Initial commit: PAI Phase 1 foundation

- Flat project structure with uv package management
- Pydantic models for Automation, Entity, Execution, Intent
- Async SQLite database wrapper with full schema
- LLM provider abstraction (Claude + llama.cpp)
- Typer CLI with init/config/status/list/intent commands
- Pydantic Settings for type-safe configuration
This commit is contained in:
mhattingpete
2026-01-21 10:22:06 +01:00
commit 6f2958ede5
13 changed files with 3015 additions and 0 deletions
+43
View File
@@ -0,0 +1,43 @@
# Python
__pycache__/
*.py[cod]
*$py.class
*.so
.Python
build/
develop-eggs/
dist/
downloads/
eggs/
.eggs/
lib/
lib64/
parts/
sdist/
var/
wheels/
*.egg-info/
.installed.cfg
*.egg
# Virtual environments
.venv/
venv/
ENV/
# IDE
.idea/
.vscode/
*.swp
*.swo
# Testing
.pytest_cache/
.coverage
htmlcov/
# uv
uv.lock
# Local data (don't commit user data)
*.db
+49
View File
@@ -0,0 +1,49 @@
# PAI - Personal AI OS
## Quick Reference
- **Spec:** `personal-ai-os-spec.md` - Full system design
- **Patterns:** `docs/patterns.md` - Code patterns to follow
## Development Principles
### AI-Accelerated Development
1. **Flat structure** - One level of nesting max, split files only when >300 lines
2. **CLI first** - Build core logic before any UI
3. **Reference, don't explain** - Point to spec or existing code
4. **Sequential depth** - One phase at a time
### Code Style
- Follow the Zen of Python (PEP 20)
- Pydantic for all data models
- Type hints everywhere
- Async by default for I/O operations
### Key Patterns
- **LLM calls:** Use `llm.py` providers, never raw API calls
- **Database:** Use `db.py` wrapper, never raw SQL outside it
- **Config:** Use Pydantic Settings, read from `~/.config/pai/`
- **CLI:** Use Typer with Rich for output
### File Responsibilities
| File | Purpose |
|------|---------|
| `models.py` | Pydantic models: Automation, Entity, Execution, etc. |
| `db.py` | SQLite wrapper, schema, migrations |
| `llm.py` | LLM providers (Claude, llama.cpp) |
| `intent.py` | Intent Engine: parse → clarify → plan |
| `cli.py` | Typer commands |
| `config.py` | Settings management |
| `gmail.py` | Gmail connector (Phase 3) |
### Commands
```bash
uv run pai --help # Run CLI
uv run pytest # Run tests
uv run pai intent "..." # Parse natural language intent
```
### Don'ts
- Don't create new files without asking
- Don't add dependencies without asking
- Don't nest folders deeper than `src/pai/`
- Don't write documentation files unless asked
File diff suppressed because it is too large Load Diff
+43
View File
@@ -0,0 +1,43 @@
[project]
name = "pai"
version = "0.1.0"
description = "Personal AI Operating System - automate your digital life with natural language"
requires-python = ">=3.12"
dependencies = [
"typer>=0.15.0",
"rich>=13.0.0",
"pydantic>=2.10.0",
"pydantic-settings>=2.7.0",
"httpx>=0.28.0",
"anthropic>=0.43.0",
"aiosqlite>=0.20.0",
"pyyaml>=6.0.0",
]
[project.optional-dependencies]
dev = [
"pytest>=8.0.0",
"pytest-asyncio>=0.25.0",
"ruff>=0.9.0",
]
[project.scripts]
pai = "pai.cli:app"
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"
[tool.hatch.build.targets.wheel]
packages = ["src/pai"]
[tool.pytest.ini_options]
asyncio_mode = "auto"
testpaths = ["tests"]
[tool.ruff]
line-length = 100
target-version = "py312"
[tool.ruff.lint]
select = ["E", "F", "I", "UP", "B", "SIM"]
+6
View File
@@ -0,0 +1,6 @@
"""PAI - Personal AI Operating System.
Automate your digital life with natural language.
"""
__version__ = "0.1.0"
+9
View File
@@ -0,0 +1,9 @@
"""Entry point for running PAI as a module.
Usage: python -m pai
"""
from pai.cli import app
if __name__ == "__main__":
app()
+237
View File
@@ -0,0 +1,237 @@
"""CLI entry point for PAI.
Uses Typer for command parsing and Rich for output.
Run with: uv run pai --help
"""
import asyncio
from typing import Annotated, Optional
import typer
from rich.console import Console
from rich.panel import Panel
from rich.table import Table
from pai.config import get_config_dir, get_data_dir, get_settings
from pai.db import init_db
from pai.models import AutomationStatus
app = typer.Typer(
name="pai",
help="Personal AI OS - automate your digital life with natural language",
no_args_is_help=True,
)
console = Console()
def run_async(coro):
"""Run an async function in the event loop."""
return asyncio.run(coro)
@app.callback()
def callback(
debug: Annotated[
bool, typer.Option("--debug", "-d", help="Enable debug output")
] = False,
):
"""PAI - Personal AI Operating System."""
if debug:
console.print("[dim]Debug mode enabled[/dim]")
@app.command()
def init():
"""Initialize PAI (create config and database)."""
async def _init():
# Show paths
config_dir = get_config_dir()
data_dir = get_data_dir()
console.print(Panel.fit(
f"[bold]Config:[/bold] {config_dir}\n"
f"[bold]Data:[/bold] {data_dir}",
title="PAI Directories",
))
# Initialize database
db = await init_db()
console.print("[green]✓[/green] Database initialized")
# Check for API key
settings = get_settings()
if settings.llm.claude.api_key:
console.print("[green]✓[/green] Claude API key configured")
else:
console.print(
"[yellow]![/yellow] Claude API key not set. "
"Set ANTHROPIC_API_KEY or add to ~/.config/pai/config.yaml"
)
await db.close()
console.print("\n[bold green]PAI initialized![/bold green]")
run_async(_init())
@app.command()
def config(
show: Annotated[
bool, typer.Option("--show", "-s", help="Show current configuration")
] = False,
):
"""Manage PAI configuration."""
settings = get_settings()
if show:
table = Table(title="PAI Configuration")
table.add_column("Setting", style="cyan")
table.add_column("Value", style="green")
table.add_row("LLM Default", settings.llm.default)
table.add_row("Claude Model", settings.llm.claude.model)
table.add_row(
"Claude API Key",
"***" + settings.llm.claude.api_key[-4:]
if settings.llm.claude.api_key
else "[red]Not set[/red]",
)
table.add_row("Local LLM URL", settings.llm.local.url)
table.add_row("Database Path", str(settings.db.path))
table.add_row("Debug Mode", str(settings.debug))
console.print(table)
else:
console.print(f"Config directory: {get_config_dir()}")
console.print("Use --show to display current configuration")
@app.command()
def status():
"""Show PAI status."""
async def _status():
from pai.db import get_db
db = get_db()
try:
# Check database
await db.initialize()
automations = await db.list_automations()
active_count = len([a for a in automations if a.status == AutomationStatus.ACTIVE])
connectors = await db.list_connectors()
console.print(Panel.fit(
f"[bold]Automations:[/bold] {len(automations)} total, {active_count} active\n"
f"[bold]Connectors:[/bold] {len(connectors)} connected",
title="PAI Status",
))
finally:
await db.close()
run_async(_status())
# =============================================================================
# Automation commands (scaffolding for Phase 4)
# =============================================================================
@app.command("list")
def list_automations(
status: Annotated[
Optional[str],
typer.Option("--status", "-s", help="Filter by status (draft, active, paused, error)"),
] = None,
):
"""List all automations."""
async def _list():
from pai.db import get_db
db = get_db()
await db.initialize()
try:
filter_status = AutomationStatus(status) if status else None
automations = await db.list_automations(status=filter_status)
if not automations:
console.print("[dim]No automations found[/dim]")
return
table = Table(title="Automations")
table.add_column("ID", style="cyan", max_width=12)
table.add_column("Name", style="bold")
table.add_column("Status", style="green")
table.add_column("Trigger")
table.add_column("Updated")
for auto in automations:
status_style = {
AutomationStatus.ACTIVE: "[green]active[/green]",
AutomationStatus.DRAFT: "[yellow]draft[/yellow]",
AutomationStatus.PAUSED: "[blue]paused[/blue]",
AutomationStatus.ERROR: "[red]error[/red]",
}.get(auto.status, str(auto.status))
table.add_row(
auto.id[:12],
auto.name,
status_style,
auto.trigger.type,
auto.updated_at.strftime("%Y-%m-%d %H:%M"),
)
console.print(table)
finally:
await db.close()
run_async(_list())
# =============================================================================
# Intent command (scaffolding for Phase 2)
# =============================================================================
@app.command()
def intent(
text: Annotated[str, typer.Argument(help="Natural language intent to parse")],
):
"""Parse a natural language intent into an automation spec.
Example:
pai intent "When a client emails me with an invoice, save it to their folder"
"""
console.print(Panel.fit(
f"[bold]Input:[/bold] {text}",
title="Intent Parsing",
))
console.print("\n[dim]Intent engine not yet implemented (Phase 2)[/dim]")
console.print("[dim]This command will parse natural language and create automation specs[/dim]")
# =============================================================================
# Connect command (scaffolding for Phase 3)
# =============================================================================
@app.command()
def connect(
service: Annotated[str, typer.Argument(help="Service to connect (google, notion, etc.)")],
):
"""Connect to an external service.
Example:
pai connect google
"""
console.print(f"[dim]Connector for '{service}' not yet implemented (Phase 3)[/dim]")
if __name__ == "__main__":
app()
+125
View File
@@ -0,0 +1,125 @@
"""Configuration management for PAI.
Uses Pydantic Settings for type-safe config with env var support.
Config is read from ~/.config/pai/config.yaml with env overrides.
"""
from pathlib import Path
from typing import Any
import yaml
from pydantic import Field
from pydantic_settings import BaseSettings, SettingsConfigDict
def get_config_dir() -> Path:
"""Get the PAI config directory, creating it if needed."""
config_dir = Path.home() / ".config" / "pai"
config_dir.mkdir(parents=True, exist_ok=True)
return config_dir
def get_data_dir() -> Path:
"""Get the PAI data directory, creating it if needed."""
data_dir = Path.home() / ".local" / "share" / "pai"
data_dir.mkdir(parents=True, exist_ok=True)
return data_dir
class ClaudeSettings(BaseSettings):
"""Claude API settings."""
api_key: str = ""
model: str = "claude-sonnet-4-20250514"
model_config = SettingsConfigDict(env_prefix="ANTHROPIC_")
class LocalLLMSettings(BaseSettings):
"""Local LLM (llama.cpp) settings."""
url: str = "http://localhost:8080"
model: str = "default"
model_config = SettingsConfigDict(env_prefix="PAI_LOCAL_")
class LLMRoutingSettings(BaseSettings):
"""LLM routing configuration."""
sensitive_domains: list[str] = Field(default_factory=lambda: ["health", "finance", "personal"])
force_local: bool = False
model_config = SettingsConfigDict(env_prefix="PAI_ROUTING_")
class LLMSettings(BaseSettings):
"""LLM provider settings."""
default: str = "claude"
claude: ClaudeSettings = Field(default_factory=ClaudeSettings)
local: LocalLLMSettings = Field(default_factory=LocalLLMSettings)
routing: LLMRoutingSettings = Field(default_factory=LLMRoutingSettings)
model_config = SettingsConfigDict(env_prefix="PAI_LLM_")
class DatabaseSettings(BaseSettings):
"""Database settings."""
path: Path = Field(default_factory=lambda: get_data_dir() / "pai.db")
model_config = SettingsConfigDict(env_prefix="PAI_DB_")
class Settings(BaseSettings):
"""Main application settings."""
llm: LLMSettings = Field(default_factory=LLMSettings)
db: DatabaseSettings = Field(default_factory=DatabaseSettings)
debug: bool = False
model_config = SettingsConfigDict(
env_prefix="PAI_",
env_nested_delimiter="__",
)
@classmethod
def from_yaml(cls, path: Path | None = None) -> "Settings":
"""Load settings from YAML file, with env overrides."""
if path is None:
path = get_config_dir() / "config.yaml"
data: dict[str, Any] = {}
if path.exists():
with open(path) as f:
data = yaml.safe_load(f) or {}
return cls(**data)
def save(self, path: Path | None = None) -> None:
"""Save settings to YAML file."""
if path is None:
path = get_config_dir() / "config.yaml"
with open(path, "w") as f:
yaml.dump(self.model_dump(mode="json"), f, default_flow_style=False)
# Global settings instance, lazily loaded
_settings: Settings | None = None
def get_settings() -> Settings:
"""Get the global settings instance."""
global _settings
if _settings is None:
_settings = Settings.from_yaml()
return _settings
def reload_settings() -> Settings:
"""Reload settings from disk."""
global _settings
_settings = Settings.from_yaml()
return _settings
+505
View File
@@ -0,0 +1,505 @@
"""SQLite database wrapper for PAI.
All database operations go through this module.
Uses aiosqlite for async operations.
"""
import json
from contextlib import asynccontextmanager
from datetime import datetime
from pathlib import Path
from typing import Any, AsyncIterator
import aiosqlite
from pai.config import get_settings
from pai.models import (
Automation,
AutomationStatus,
Connector,
ConnectorStatus,
ConnectorType,
Entity,
EntityType,
Execution,
ExecutionStatus,
IntentGraph,
)
# Schema version for migrations
SCHEMA_VERSION = 1
SCHEMA = """
-- Schema version tracking
CREATE TABLE IF NOT EXISTS schema_version (
version INTEGER PRIMARY KEY
);
-- Connectors (user's connected accounts)
CREATE TABLE IF NOT EXISTS connectors (
id TEXT PRIMARY KEY,
type TEXT NOT NULL,
account_id TEXT NOT NULL,
status TEXT NOT NULL DEFAULT 'active',
credentials_encrypted TEXT,
last_sync TEXT,
schema_json TEXT,
created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
UNIQUE(type, account_id)
);
-- Entities (clients, projects, etc. discovered from data)
CREATE TABLE IF NOT EXISTS entities (
id TEXT PRIMARY KEY,
type TEXT NOT NULL,
name TEXT NOT NULL,
aliases_json TEXT DEFAULT '[]',
metadata_json TEXT DEFAULT '{}',
sources_json TEXT DEFAULT '[]',
created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
updated_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
);
CREATE INDEX IF NOT EXISTS idx_entities_type ON entities(type);
CREATE INDEX IF NOT EXISTS idx_entities_name ON entities(name);
-- Automations
CREATE TABLE IF NOT EXISTS automations (
id TEXT PRIMARY KEY,
name TEXT NOT NULL,
description TEXT DEFAULT '',
status TEXT NOT NULL DEFAULT 'draft',
trigger_json TEXT NOT NULL,
variables_json TEXT DEFAULT '[]',
actions_json TEXT DEFAULT '[]',
error_handling_json TEXT DEFAULT '[]',
monitoring_json TEXT DEFAULT '{}',
capabilities_json TEXT DEFAULT '[]',
created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
updated_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
version INTEGER NOT NULL DEFAULT 1
);
CREATE INDEX IF NOT EXISTS idx_automations_status ON automations(status);
-- Executions
CREATE TABLE IF NOT EXISTS executions (
id TEXT PRIMARY KEY,
automation_id TEXT NOT NULL,
automation_version INTEGER NOT NULL,
triggered_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
completed_at TEXT,
status TEXT NOT NULL DEFAULT 'running',
trigger_event_json TEXT NOT NULL,
variables_json TEXT DEFAULT '[]',
action_results_json TEXT DEFAULT '[]',
error_json TEXT,
FOREIGN KEY (automation_id) REFERENCES automations(id)
);
CREATE INDEX IF NOT EXISTS idx_executions_automation ON executions(automation_id);
CREATE INDEX IF NOT EXISTS idx_executions_status ON executions(status);
CREATE INDEX IF NOT EXISTS idx_executions_triggered_at ON executions(triggered_at);
-- Intent graphs (parsed intents, for learning)
CREATE TABLE IF NOT EXISTS intents (
id TEXT PRIMARY KEY,
type TEXT NOT NULL DEFAULT 'automation',
confidence REAL NOT NULL DEFAULT 1.0,
trigger_json TEXT,
actions_json TEXT DEFAULT '[]',
ambiguities_json TEXT DEFAULT '[]',
raw_input TEXT NOT NULL,
created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
);
-- Conversations
CREATE TABLE IF NOT EXISTS conversations (
id TEXT PRIMARY KEY,
messages_json TEXT DEFAULT '[]',
context_json TEXT DEFAULT '{}',
created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
updated_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
);
"""
class Database:
"""Async SQLite database wrapper."""
def __init__(self, path: Path | None = None):
self.path = path or get_settings().db.path
self._conn: aiosqlite.Connection | None = None
@asynccontextmanager
async def connection(self) -> AsyncIterator[aiosqlite.Connection]:
"""Get a database connection."""
if self._conn is None:
self._conn = await aiosqlite.connect(self.path)
self._conn.row_factory = aiosqlite.Row
yield self._conn
async def close(self) -> None:
"""Close the database connection."""
if self._conn:
await self._conn.close()
self._conn = None
async def initialize(self) -> None:
"""Initialize the database schema."""
async with self.connection() as conn:
await conn.executescript(SCHEMA)
# Set schema version
await conn.execute(
"INSERT OR REPLACE INTO schema_version (version) VALUES (?)",
(SCHEMA_VERSION,),
)
await conn.commit()
# =========================================================================
# Connectors
# =========================================================================
async def save_connector(self, connector: Connector) -> None:
"""Save a connector."""
async with self.connection() as conn:
await conn.execute(
"""
INSERT OR REPLACE INTO connectors
(id, type, account_id, status, last_sync, schema_json, created_at)
VALUES (?, ?, ?, ?, ?, ?, ?)
""",
(
connector.id,
connector.type.value,
connector.account_id,
connector.status.value,
connector.last_sync.isoformat() if connector.last_sync else None,
connector.schema_.model_dump_json() if connector.schema_ else None,
connector.created_at.isoformat(),
),
)
await conn.commit()
async def get_connector(self, connector_id: str) -> Connector | None:
"""Get a connector by ID."""
async with self.connection() as conn:
cursor = await conn.execute(
"SELECT * FROM connectors WHERE id = ?", (connector_id,)
)
row = await cursor.fetchone()
if not row:
return None
return self._row_to_connector(row)
async def list_connectors(
self, status: ConnectorStatus | None = None
) -> list[Connector]:
"""List all connectors, optionally filtered by status."""
async with self.connection() as conn:
if status:
cursor = await conn.execute(
"SELECT * FROM connectors WHERE status = ?", (status.value,)
)
else:
cursor = await conn.execute("SELECT * FROM connectors")
rows = await cursor.fetchall()
return [self._row_to_connector(row) for row in rows]
def _row_to_connector(self, row: aiosqlite.Row) -> Connector:
"""Convert a database row to a Connector model."""
return Connector(
id=row["id"],
type=ConnectorType(row["type"]),
account_id=row["account_id"],
status=ConnectorStatus(row["status"]),
last_sync=datetime.fromisoformat(row["last_sync"]) if row["last_sync"] else None,
schema=json.loads(row["schema_json"]) if row["schema_json"] else None,
created_at=datetime.fromisoformat(row["created_at"]),
)
# =========================================================================
# Entities
# =========================================================================
async def save_entity(self, entity: Entity) -> None:
"""Save an entity."""
async with self.connection() as conn:
await conn.execute(
"""
INSERT OR REPLACE INTO entities
(id, type, name, aliases_json, metadata_json, sources_json, created_at, updated_at)
VALUES (?, ?, ?, ?, ?, ?, ?, ?)
""",
(
entity.id,
entity.type.value,
entity.name,
json.dumps(entity.aliases),
json.dumps(entity.metadata),
json.dumps([s.model_dump(mode="json") for s in entity.sources]),
entity.created_at.isoformat(),
datetime.now().isoformat(),
),
)
await conn.commit()
async def get_entity(self, entity_id: str) -> Entity | None:
"""Get an entity by ID."""
async with self.connection() as conn:
cursor = await conn.execute(
"SELECT * FROM entities WHERE id = ?", (entity_id,)
)
row = await cursor.fetchone()
if not row:
return None
return self._row_to_entity(row)
async def list_entities(
self, entity_type: EntityType | None = None
) -> list[Entity]:
"""List all entities, optionally filtered by type."""
async with self.connection() as conn:
if entity_type:
cursor = await conn.execute(
"SELECT * FROM entities WHERE type = ?", (entity_type.value,)
)
else:
cursor = await conn.execute("SELECT * FROM entities")
rows = await cursor.fetchall()
return [self._row_to_entity(row) for row in rows]
def _row_to_entity(self, row: aiosqlite.Row) -> Entity:
"""Convert a database row to an Entity model."""
return Entity(
id=row["id"],
type=EntityType(row["type"]),
name=row["name"],
aliases=json.loads(row["aliases_json"]),
metadata=json.loads(row["metadata_json"]),
sources=json.loads(row["sources_json"]),
created_at=datetime.fromisoformat(row["created_at"]),
updated_at=datetime.fromisoformat(row["updated_at"]),
)
# =========================================================================
# Automations
# =========================================================================
async def save_automation(self, automation: Automation) -> None:
"""Save an automation."""
async with self.connection() as conn:
await conn.execute(
"""
INSERT OR REPLACE INTO automations
(id, name, description, status, trigger_json, variables_json, actions_json,
error_handling_json, monitoring_json, capabilities_json, created_at, updated_at, version)
VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
""",
(
automation.id,
automation.name,
automation.description,
automation.status.value,
automation.trigger.model_dump_json(),
json.dumps([v.model_dump(mode="json") for v in automation.variables]),
json.dumps([a.model_dump(mode="json") for a in automation.actions]),
json.dumps([e.model_dump(mode="json") for e in automation.error_handling]),
automation.monitoring.model_dump_json(),
json.dumps([c.model_dump(mode="json") for c in automation.capabilities]),
automation.created_at.isoformat(),
datetime.now().isoformat(),
automation.version,
),
)
await conn.commit()
async def get_automation(self, automation_id: str) -> Automation | None:
"""Get an automation by ID."""
async with self.connection() as conn:
cursor = await conn.execute(
"SELECT * FROM automations WHERE id = ?", (automation_id,)
)
row = await cursor.fetchone()
if not row:
return None
return self._row_to_automation(row)
async def list_automations(
self, status: AutomationStatus | None = None
) -> list[Automation]:
"""List all automations, optionally filtered by status."""
async with self.connection() as conn:
if status:
cursor = await conn.execute(
"SELECT * FROM automations WHERE status = ? ORDER BY updated_at DESC",
(status.value,),
)
else:
cursor = await conn.execute(
"SELECT * FROM automations ORDER BY updated_at DESC"
)
rows = await cursor.fetchall()
return [self._row_to_automation(row) for row in rows]
def _row_to_automation(self, row: aiosqlite.Row) -> Automation:
"""Convert a database row to an Automation model."""
trigger_data = json.loads(row["trigger_json"])
return Automation(
id=row["id"],
name=row["name"],
description=row["description"],
status=AutomationStatus(row["status"]),
trigger=trigger_data,
variables=json.loads(row["variables_json"]),
actions=json.loads(row["actions_json"]),
error_handling=json.loads(row["error_handling_json"]),
monitoring=json.loads(row["monitoring_json"]),
capabilities=json.loads(row["capabilities_json"]),
created_at=datetime.fromisoformat(row["created_at"]),
updated_at=datetime.fromisoformat(row["updated_at"]),
version=row["version"],
)
# =========================================================================
# Executions
# =========================================================================
async def save_execution(self, execution: Execution) -> None:
"""Save an execution."""
async with self.connection() as conn:
await conn.execute(
"""
INSERT OR REPLACE INTO executions
(id, automation_id, automation_version, triggered_at, completed_at, status,
trigger_event_json, variables_json, action_results_json, error_json)
VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
""",
(
execution.id,
execution.automation_id,
execution.automation_version,
execution.triggered_at.isoformat(),
execution.completed_at.isoformat() if execution.completed_at else None,
execution.status.value,
execution.trigger_event.model_dump_json(),
json.dumps([v.model_dump(mode="json") for v in execution.variables]),
json.dumps([r.model_dump(mode="json") for r in execution.action_results]),
execution.error.model_dump_json() if execution.error else None,
),
)
await conn.commit()
async def get_execution(self, execution_id: str) -> Execution | None:
"""Get an execution by ID."""
async with self.connection() as conn:
cursor = await conn.execute(
"SELECT * FROM executions WHERE id = ?", (execution_id,)
)
row = await cursor.fetchone()
if not row:
return None
return self._row_to_execution(row)
async def list_executions(
self,
automation_id: str | None = None,
status: ExecutionStatus | None = None,
limit: int = 100,
) -> list[Execution]:
"""List executions with optional filters."""
async with self.connection() as conn:
query = "SELECT * FROM executions WHERE 1=1"
params: list[Any] = []
if automation_id:
query += " AND automation_id = ?"
params.append(automation_id)
if status:
query += " AND status = ?"
params.append(status.value)
query += " ORDER BY triggered_at DESC LIMIT ?"
params.append(limit)
cursor = await conn.execute(query, params)
rows = await cursor.fetchall()
return [self._row_to_execution(row) for row in rows]
def _row_to_execution(self, row: aiosqlite.Row) -> Execution:
"""Convert a database row to an Execution model."""
return Execution(
id=row["id"],
automation_id=row["automation_id"],
automation_version=row["automation_version"],
triggered_at=datetime.fromisoformat(row["triggered_at"]),
completed_at=(
datetime.fromisoformat(row["completed_at"]) if row["completed_at"] else None
),
status=ExecutionStatus(row["status"]),
trigger_event=json.loads(row["trigger_event_json"]),
variables=json.loads(row["variables_json"]),
action_results=json.loads(row["action_results_json"]),
error=json.loads(row["error_json"]) if row["error_json"] else None,
)
# =========================================================================
# Intents
# =========================================================================
async def save_intent(self, intent: IntentGraph) -> None:
"""Save an intent graph."""
async with self.connection() as conn:
await conn.execute(
"""
INSERT OR REPLACE INTO intents
(id, type, confidence, trigger_json, actions_json, ambiguities_json, raw_input, created_at)
VALUES (?, ?, ?, ?, ?, ?, ?, ?)
""",
(
intent.id,
intent.type,
intent.confidence,
intent.trigger.model_dump_json() if intent.trigger else None,
json.dumps([a.model_dump(mode="json") for a in intent.actions]),
json.dumps([a.model_dump(mode="json") for a in intent.ambiguities]),
intent.raw_input,
datetime.now().isoformat(),
),
)
await conn.commit()
async def get_intent(self, intent_id: str) -> IntentGraph | None:
"""Get an intent by ID."""
async with self.connection() as conn:
cursor = await conn.execute(
"SELECT * FROM intents WHERE id = ?", (intent_id,)
)
row = await cursor.fetchone()
if not row:
return None
return IntentGraph(
id=row["id"],
type=row["type"],
confidence=row["confidence"],
trigger=json.loads(row["trigger_json"]) if row["trigger_json"] else None,
actions=json.loads(row["actions_json"]),
ambiguities=json.loads(row["ambiguities_json"]),
raw_input=row["raw_input"],
)
# Global database instance
_db: Database | None = None
def get_db() -> Database:
"""Get the global database instance."""
global _db
if _db is None:
_db = Database()
return _db
async def init_db() -> Database:
"""Initialize the database and return the instance."""
db = get_db()
await db.initialize()
return db
+297
View File
@@ -0,0 +1,297 @@
"""LLM provider abstraction for PAI.
Supports both Claude API and local llama.cpp server.
All LLM calls should go through this module.
"""
import json
from typing import Any, Protocol, TypeVar
import anthropic
import httpx
from pydantic import BaseModel
from pai.config import get_settings
T = TypeVar("T", bound=BaseModel)
class Message(BaseModel):
"""Chat message."""
role: str # "user", "assistant", or "system"
content: str
class Response(BaseModel):
"""LLM response."""
content: str
model: str
usage: dict[str, int] | None = None
stop_reason: str | None = None
class LLMProvider(Protocol):
"""Protocol for LLM providers."""
async def complete(
self,
messages: list[Message],
*,
system: str | None = None,
max_tokens: int = 4096,
temperature: float = 0.7,
) -> Response:
"""Generate a completion from messages."""
...
async def complete_structured(
self,
messages: list[Message],
schema: type[T],
*,
system: str | None = None,
max_tokens: int = 4096,
temperature: float = 0.0,
) -> T:
"""Generate a structured response matching the schema."""
...
class ClaudeProvider:
"""Claude API provider using the Anthropic SDK."""
def __init__(self, api_key: str | None = None, model: str | None = None):
settings = get_settings().llm.claude
self.api_key = api_key or settings.api_key
self.model = model or settings.model
if not self.api_key:
raise ValueError(
"Claude API key not set. Set ANTHROPIC_API_KEY env var or configure in ~/.config/pai/config.yaml"
)
self.client = anthropic.AsyncAnthropic(api_key=self.api_key)
async def complete(
self,
messages: list[Message],
*,
system: str | None = None,
max_tokens: int = 4096,
temperature: float = 0.7,
) -> Response:
"""Generate a completion from messages."""
# Convert messages to Anthropic format
anthropic_messages = [
{"role": m.role, "content": m.content}
for m in messages
if m.role != "system"
]
# Build system prompt from system messages
system_parts = [m.content for m in messages if m.role == "system"]
if system:
system_parts.insert(0, system)
system_prompt = "\n\n".join(system_parts) if system_parts else None
response = await self.client.messages.create(
model=self.model,
max_tokens=max_tokens,
temperature=temperature,
system=system_prompt or anthropic.NOT_GIVEN,
messages=anthropic_messages,
)
return Response(
content=response.content[0].text if response.content else "",
model=response.model,
usage={
"input_tokens": response.usage.input_tokens,
"output_tokens": response.usage.output_tokens,
},
stop_reason=response.stop_reason,
)
async def complete_structured(
self,
messages: list[Message],
schema: type[T],
*,
system: str | None = None,
max_tokens: int = 4096,
temperature: float = 0.0,
) -> T:
"""Generate a structured response matching the schema."""
# Build schema description
schema_json = schema.model_json_schema()
schema_str = json.dumps(schema_json, indent=2)
# Augment system prompt with schema instructions
schema_instruction = f"""You must respond with valid JSON that matches this schema:
{schema_str}
Respond ONLY with the JSON object, no markdown code blocks or explanations."""
full_system = f"{system}\n\n{schema_instruction}" if system else schema_instruction
response = await self.complete(
messages,
system=full_system,
max_tokens=max_tokens,
temperature=temperature,
)
# Parse and validate response
content = response.content.strip()
# Remove markdown code blocks if present
if content.startswith("```"):
lines = content.split("\n")
content = "\n".join(lines[1:-1] if lines[-1] == "```" else lines[1:])
data = json.loads(content)
return schema.model_validate(data)
class LlamaCppProvider:
"""Local llama.cpp server provider via OpenAI-compatible API."""
def __init__(self, url: str | None = None, model: str | None = None):
settings = get_settings().llm.local
self.url = (url or settings.url).rstrip("/")
self.model = model or settings.model
self.client = httpx.AsyncClient(timeout=120.0)
async def complete(
self,
messages: list[Message],
*,
system: str | None = None,
max_tokens: int = 4096,
temperature: float = 0.7,
) -> Response:
"""Generate a completion from messages."""
# Build messages list with system prompt
api_messages: list[dict[str, str]] = []
if system:
api_messages.append({"role": "system", "content": system})
for m in messages:
api_messages.append({"role": m.role, "content": m.content})
response = await self.client.post(
f"{self.url}/v1/chat/completions",
json={
"model": self.model,
"messages": api_messages,
"max_tokens": max_tokens,
"temperature": temperature,
},
)
response.raise_for_status()
data = response.json()
choice = data["choices"][0]
return Response(
content=choice["message"]["content"],
model=data.get("model", self.model),
usage=data.get("usage"),
stop_reason=choice.get("finish_reason"),
)
async def complete_structured(
self,
messages: list[Message],
schema: type[T],
*,
system: str | None = None,
max_tokens: int = 4096,
temperature: float = 0.0,
) -> T:
"""Generate a structured response matching the schema."""
# Build schema description
schema_json = schema.model_json_schema()
schema_str = json.dumps(schema_json, indent=2)
schema_instruction = f"""You must respond with valid JSON that matches this schema:
{schema_str}
Respond ONLY with the JSON object, no markdown code blocks or explanations."""
full_system = f"{system}\n\n{schema_instruction}" if system else schema_instruction
# Build messages list
api_messages: list[dict[str, str]] = [
{"role": "system", "content": full_system}
]
for m in messages:
api_messages.append({"role": m.role, "content": m.content})
# Request with JSON mode if supported
response = await self.client.post(
f"{self.url}/v1/chat/completions",
json={
"model": self.model,
"messages": api_messages,
"max_tokens": max_tokens,
"temperature": temperature,
"response_format": {"type": "json_object"},
},
)
response.raise_for_status()
data = response.json()
content = data["choices"][0]["message"]["content"]
parsed = json.loads(content)
return schema.model_validate(parsed)
async def close(self) -> None:
"""Close the HTTP client."""
await self.client.aclose()
def get_provider(name: str | None = None) -> LLMProvider:
"""Get an LLM provider by name.
Args:
name: Provider name ("claude" or "local"). Defaults to config setting.
Returns:
Configured LLM provider.
"""
settings = get_settings().llm
provider_name = name or settings.default
if provider_name == "claude":
return ClaudeProvider()
elif provider_name == "local":
return LlamaCppProvider()
else:
raise ValueError(f"Unknown LLM provider: {provider_name}")
def should_use_local(context: dict[str, Any] | None = None) -> bool:
"""Determine if local model should be used based on routing rules.
Args:
context: Optional context with "domains" key listing data domains involved.
Returns:
True if local model should be used.
"""
settings = get_settings().llm.routing
# User override: always use local
if settings.force_local:
return True
# Check if any sensitive domains are involved
if context and "domains" in context:
for domain in context["domains"]:
if domain.lower() in settings.sensitive_domains:
return True
return False
+494
View File
@@ -0,0 +1,494 @@
"""Core data models for PAI.
Translated from TypeScript interfaces in personal-ai-os-spec.md.
All models use Pydantic v2 for validation and serialization.
"""
from datetime import datetime
from enum import Enum
from typing import Any, Literal
from pydantic import BaseModel, Field
# =============================================================================
# Enums
# =============================================================================
class ConnectorType(str, Enum):
"""Supported connector types."""
GMAIL = "gmail"
GOOGLE_SHEETS = "google_sheets"
GOOGLE_DRIVE = "google_drive"
GOOGLE_CONTACTS = "google_contacts"
GOOGLE_CALENDAR = "google_calendar"
DROPBOX = "dropbox"
NOTION = "notion"
SLACK = "slack"
class ConnectorStatus(str, Enum):
"""Connector connection status."""
ACTIVE = "active"
EXPIRED = "expired"
ERROR = "error"
class EntityType(str, Enum):
"""Types of entities extracted from user data."""
CLIENT = "client"
PROJECT = "project"
PERSON = "person"
FOLDER = "folder"
SPREADSHEET = "spreadsheet"
class AutomationStatus(str, Enum):
"""Automation lifecycle status."""
DRAFT = "draft"
ACTIVE = "active"
PAUSED = "paused"
ERROR = "error"
class ExecutionStatus(str, Enum):
"""Execution result status."""
RUNNING = "running"
SUCCESS = "success"
PARTIAL = "partial"
FAILED = "failed"
class LearningEventType(str, Enum):
"""Types of learning signals."""
CORRECTION = "correction"
UNDO = "undo"
FEEDBACK = "feedback"
PATTERN = "pattern"
# =============================================================================
# Connectors
# =============================================================================
class ConnectorSchema(BaseModel):
"""Schema discovered from a connector's data."""
fields: dict[str, str] = Field(default_factory=dict)
sample_data: list[dict[str, Any]] = Field(default_factory=list)
class Connector(BaseModel):
"""User's connected account."""
id: str
type: ConnectorType
account_id: str
status: ConnectorStatus = ConnectorStatus.ACTIVE
last_sync: datetime | None = None
schema_: ConnectorSchema | None = Field(default=None, alias="schema")
created_at: datetime = Field(default_factory=datetime.now)
# =============================================================================
# Entities
# =============================================================================
class EntitySource(BaseModel):
"""Where an entity was discovered."""
connector_id: str
field: str
value: str
discovered_at: datetime = Field(default_factory=datetime.now)
class Entity(BaseModel):
"""Known entity extracted from user's data."""
id: str
type: EntityType
name: str
aliases: list[str] = Field(default_factory=list)
metadata: dict[str, Any] = Field(default_factory=dict)
sources: list[EntitySource] = Field(default_factory=list)
created_at: datetime = Field(default_factory=datetime.now)
updated_at: datetime = Field(default_factory=datetime.now)
# =============================================================================
# Triggers
# =============================================================================
class EmailCondition(BaseModel):
"""Condition for email trigger."""
field: Literal["from", "to", "subject", "body", "attachments"]
operator: Literal["equals", "contains", "matches", "semantic"]
value: str
confidence: float = Field(default=1.0, ge=0.0, le=1.0)
class EmailTrigger(BaseModel):
"""Trigger on email arrival."""
type: Literal["email"] = "email"
account: str
conditions: list[EmailCondition] = Field(default_factory=list)
class ScheduleTrigger(BaseModel):
"""Trigger on schedule."""
type: Literal["schedule"] = "schedule"
cron: str | None = None
interval_value: int | None = None
interval_unit: Literal["minutes", "hours", "days"] | None = None
timezone: str = "UTC"
class WebhookTrigger(BaseModel):
"""Trigger on webhook."""
type: Literal["webhook"] = "webhook"
endpoint: str
secret: str | None = None
class FileChangeTrigger(BaseModel):
"""Trigger on file change."""
type: Literal["file_change"] = "file_change"
connector: str
path_pattern: str
events: list[Literal["created", "modified", "deleted"]] = Field(
default_factory=lambda: ["created", "modified"]
)
class ManualTrigger(BaseModel):
"""Manual trigger (user-initiated)."""
type: Literal["manual"] = "manual"
Trigger = EmailTrigger | ScheduleTrigger | WebhookTrigger | FileChangeTrigger | ManualTrigger
# =============================================================================
# Actions
# =============================================================================
class FileAction(BaseModel):
"""File operation action."""
type: Literal["file.read", "file.write", "file.move", "file.delete"]
connector: str
path: str
source: str | None = None
on_conflict: Literal["overwrite", "rename", "skip", "error"] = "rename"
class SpreadsheetRow(BaseModel):
"""Row data for spreadsheet action."""
column: str
value: str
class SpreadsheetAction(BaseModel):
"""Spreadsheet operation action."""
type: Literal["spreadsheet.read", "spreadsheet.append", "spreadsheet.update"]
connector: str
spreadsheet_id: str
sheet_name: str
row: list[SpreadsheetRow] | None = None
range: str | None = None
class EmailAction(BaseModel):
"""Email operation action."""
type: Literal["email.send", "email.label", "email.archive"]
connector: str
to: list[str] | None = None
subject: str | None = None
body: str | None = None
label: str | None = None
message_id: str | None = None
class ExtractionField(BaseModel):
"""Field to extract from a document."""
name: str
type: Literal["text", "currency", "date", "number"]
confidence_threshold: float = Field(default=0.7, ge=0.0, le=1.0)
class ExtractAction(BaseModel):
"""Document extraction action."""
type: Literal["document.extract"] = "document.extract"
source: str
fields: list[ExtractionField]
on_low_confidence: Literal["flag", "skip", "error"] = "flag"
Action = FileAction | SpreadsheetAction | EmailAction | ExtractAction
# =============================================================================
# Capabilities & Error Handling
# =============================================================================
class Capability(BaseModel):
"""What an automation can access."""
connector: str
operations: list[Literal["read", "write", "delete"]]
scope: dict[str, Any] | None = None
class ErrorHandler(BaseModel):
"""Error handling configuration."""
condition: str
action: Literal["continue", "stop", "notify", "create_review_task"]
message: str | None = None
class MonitoringConfig(BaseModel):
"""Monitoring configuration."""
notify_on: list[str] = Field(default_factory=lambda: ["error"])
daily_digest: bool = False
# =============================================================================
# Automations
# =============================================================================
class Variable(BaseModel):
"""Variable in an automation."""
name: str
type: str
resolved_from: str
class Automation(BaseModel):
"""Automation definition."""
id: str
name: str
description: str = ""
status: AutomationStatus = AutomationStatus.DRAFT
trigger: Trigger
variables: list[Variable] = Field(default_factory=list)
actions: list[Action] = Field(default_factory=list)
error_handling: list[ErrorHandler] = Field(default_factory=list)
monitoring: MonitoringConfig = Field(default_factory=MonitoringConfig)
capabilities: list[Capability] = Field(default_factory=list)
created_at: datetime = Field(default_factory=datetime.now)
updated_at: datetime = Field(default_factory=datetime.now)
version: int = 1
# =============================================================================
# Executions
# =============================================================================
class TriggerEvent(BaseModel):
"""Event that triggered an execution."""
type: str
data: dict[str, Any] = Field(default_factory=dict)
timestamp: datetime = Field(default_factory=datetime.now)
class ResolvedVariable(BaseModel):
"""Variable resolved during execution."""
name: str
value: Any
confidence: float = Field(default=1.0, ge=0.0, le=1.0)
class ActionResult(BaseModel):
"""Result of executing an action."""
action_id: str
status: Literal["success", "failed", "skipped"]
output: dict[str, Any] = Field(default_factory=dict)
error: str | None = None
duration_ms: int | None = None
class ExecutionError(BaseModel):
"""Execution error details."""
message: str
action_id: str | None = None
recoverable: bool = True
recovery_options: list[str] = Field(default_factory=list)
class Execution(BaseModel):
"""Execution record."""
id: str
automation_id: str
automation_version: int
triggered_at: datetime = Field(default_factory=datetime.now)
completed_at: datetime | None = None
status: ExecutionStatus = ExecutionStatus.RUNNING
trigger_event: TriggerEvent
variables: list[ResolvedVariable] = Field(default_factory=list)
action_results: list[ActionResult] = Field(default_factory=list)
error: ExecutionError | None = None
# =============================================================================
# Intent Engine
# =============================================================================
class Ambiguity(BaseModel):
"""Ambiguity detected in intent parsing."""
id: str
field: str
description: str
suggested_questions: list[str] = Field(default_factory=list)
class IntentAction(BaseModel):
"""Action in an intent graph."""
type: str
params: dict[str, Any] = Field(default_factory=dict)
confidence: float = Field(default=1.0, ge=0.0, le=1.0)
output: str | None = None
class IntentTrigger(BaseModel):
"""Trigger in an intent graph."""
type: str
conditions: list[dict[str, Any]] = Field(default_factory=list)
confidence: float = Field(default=1.0, ge=0.0, le=1.0)
class IntentGraph(BaseModel):
"""Parsed intent from natural language."""
id: str
type: Literal["automation", "query", "command"] = "automation"
confidence: float = Field(default=1.0, ge=0.0, le=1.0)
trigger: IntentTrigger | None = None
actions: list[IntentAction] = Field(default_factory=list)
ambiguities: list[Ambiguity] = Field(default_factory=list)
raw_input: str = ""
class ClarificationQuestion(BaseModel):
"""Question to clarify an ambiguity."""
id: str
ambiguity_id: str
question: str
options: list[str] = Field(default_factory=list)
default: str | None = None
class ClarificationAnswer(BaseModel):
"""Answer to a clarification question."""
question_id: str
answer: str
class ClarificationState(BaseModel):
"""State of clarification dialog."""
intent_id: str
questions_asked: int = 0
questions_answered: int = 0
questions: list[ClarificationQuestion] = Field(default_factory=list)
answers: list[ClarificationAnswer] = Field(default_factory=list)
ready_to_plan: bool = False
# =============================================================================
# Learning
# =============================================================================
class ProposedFix(BaseModel):
"""Proposed fix from learning."""
type: str
rule: str
confidence: float = Field(default=0.5, ge=0.0, le=1.0)
class LearningEvent(BaseModel):
"""Learning event from user feedback."""
id: str
type: LearningEventType
automation_id: str | None = None
execution_id: str | None = None
original: Any = None
corrected: Any = None
inferred_cause: str | None = None
proposed_fix: ProposedFix | None = None
user_response: Literal["accepted", "rejected", "modified"] | None = None
created_at: datetime = Field(default_factory=datetime.now)
# =============================================================================
# Conversations
# =============================================================================
class Message(BaseModel):
"""Message in a conversation."""
role: Literal["user", "assistant", "system"]
content: str
timestamp: datetime = Field(default_factory=datetime.now)
class ConversationContext(BaseModel):
"""Context for a conversation."""
entities_mentioned: list[str] = Field(default_factory=list)
automations_mentioned: list[str] = Field(default_factory=list)
current_intent_id: str | None = None
class Conversation(BaseModel):
"""Conversation with the system."""
id: str
messages: list[Message] = Field(default_factory=list)
context: ConversationContext = Field(default_factory=ConversationContext)
created_at: datetime = Field(default_factory=datetime.now)
updated_at: datetime = Field(default_factory=datetime.now)
View File
+72
View File
@@ -0,0 +1,72 @@
"""Tests for PAI models."""
from pai.models import (
Automation,
AutomationStatus,
EmailCondition,
EmailTrigger,
Entity,
EntityType,
FileAction,
IntentGraph,
)
def test_email_trigger():
"""Test EmailTrigger model."""
trigger = EmailTrigger(
account="user@example.com",
conditions=[
EmailCondition(
field="from",
operator="contains",
value="@client.com",
)
],
)
assert trigger.type == "email"
assert len(trigger.conditions) == 1
def test_automation():
"""Test Automation model."""
auto = Automation(
id="auto_001",
name="Test Automation",
description="A test automation",
trigger=EmailTrigger(account="user@example.com"),
actions=[
FileAction(
type="file.write",
connector="google_drive",
path="/test/file.pdf",
)
],
)
assert auto.status == AutomationStatus.DRAFT
assert auto.version == 1
assert len(auto.actions) == 1
def test_entity():
"""Test Entity model."""
entity = Entity(
id="ent_001",
type=EntityType.CLIENT,
name="Acme Corp",
aliases=["Acme", "ACME Corporation"],
metadata={"domain": "acme.com"},
)
assert entity.type == EntityType.CLIENT
assert "Acme" in entity.aliases
def test_intent_graph():
"""Test IntentGraph model."""
intent = IntentGraph(
id="int_001",
confidence=0.85,
raw_input="When a client emails me...",
)
assert intent.type == "automation"
assert intent.confidence == 0.85