Metadata-Version: 2.4
Name: opero-odoo-agent-tools
Version: 0.1.0
Summary: Framework-neutral Odoo connector tools for AI agent runtimes
Author: Opero
License-Expression: MIT
Project-URL: Homepage, https://opero.asia
Project-URL: Documentation, https://opero.asia
Keywords: odoo,agents,tools,sdk,connector
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# Odoo Agent Tools SDK

A small, framework-neutral connector layer for exposing Odoo operations as safe,
predictable tools for AI agents.

The goal is to keep agent developers away from raw Odoo RPC details. They should
call typed tool functions with JSON-compatible arguments and receive consistent
results that are easy to pass back into an agent runtime.

## Design Principles

1. **Agent-safe by default**: validate inputs, bound result sizes, and avoid
   destructive operations unless the tool explicitly opts in.
2. **Framework-neutral**: expose plain Python callables and JSON schemas so the
   tools can be adapted to OpenAI, LangChain, Semantic Kernel, AutoGen, or a
   custom runner.
3. **Odoo-native underneath**: preserve Odoo concepts such as models, domains,
   fields, and record IDs without leaking XML-RPC ceremony into agent code.
4. **Predictable outputs**: every tool returns a `ToolResult` with `ok`, `data`,
   and `error` fields.
5. **Extensible connector standards**: new connectors should follow the same
   tool definition and error contract used here.

## Quick Start

Install the package:

```powershell
pip install opero-odoo-agent-tools
```

```python
from odoo_agent_tools import OdooClient, OdooConfig, build_odoo_business_tools

config = OdooConfig(
    url="https://example.odoo.com",
    database="my-db",
    username="agent@example.com",
    password="api-key-or-password",
)

client = OdooClient(config)
tools = build_odoo_business_tools(client)

result = tools["odoo_find_customer"].call({"query": "Acme", "limit": 10})

print(result.to_dict())
```

The low-level model tools are also available through `build_odoo_tools`.

## Included Tools

### Low-Level Odoo Tools

- `odoo_search_read`: search and read records from an Odoo model.
- `odoo_read`: read records by ID.
- `odoo_create`: create a record, opt-in write tool.
- `odoo_write`: update records, opt-in write tool.
- `odoo_unlink`: delete records, opt-in destructive tool.
- `odoo_call_method`: call an allowlisted model method.

### Business Tools

- `odoo_find_customer`: find contacts by name, email, or phone.
- `odoo_create_crm_lead`: create a CRM lead or opportunity.
- `odoo_get_invoice_status`: get invoice status and payment details.
- `odoo_find_product`: find products by name, SKU, or barcode.
- `odoo_create_project_task`: create a project task.
- `odoo_get_sale_order_status`: get sales order state, invoice status, and delivery status.

## Connector Standard

Every connector tool should provide:

- A stable `name` using the `{system}_{verb}` pattern.
- A short `description` written for an agent planner.
- A JSON Schema object for arguments.
- A plain Python `call(arguments: dict) -> ToolResult` method.
- A conservative default limit for list operations.
- Explicit `is_write` and `is_destructive` flags.
- Structured errors using `ToolError`.

See `docs/CONNECTOR_STANDARD.md` for the full standard.

## Development

```powershell
$env:PYTHONPATH='src'
python -m unittest discover -s tests
```

## Testing Against Odoo

Create a `.env` file from `.env.example` and fill in your Odoo details:

```powershell
Copy-Item .env.example .env
```

Then edit `.env`:

```env
ODOO_URL=https://your-company.odoo.com
ODOO_DATABASE=your-database
ODOO_USERNAME=agent@example.com
ODOO_PASSWORD=your-api-key-or-password
```

Run the smoke test:

```powershell
$env:PYTHONPATH='src'
python examples/smoke_test_odoo.py
```

The smoke test calls `odoo_search_read` against `res.partner` and prints a
standard `ToolResult`. Existing environment variables override values loaded
from `.env`.

You can also test the higher-level business tools:

```powershell
$env:PYTHONPATH='src'
python examples/smoke_test_business_tools.py
```

The package uses only Python standard library modules at runtime.
