Mai/.planning/codebase/INTEGRATIONS.md

External Integrations

Analysis Date: 2026-01-26

APIs & External Services

Model Inference:

• LMStudio - Local model server for inference and model switching

  • SDK/Client: LMStudio Python API
  • Auth: None (local service, no authentication required)
  • Configuration: model_path env var, endpoint URL

• Ollama - Alternative local model management system

  • SDK/Client: Ollama REST API (HTTP)
  • Auth: None (local service)
  • Purpose: Model loading, switching, inference with resource detection

Communication & Approvals:

• Discord - Bot interface for conversation and change approvals
  • SDK/Client: discord.py library
  • Auth: DISCORD_BOT_TOKEN env variable
  • Purpose: Multi-turn conversations, approval reactions (thumbs up/down), status updates

Data Storage

Databases:

• SQLite3 (local file-based)
  • Connection: Local file path, no remote connection
  • Client: Python sqlite3 (stdlib) or SQLAlchemy ORM
  • Purpose: Persistent conversation history, memory compression, learned patterns
  • Location: Local filesystem (.db files)

File Storage:

• Local filesystem only - Git-tracked code changes, conversation history backups
• No cloud storage integration in v1

Caching:

• In-memory caching for current conversation context
• Redis: Not used in v1 (local-first constraint)
• Model context window management: Token-based cache within model inference

Authentication & Identity

Auth Provider:

• Custom local auth - No external identity provider
• Implementation:
  • Discord user ID as conversation context identifier
  • Optional local password/PIN for CLI access
  • No OAuth/cloud identity providers (offline-first requirement)

Monitoring & Observability

Error Tracking:

• None (local only, no error reporting service)
• Local audit logging to SQLite instead

Logs:

• File-based logging to .logs/ directory
• Format: Structured JSON logs with timestamp, level, context
• Rotation: Size-based or time-based rotation strategy
• No external log aggregation (offline-first)

CI/CD & Deployment

Hosting:

• Local machine only (desktop/laptop with RTX 3060+)
• No cloud hosting in v1

CI Pipeline:

• GitHub Actions for Discord webhook on push
  • Workflow: .github/workflows/discord_sync.yml
  • Trigger: Push events
  • Action: POST to Discord webhook for notification

Git Integration:

• All Mai's self-modifications committed automatically with git
• Local git repo tracking all code changes
• Commit messages include decision context and review results

Environment Configuration

Required env vars:

• DISCORD_BOT_TOKEN - Discord bot authentication
• LMSTUDIO_ENDPOINT - LMStudio API URL (default: localhost:8000)
• OLLAMA_ENDPOINT - Ollama API URL (optional alternative, default: localhost:11434)
• DISCORD_USER_ID - User Discord ID for approval requests
• MEMORY_DB_PATH - SQLite database file location
• MODEL_CACHE_DIR - Directory for model files
• CPU_CORES_AVAILABLE - System CPU count for resource management
• GPU_VRAM_AVAILABLE - VRAM in GB for model selection
• SANDBOX_DOCKER_IMAGE - Docker image ID for code sandbox execution

Secrets location:

• .env file (Python-dotenv) for local development
• Environment variables for production/runtime
• Git-ignored: .env not committed

Webhooks & Callbacks

Incoming:

• Discord message webhooks - Handled by discord.py bot event listeners
• No external webhook endpoints in v1

Outgoing:

• Discord webhook for git notifications (configured in GitHub Actions)
• Endpoint: Stored in GitHub secrets as WEBHOOK
• Triggered on: git push events
• Payload: Git commit information (author, message, timestamp)

Model Callback Handling:

• LMStudio streaming callbacks for token-by-token responses
• Ollama streaming responses for incremental model output

Code Execution Sandbox

Sandbox Environment:

• Docker container with resource limits
  • SDK: Docker SDK for Python (docker-py)
  • Environment: Isolated Linux container
  • Resource limits: CPU cores, RAM, network restrictions

Risk Assessment:

• Multi-level risk evaluation (LOW/MEDIUM/HIGH/BLOCKED)
• AST validation before container execution
• Second-agent review via Claude/OpenCode API

---

Integration audit: 2026-01-26