mirror of
https://github.com/mhattingpete/personal-ai-os.git
synced 2026-11-18 18:04:27 +00:00
- Add sandbox exceptions section (git commands, uv run) - Add github.py to MCP servers table - Update watcher.py description to include GitHubPRWatcher - Add 'pai watch github' to commands list
4.0 KiB
4.0 KiB
PAI - Personal AI OS
Quick Reference
- Spec:
personal-ai-os-spec.md- Full system design - Roadmap:
ROADMAP.md- Feature roadmap and progress - Python: >=3.12 required
- Package manager:
uv
Project Structure
src/pai/ # Main application (12 modules)
pai_mcp/ # MCP server implementations
tests/ # pytest test suite
Development Principles
AI-Accelerated Development
- Flat structure - One level of nesting max, split files only when >300 lines
- CLI first - Build core logic before any UI
- Reference, don't explain - Point to spec or existing code
- Sequential depth - One phase at a time
Code Style
- Follow the Zen of Python (PEP 20)
- Pydantic v2 for all data models
- Type hints everywhere
- Async by default for I/O operations
- Line length: 100 (ruff)
Key Patterns
- LLM calls: Use
llm.pyproviders, never raw API calls - Database: Use
db.pywrapper, never raw SQL outside it - Config: Use Pydantic Settings, read from
~/.config/pai/ - CLI: Use Typer with Rich for output
- Connectors: Use MCP servers in
pai_mcp/, never direct API calls in executor - Singletons:
get_db(),get_settings(),get_mcp_manager()for global instances
File Responsibilities
| File | Purpose |
|---|---|
models.py |
Pydantic models: Automation, Entity, Execution, Triggers (Email, GitHub), Actions |
db.py |
Async SQLite wrapper (aiosqlite), schema v2, migrations |
llm.py |
LLM providers (Claude, llama.cpp) with routing and structured outputs |
intent.py |
Intent Engine: parse → clarify → plan pipeline |
executor.py |
Execution Engine: run automations via MCP, LLM email classification |
mcp.py |
MCP client manager: connect to MCP servers, route actions |
cli.py |
Typer commands: init, config, status, list, intent, connect, emails, entities, mcp |
config.py |
Pydantic Settings with YAML + env var support |
gmail.py |
Gmail OAuth client: search, labels, entity extraction |
watcher.py |
Trigger watchers: EmailWatcher, GitHubPRWatcher - poll and evaluate conditions |
MCP Servers (pai_mcp/)
| Server | Purpose |
|---|---|
gmail.py |
Gmail MCP server (FastMCP): search, get, label, archive emails |
github.py |
GitHub MCP server (FastMCP): list PRs, get reviews, format for Claude Code |
External MCP Servers (configured in ~/.config/pai/mcp.json)
| Server | Repo | Purpose |
|---|---|---|
outlook |
outlook-mcp |
Outlook emails + calendar via Microsoft Graph |
Commands
uv run pai --help # Run CLI
uv run pytest # Run tests
uv run pai intent "..." # Parse natural language intent
uv run pai init # Initialize config + database
uv run pai connect google # OAuth connect to Google
uv run pai emails "query" # Search emails
uv run pai entities # List discovered entities
uv run pai mcp list # List MCP servers
uv run pai watch github # Watch for PR reviews
Sandbox Exceptions
Always use dangerouslyDisableSandbox: true for:
- All
gitcommands (commit, push, status, etc.) uv run- Python package manager needs full filesystem access
Architecture Flow
User (CLI) → Intent Engine → Automation spec
↓
Watcher (poll triggers) → Executor → MCP Manager → MCP Servers → External APIs
↓
Database (results, state)
Configuration Paths
- Config:
~/.config/pai/config.yaml- LLM settings, routing, debug - MCP:
~/.config/pai/mcp.json- MCP server definitions - Data:
~/.local/share/pai/pai.db- SQLite database - Gmail:
~/.config/pai/google_credentials.json+google_token.json
Don'ts
- Don't create new files without asking
- Don't add dependencies without asking
- Don't nest folders deeper than
src/pai/orpai_mcp/ - Don't write documentation files unless asked
- Don't add legacy/fallback code paths - MCP-only for connectors