Metadata-Version: 2.4
Name: delfhos
Version: 0.5.5
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

Python SDK for building AI agents that use real tools — Gmail, SQL, Drive, Sheets, MCP servers, and your own functions — with safe, human-in-the-loop execution.

> Full documentation at **[delfhos.com/docs](https://delfhos.com/docs)**

---

## How it works

You describe a task in plain English. Delfhos:

1. **Picks** the relevant tools from the ones you configured
2. **Writes** Python code to accomplish the task
3. **Executes** that code in a sandbox against your real services
4. **Retries** automatically if something fails

You stay in control: restrict which actions each tool can take, and require approval before any write, send, or delete.

---

## Install

```bash
pip install delfhos
```

## API Key

Delfhos supports Gemini, OpenAI, and Anthropic models. Export the key for the provider you want to use:

```bash
export GOOGLE_API_KEY="..."    # Gemini
export OPENAI_API_KEY="..."    # OpenAI
export ANTHROPIC_API_KEY="..."  # Claude
```

---

## Try it instantly (no credentials needed)

The sandbox tools come pre-loaded with dummy data so you can run your first agent right now:

```python
from delfhos import Agent
from delfhos.sandbox import MockEmail, MockDatabase

agent = Agent(
    tools=[MockEmail(confirm=False), MockDatabase(confirm=False)],
    llm="gemini-2.0-flash-lite",
)

agent.run(
    "Read my unread emails. If any mention a support ticket, "
    "look it up in the database and summarise the customer name, "
    "open tickets, and total order value."
)
agent.stop()
```

Or just run the included example:

```bash
python examples/hello_delfhos.py
```

---

## Custom tools

Decorate any Python function with `@tool` and the agent can call it:

```python
from delfhos import Agent, tool

@tool
def calculate_discount(price: float, pct: float) -> float:
    """Return price after applying a percentage discount."""
    return price * (1 - pct / 100)

agent = Agent(tools=[calculate_discount], llm="gemini-2.0-flash-lite")
agent.run("What is the price of a $120 item with a 15% discount?")
agent.stop()
```

---

## Built-in tools

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

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

agent = Agent(tools=[gmail, db, drive], llm="gemini-2.0-flash-lite")
agent.run("Check unread emails and log any order mentions to the database.")
agent.stop()
```

**`allow`** — restrict which actions are available on the tool (`["read", "send"]`, `["schema", "query"]`, …).  
**`confirm`** — when human approval is required: `True` (all), `False` (none), or a list of specific actions.

---

## Interactive chat

```python
from delfhos import Agent, Chat, Gmail

agent = Agent(
    tools=[Gmail(oauth_credentials="client_secrets.json")],
    llm="gemini-2.0-flash-lite",
    chat=Chat(summarizer_llm="gemini-2.0-flash-lite"),
)

agent.run_chat()  # starts a terminal session — type /help for commands
```

---

## Memory

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

agent = Agent(
    tools=[...],
    llm="gemini-2.0-flash-lite",
    chat=Chat(keep=8, summarize=True, namespace="my_agent"),    # short-term
    memory=Memory(namespace="my_agent"),                         # long-term semantic
)
```

---

## MCP servers

```python
from delfhos import Agent, MCP

fs = MCP("server-filesystem", args=["."], allow=["read_file", "write_file"])
agent = Agent(tools=[fs], llm="gemini-2.0-flash-lite")
agent.run("List all Python files and write a one-line summary for each.")
agent.stop()
```

---

## Response object

`agent.run()` returns a `Response` with the result, status, cost, and trace:

```python
r = agent.run("How many users signed up this week?")

print(r.text)        # agent's answer
print(r.status)      # True if task succeeded
print(r.cost_usd)    # cost in dollars (e.g. 0.0003)
print(r.duration_ms) # wall-clock time in milliseconds
```

---

## Model support

Pass any model string from Gemini, OpenAI, or Anthropic:

```python
# Gemini
agent = Agent(tools=[...], llm="gemini-2.0-flash-lite")
agent = Agent(tools=[...], llm="gemini-2.0-flash")

# OpenAI
agent = Agent(tools=[...], llm="gpt-4o-mini")
agent = Agent(tools=[...], llm="gpt-4o")

# Anthropic
agent = Agent(tools=[...], llm="claude-3-5-haiku-latest")
agent = Agent(tools=[...], llm="claude-3-5-sonnet-latest")
```

Use `light_llm` + `heavy_llm` to split fast prefiltering from heavier code generation:

```python
agent = Agent(
    tools=[...],
    light_llm="gemini-2.0-flash-lite",   # fast, cheap — for tool selection
    heavy_llm="gemini-2.0-flash",         # stronger — for code generation
)
```

---

## Context manager

The agent cleans up automatically when used as a context manager:

```python
with Agent(tools=[...], llm="gemini-2.0-flash-lite") as agent:
    agent.run("Summarise last week's sales and email it to the team.")
```

---

For the full API reference and advanced guides see [DOCS.md](DOCS.md) or **[delfhos.com/docs](https://delfhos.com/docs)**.

## License

Apache-2.0
