odoo-ai/README.md

# ActiveBlue AI

Multi-agent AI system integrated with Odoo 18 Community Edition, powered by **Ollama** (`activeblue-chat` / llama-based model) running fully on-premise.

## What's New (May 2026)

- **Ollama cold-start fix**: `activeblue-chat` model takes ~124s to load from disk; timeout raised to 300s (enforced in code regardless of env var) and the model is pre-warmed at service startup so the first user message never times out.
- **Model pre-warming**: `_prewarm_ollama()` is launched as a background task during lifespan startup, loading the model into VRAM before any user traffic arrives.
- **Improved health check**: `/health/detailed` now queries Ollama's `ps` endpoint to report whether the model is loaded (`ok`) or still loading (`warming`), giving accurate bot online/offline status.
- **Comprehensive unit test suite**: 433 tests across all 8 specialist agents, all tool layers, PeerBus, AgentRegistry, ToolCallValidator, and base agent lifecycle. Run with `.venv-test/bin/python -m pytest tests/ -q`.
- **Tool count enforcement**: Each specialist agent is validated at startup to have ≤ 8 tools (`AgentConfigError` otherwise).
- **PeerBus inter-agent communication**: Agents can call each other with depth-limited routing, timeout safety, and call-log tracking.
- **Auto-RAG**: All agents automatically fetch Odoo 18 workflow guidance from `odoo_doc_agent` before answering.
- **Auto-heal loop**: Background task calls `sysops_agent.auto_heal()` every 2 minutes if any system is degraded.

## Architecture

```
Odoo 18 (ai.activeblue.net)
  └── activeblue_ai module
        ├── OWL2 systray brain icon + slide-in chat panel
        ├── Models: ab.ai.bot, ab.ai.directive, ab.ai.log, ab.ai.agent.registry
        └── Controllers: /ai/chat, /ai/webhook/callback, /ai/health, /ai/approval/*

FastAPI Agent Service (192.168.2.47:8001)
  ├── POST /dispatch       — route user message to MasterAgent
  ├── GET/POST /approval/* — human approval workflow
  ├── GET/POST /registry/* — agent registry + LLM backend overrides
  ├── POST /sweep          — trigger proactive agent sweeps
  └── GET /health          — service health + Odoo/Ollama status

MasterAgent (singleton)
  ├── Classifies intent via LLM
  ├── Routes to specialist agents in parallel (asyncio.gather)
  ├── Manages 3-tier memory (conversation / operational / knowledge)
  └── Synthesises responses

Specialist Agents (8, stateless):
  finance_agent, accounting_agent, crm_agent, sales_agent,
  project_agent, elearning_agent, expenses_agent, employees_agent
```

## Privacy Modes

| Mode    | Behaviour                                  |
|---------|--------------------------------------------|
| `local` | Ollama only for all agents                 |
| `hybrid`| Per-agent override (DB → env → fallback)   |
| `cloud` | Claude for non-HIPAA agents                |

**HIPAA-locked agents** (always Ollama, no exceptions):
`finance_agent`, `accounting_agent`, `employees_agent`, `expenses_agent`

## Quick Start

### 1. Clone and configure

```bash
git clone http://192.168.1.64:3000/tocmo0nlord/odoo-ai.git
cd odoo-ai
cp .env.example .env
# Edit .env — set POSTGRES_PASSWORD, ODOO_API_KEY, etc.
```

### 2. Run Odoo 18

```bash
docker compose -f docker-compose.odoo.yml up -d
```

### 3. Run the Agent Service

```bash
docker compose up -d
```

Or for development:

```bash
pip install -r requirements.txt
uvicorn agent_service.main:app --reload --port 8001
```

### 4. Run database migrations

```bash
cd agent_service/migrations
alembic upgrade head
```

### 5. Install Odoo module

In Odoo → Settings → Apps → search "ActiveBlue AI" → Install.

## Environment Variables

See `.env.example` for the full list. Key variables:

| Variable | Description |
|----------|-------------|
| `ODOO_URL` | Odoo base URL (e.g. `http://ai.activeblue.net`) |
| `ODOO_API_KEY` | Odoo user API key |
| `OLLAMA_URL` | Ollama API URL (e.g. `http://192.168.2.47:11434`) |
| `ANTHROPIC_API_KEY` | Required only if `LLM_PRIVACY_MODE=cloud` or `hybrid` |
| `LLM_PRIVACY_MODE` | `local` / `hybrid` / `cloud` (default: `local`) |
| `POSTGRES_PASSWORD` | Required — no default |
| `WEBHOOK_SECRET` | Shared secret between Odoo and agent service |

## Development

### Running tests

```bash
# Using the project test venv (recommended)
.venv-test/bin/python -m pytest tests/ -q

# Or install manually
pip install pytest pytest-asyncio
pytest tests/ -v
```

Test coverage (433 passing, all on Ollama/local mode):
- `tests/test_registry.py` — AgentRegistry lifecycle
- `tests/test_peer_bus.py` — PeerBus routing, depth limits, timeouts
- `tests/test_tool_validator.py` — ToolCallValidator, type coercion, enum guards
- `tests/test_*_tools.py` — 8 files covering every tool method (finance, accounting, crm, sales, project, elearning, employees, expenses)
- `tests/test_*_agent.py` — 8 files covering plan/gather/reason/act/report/sweep/peer_bus for each specialist agent
- `tests/test_dispatch_router.py`, `test_e2e_dispatch.py`, `test_llm_router.py`, `test_odoo_client.py` — integration tests

### Project structure

```
odoo-ai/
├── agent_service/
│   ├── agents/          # MasterAgent + 8 specialist agents + PeerBus + SweepCoordinator
│   ├── llm/             # OllamaBackend, ClaudeBackend, LLMRouter, ToolCallValidator
│   ├── memory/          # ConversationStore, OperationalStore, KnowledgeStore, MemoryManager
│   ├── tools/           # OdooClient + per-domain tools (finance, crm, sales, ...)
│   ├── routers/         # FastAPI routers (dispatch, approval, registry, sweep, health)
│   ├── prompts/         # System prompts for each agent
│   ├── migrations/      # Alembic migrations (7 tables)
│   ├── logging_utils/   # Structured JSON logging + Loki push
│   ├── config.py        # pydantic-settings
│   ├── app_state.py     # Global singletons
│   └── main.py          # FastAPI app + lifespan startup
├── addons/
│   └── activeblue_ai/   # Odoo 18 module
│       ├── models/      # ab.ai.bot, ab.ai.directive, ab.ai.log, ab.ai.agent.registry
│       ├── controllers/ # webhook, health_proxy, approval + chat
│       ├── views/       # XML views + menus
│       ├── security/    # groups + ACL
│       ├── data/        # cron jobs
│       └── static/      # OWL2 JS + CSS + XML templates
├── research/            # Per-domain research notes
├── tests/               # pytest test suite
├── docker-compose.odoo.yml  # Odoo 18 + PostgreSQL 15
├── docker-compose.yml       # Agent service + PostgreSQL 15
├── Dockerfile
├── requirements.txt
└── .env.example
```

## Agent Tool Limits

Each specialist agent is capped at **8 tools** (`MAX_TOOLS_PER_AGENT`). The `ToolCallValidator` raises `AgentConfigError` at startup if exceeded.

## Memory Architecture

| Tier | Store | TTL | Scope |
|------|-------|-----|-------|
| Tier 1 | `ab_conversation_memory` | Hard cap: 200 rows/user | Per user |
| Tier 2 | `ab_operational_memory` | 90 days | Per agent+scope |
| Tier 3 | `ab_knowledge_store` | Permanent | Entity-keyed |

## License

LGPL-3.0