Perry: Multi-Agent Odoo Orchestrator

Perry is an advanced multi-agent system integrated with Odoo, designed to act as an intelligent assistant capable of executing complex actions, querying financial data, and managing customer relationships using natural language.

Built on a Semantic Router architecture, Perry delegates tasks to specialized agents, ensuring security, transparent reasoning, and mandatory human validation.

---

System Architecture

The system is orchestrated by a Semantic Router that classifies user intent and redirects it to the appropriate specialized agent:

• FinanceAgent: Manages payments and balance inquiries.
• CRMAgent: Lead creation and opportunity tracking.
• CalendarAgent: Event scheduling and calendar management.
• ChatAgent: Default general-purpose assistant.

---

Internal Documentation

For deep dives into specific modules, architecture components and implementation details, please refer to our dedicated internal documentation:

• Agents & Factory Architecture: Detailed breakdown of the agentic ecosystem, including the Base Agent, Factory Agent and the specific implementations (Calendar, Chat, CRM, Finance).
• Semantic Router: Guide on the intent classification engine that evaluates user inputs and dispatches tasks to the correct agent.
• MCP Server & Tools: Documentation covering the Model Context Protocol (MCP) integration and the comprehensive suite of tools connecting the AI to Odoo.
• Guardrails & Safety: Information on how Guardrails AI enforces structured outputs, prevents hallucinations and ensures safe execution.
• Traceability & Observability: Setup and usage instructions for tracking system state, telemetry and debugging using Pydantic Logfire.
• Gmail Polling Service: Overview of the background worker responsible for polling and ingesting incoming emails into the pipeline.
• Testing Strategy: Guidelines on our testing protocols, test structure and mocking strategies to maintain high coverage.

---

Key Features

• MCP Integration: Uses the Model Context Protocol via FastMCP to connect AI tools directly with the Odoo backend.
• Transparent Reasoning: Perry exposes his "thought process" before executing actions, allowing users to understand the logic behind every decision.
• Safety & Guardrails: Powered by Guardrails AI to prevent hallucinations or unexpected outputs.
• Human-in-the-Loop (HITL): Mandatory validation tool. Perry requests human confirmation for critical data (payments, leads, events) before any database write occurs.
• Flexible Models: Support for API-based models (OpenAI/Gemini) or local inference via vLLM.
• Observability: Full interaction and state traceability using Logfire.

---

Code Quality

We maintain a rigorous quality standard:

• Coverage: 100% unit and integration test coverage with pytest-cov.
• Linting: Clean code guaranteed by ruff.
• Security: Vulnerability scanning via safety.

---

Installation and Deployment

Perry requires two main components running on the same Docker network to communicate:

1. testing-odoo: The Odoo instance for testing.
2. ingest-api: The "brain" housing Perry and his agents.

1. Network Preparation

Create the shared Docker network:

docker network create perry-network

2. Odoo Setup (testing-odoo)

Clone and launch the Odoo instance:

git clone https://github.com/Perry-Multi-LLM/testing-odoo.git
cd testing-odoo
docker-compose up -d --build

3. Perry Setup (ingest-api)

Clone the orchestrator and configure the environment:

cd ..
git clone https://github.com/Perry-Multi-LLM/ingest-api.git
cd ingest-api

Create a .env file following the .env-example template, then launch:

docker-compose up -d --build

4. Connect Containers to the Network

To enable communication between the brain and the ERP, link them manually to the network:

docker network connect perry-network testing-odoo
docker network connect perry-network ingest-api