Metadata-Version: 2.4
Name: delfhos
Version: 0.5.0
Summary: Delfhos — AI agent SDK with typed connections and tool orchestration
Author-email: David Serrano <davidsd.2704@gmail.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/DavidFraifer/delfhos
Project-URL: Source, https://github.com/DavidFraifer/delfhos
Project-URL: Issues, https://github.com/DavidFraifer/delfhos/issues
Keywords: ai,agents,sdk,automation,mcp,gemini
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: google-genai>=1.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: requests>=2.28.0
Requires-Dist: beautifulsoup4>=4.12.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: tenacity>=8.0.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: sentence-transformers>=2.2.0
Requires-Dist: transformers>=4.30.0
Requires-Dist: huggingface-hub>=0.16.0
Requires-Dist: psycopg2-binary<3.0,>=2.9
Requires-Dist: mysql-connector-python<9.0,>=8.0
Requires-Dist: openpyxl>=3.1.0
Requires-Dist: PyPDF2>=3.0.0
Requires-Dist: PyYAML>=6.0.0
Requires-Dist: google-auth>=2.0.0
Requires-Dist: google-auth-oauthlib>=1.0.0
Requires-Dist: google-auth-httplib2>=0.1.0
Requires-Dist: google-api-python-client>=2.0.0
Requires-Dist: rich>=10.0.0
Requires-Dist: questionary>=2.1.0
Requires-Dist: fastapi>=0.100.0
Requires-Dist: uvicorn>=0.23.0
Requires-Dist: python-multipart>=0.0.6
Requires-Dist: python-jose>=3.3.0
Requires-Dist: email-validator>=2.0.0
Requires-Dist: passlib>=1.7.4
Requires-Dist: bcrypt>=4.0.0
Requires-Dist: websockets>=11.0
Requires-Dist: httpx>=0.24.0
Requires-Dist: tqdm>=4.65.0
Requires-Dist: stripe>=5.0.0
Requires-Dist: supabase>=2.0.0
Requires-Dist: postgrest>=0.10.0
Provides-Extra: sql
Requires-Dist: psycopg2-binary<3.0,>=2.9; extra == "sql"
Requires-Dist: mysql-connector-python<9.0,>=8.0; extra == "sql"
Provides-Extra: dev
Requires-Dist: build>=1.2.2; extra == "dev"
Requires-Dist: twine>=5.1.1; extra == "dev"
Requires-Dist: pytest>=8.0.0; extra == "dev"
Dynamic: license-file

# Delfhos

Delfhos is a Python SDK for building AI agents that use real tools (Gmail, SQL, Drive, MCP, custom functions) with clean orchestration and safe execution.

## Install

```bash
pip install delfhos
```

From source:

```bash
git clone https://github.com/DavidFraifer/delfhos
cd delfhos
pip install -e .
```

## Quick Start

```python
from delfhos import Agent, WebSearch

agent = Agent(
    tools=[WebSearch(llm="gpt-5.4-mini")],
    llm="gemini-3.1-flash-lite-preview",
)

agent.run("What are the top 3 AI trends this week? Keep it short.")
agent.stop()
```

## Core Concepts

- `Agent`: public entry point (`from delfhos import Agent`)
- `tools`: built-in tools, MCP tools, and `@tool` custom functions
- `Chat`: short-term conversation memory (SQLite persisted)
- `Memory`: long-term semantic memory (SQLite + embeddings)
- `confirm`: action approval policy (`True`, `False`, or list like `["write", "delete"]`)

## Built-in Tools

```python
from delfhos import Gmail, SQL, Sheets, Drive, Calendar, Docs, WebSearch, MCP
```

Examples:

```python
gmail = Gmail(oauth_credentials="client_secrets.json", allow=["read", "send"])
db = SQL(url="postgresql://user:pass@host/mydb", allow=["schema", "query"])
drive = Drive(oauth_credentials="client_secrets.json", allow=["search", "get"])

agent = Agent(tools=[gmail, db, drive], llm="gemini-3.1-flash-lite-preview")
```

Notes:
- Use `allow=[...]` to restrict actions.
- Inspect available methods with `tool.inspect()` or detailed output with `tool.inspect(verbose=True)`.
- `WebSearch` requires an explicit search model: `WebSearch(llm="gemini-..." )` or `WebSearch(llm="gpt-...")`.
- For parseable outputs, request format in the query (e.g., "Return ONLY JSON: {\"rate\": number}").

## Custom Tools

```python
from delfhos import Agent, tool

@tool
async def calculate_total(price: float, tax: float) -> float:
    return price * (1 + tax)

agent = Agent(
    tools=[calculate_total],
    llm="gemini-3.1-flash-lite-preview",
)
```

## Memory (Chat + Long-Term)

```python
from delfhos import Agent, Chat, Memory, WebSearch

agent = Agent(
    tools=[WebSearch(llm="gpt-5.4-mini")],
    chat=Chat(keep=8, summarize=True, namespace="support_agent"),
    memory=Memory(namespace="support_agent"),
    llm="gemini-3.1-flash-lite-preview",
)
```

Default storage paths:
- Chat: `~/delfhos/chat/<namespace>.db`
- Memory: `~/delfhos/memory/<namespace>.db`

Generated task code can persist durable facts with:

```python
await memory.save("User prefers monthly billing", desc="final preference")
```

## Approval and Safety

```python
agent = Agent(
    tools=[...],
    confirm=["write", "delete"],
    llm="gemini-3.1-flash-lite-preview",
)
```

- `confirm` controls which actions require approval.
- `@tool(confirm=True)` enforces approval for that tool.

## Model Support

Supported model families:
- `gemini-*`
- `gpt-*` (including `o1/o3/o4` style IDs)
- `claude-*`

Example:

```python
agent = Agent(tools=[...], llm="gemini-3.1-flash-lite-preview")
```

## Pricing and Cost (USD)

Delfhos calculates LLM cost in USD from a user-editable pricing file:

- `~/delfhos/pricing.json`

Behavior:
- The file is auto-created on first run.
- Final execution summary always shows total USD cost.
- In verbose mode, each LLM call also shows its individual USD cost.
- Trace exports include total cost and pricing source path.
- If a model is missing in `pricing.json`, Delfhos does not calculate USD cost for that model and logs a warning.

You can edit prices or add new models at any time:

```json
{
    "_comment": "USD per 1M tokens. Edit rates or add models. Wildcards are supported, e.g. gpt-*.",
    "models": {
        "gemini-3.1-flash-lite-preview": {
            "input_per_million": 0.10,
            "output_per_million": 0.40
        },
        "gpt-4o-mini": {
            "input_per_million": 0.15,
            "output_per_million": 0.60
        },
        "claude-3-5-sonnet": {
            "input_per_million": 3.00,
            "output_per_million": 15.00
        },
        "gpt-*": {
            "input_per_million": 1.00,
            "output_per_million": 4.00
        }
    }
}
```

## Error System

Delfhos errors include:
- stable code
- readable message
- fix hint

Example shape:

```text
❌ [ERR-TOOL-001] Delfhos Error
----------------------------------------
Message: Tool 'web_search' failed during execution: network timeout
----------------------------------------
💡 Hint: Review the arguments sent to the tool...
```

Main families include:
- `ERR-TOOL-*`
- `ERR-CONN-*`
- `ERR-ENV-*`
- `ERR-LLM-*`
- `ERR-MCP-*`

## Minimal MCP Example

```python
from delfhos import Agent, MCP

fs = MCP(
    "server-filesystem",
    args=["."],
    allow=["read_file", "write_file"],
)

agent = Agent(tools=[fs], llm="gemini-3.1-flash-lite-preview")
agent.run("List python files and create a short summary file.")
agent.stop()
```

## License

Apache-2.0
