Metadata-Version: 2.4
Name: agenthelm
Version: 0.2.0
Summary: A production-ready, observable, and reliable AI agent orchestration framework.
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi>=0.120.0
Requires-Dist: opentelemetry-api>=1.38.0
Requires-Dist: pydantic>=2.12.3
Requires-Dist: requests>=2.32.5
Requires-Dist: sqlalchemy>=2.0.44
Requires-Dist: typer>=0.20.0
Requires-Dist: tabulate>=0.9.0
Provides-Extra: dev
Requires-Dist: ruff>=0.5.5; extra == "dev"
Requires-Dist: pytest>=8.3.2; extra == "dev"
Requires-Dist: mkdocs>=1.6.0; extra == "dev"
Requires-Dist: mkdocs-material>=9.5.0; extra == "dev"
Requires-Dist: mkdocstrings[python]>=0.25.1; extra == "dev"
Requires-Dist: ty>=0.0.1a24; extra == "dev"
Requires-Dist: matplotlib>=3.10.7; extra == "dev"
Requires-Dist: networkx>=3.5; extra == "dev"
Dynamic: license-file

[![FreePalestine.Dev](https://freepalestine.dev/header/1)](https://freepalestine.dev)

# AgentHelm

**Production-Ready Orchestration for AI Agents.**

---

AgentHelm is a lightweight Python framework for building AI agents with a focus on production-readiness. It provides the essential orchestration layer to make your agents observable, reliable, and safe.

In the rapidly evolving world of AI agents, many frameworks focus on rapid prototyping. AgentHelm is different. It's built on the premise that for agents to be trusted in real-world, production environments, they need the same level of observability and control as traditional software.

If you've ever struggled to debug a failing agent or worried about deploying an agent that interacts with real-world systems, AgentHelm is for you.

## Key Features

-   **Traceable Execution**: Automatically log every tool call, its inputs, outputs, errors, and execution time. Get a complete, structured audit trail of your agent's actions.
-   **Human-in-the-Loop**: Mark sensitive tools (e.g., `charge_credit_card`) with a `@tool(requires_approval=True)` decorator to ensure a human must approve the action before it runs.
-   **Resilient Workflows**: Define automatic retries for flaky tools that might fail due to transient network errors.
-   **Transactional Safety**: Implement automatic rollbacks for multi-step workflows. If a step fails, AgentHelm can run compensating actions to undo the previous steps.

---

## Observability & Trace Explorer (v0.2.0 New!)

AgentHelm now provides enhanced observability features, allowing you to store, query, and analyze your agent's execution
traces with ease.

### Storage Backends

By default, AgentHelm stores traces in a JSON file (`cli_trace.json`). You can now choose between different storage
backends:

- **JSON Storage**: Simple file-based storage (`.json` files). Ideal for local development and smaller projects.
- **SQLite Storage**: A robust, file-based relational database (`.db` files). Offers efficient querying capabilities for
  larger trace datasets.

Specify your desired storage backend using the `--trace-file` option with either a `.json` or `.db` extension.

### CLI Trace Explorer

Use the `agenthelm traces` command to interact with your stored execution traces:

#### List Traces

List recent traces with pagination:

```bash
agenthelm traces list --limit 5 --offset 0 --trace-file my_traces.db
agenthelm traces list --json # Output in JSON format
```

#### Show Trace Details

View detailed information for a specific trace ID:

```bash
agenthelm traces show 0 --trace-file my_traces.db
```

#### Filter Traces

Filter traces by various criteria:

```bash
agenthelm traces filter --tool-name read_file --status failed --date-from 2025-11-01 --trace-file my_traces.db
agenthelm traces filter --min-time 1.0 --confidence-max 0.5 --json
```

#### Export Traces

Export filtered traces to different formats (CSV, JSON, Markdown):

```bash
agenthelm traces export --output report.csv --format csv --status failed --trace-file my_traces.db
agenthelm traces export --output all_traces.json --format json
agenthelm traces export --output summary.md --format md --tool-name search_web
```

---

## The Agent Helm Ecosystem

```mermaid
graph TD
subgraph "AgentHelm Ecosystem"
    direction LR
    A[User Task] --> AH(AgentHelm Orchestrator)
    AH --  Sends prompt/tools --> LLM(LLM Engine e.g., Mistral)
    LLM --  Returns tool_call --> AH
    AH --  Executes tool --> T1[Tool: get_weather]
    AH --  Executes tool --> T2[Tool: post_tweet]
    AH --  Executes tool --> T3[Tool: ...]
    T1 --  Returns result --> AH
    T2 --  Returns result --> AH
    AH --  Sends result to LLM --> LLM
    LLM -- Returns final answer --> AH
    AH -- Returns to User --> UO[Final Output]
end

style AH fill:#007BFF,stroke:#333,stroke-width:2px,color:#fff
style LLM fill:#FFC107,stroke:#333,stroke-width:2px,color:#000        
```

## The Trace Explorer

```mermaid
graph TD
    A[Agent Execution] --> B{Storage Backend}
    B -->|JSON| C[JSON File]
    B -->|SQLite| D[SQLite DB]
    C --> E[CLI Trace Explorer]
    D --> E
    E --> F[traces list]
    E --> G[traces show]
    E --> H[traces filter]
    E --> I[traces export]
    I -->|CSV| J[report.csv]
    I -->|JSON| K[data.json]
    I -->|Markdown| L[summary.md]
    style B fill: #007BFF, stroke: #333, stroke-width: 2px, color: #fff
    style E fill: #FFC107, stroke: #333, stroke-width: 2px, color: #000

```

## Quick Start

### 1. Installation

```bash
pip install agenthelm
```

### 2. Create your Tools

Create a Python file (e.g., `tools.py`) and define your functions with the `@tool` decorator. AgentHelm automatically parses the function signature to build the contract.

```python
# tools.py
from orchestrator import tool

@tool()
def get_weather(city: str) -> str:
    """Gets the current weather for a given city."""
    if city == "New York":
        return "It is 24°C and sunny in New York."
    else:
        return f"Sorry, I don't know the weather for {city}."

@tool(requires_approval=True)
def post_tweet(message: str) -> dict:
    """Posts a message to a social media feed."""
    print(f"TWEETING: {message}")
    return {"status": "posted"}
```

### 3. Environment Variables

AgentHelm requires API keys for the Large Language Models (LLMs) it interacts with. Set these as environment variables:

-   **Mistral AI**: Set `MISTRAL_API_KEY`. Optionally, set `MISTRAL_MODEL_NAME` (defaults to `mistral-small-latest`).
    ```bash
    export MISTRAL_API_KEY="your_mistral_api_key_here"
    # export MISTRAL_MODEL_NAME="mistral-large-latest"
    ```
-   **OpenAI**: Set `OPENAI_API_KEY`. Optionally, set `OPENAI_MODEL_NAME` (defaults to `gpt-4`).
    ```bash
    export OPENAI_API_KEY="your_openai_api_key_here"
    # export OPENAI_MODEL_NAME="gpt-3.5-turbo"
    ```

### 4. Run the Agent

Use the `agenthelm` command-line tool (or `python -m main`) to run your agent. The CLI handles everything from setting up the agent to running the reasoning loop and logging the traces.

```bash
# Run the agent from your terminal
agenthelm run \
  --agent-file examples/cli_tools_example/my_agent_tools.py \
  --task "What is the weather in New York?"

# For verbose output, add the -v or --verbose flag
agenthelm run \
  --agent-file examples/cli_tools_example/my_agent_tools.py \
  --task "What is the weather in New York?" \
  --llm-type mistral \
  --verbose

# To specify the output trace file, use the --trace-file option
agenthelm run \
  --agent-file examples/cli_tools_example/my_agent_tools.py \
  --task "What is the weather in New York?" \
  --trace-file my_trace.json
```

This will produce a detailed trace file (by default `cli_trace.json`), giving you a perfect record of the agent's
execution.

## Documentation

For comprehensive guides, tutorials, and API reference, please visit our official documentation site: [https://hadywalied.github.io/agenthelm/](https://hadywalied.github.io/agenthelm/)

## Contributing

We welcome contributions! Please feel free to open an issue or submit a pull request.
