f238a958a0
- STACK.md - Technologies and dependencies - ARCHITECTURE.md - System design and patterns - STRUCTURE.md - Directory layout - CONVENTIONS.md - Code style and patterns - TESTING.md - Test structure - INTEGRATIONS.md - External services - CONCERNS.md - Technical debt and issues
130 lines
4.2 KiB
Markdown
130 lines
4.2 KiB
Markdown
# 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*
|