Metadata-Version: 2.3
Name: idun-agent-engine
Version: 0.1.0
Summary: Python SDK and runtime to serve AI agents with FastAPI, LangGraph, and observability.
License: MIT
Keywords: agents,langgraph,fastapi,sdk,llm,observability
Author: Geoffrey HARRAZI
Author-email: geoffreyharrazi@gmail.com
Requires-Python: >=3.13,<3.14
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Software Development :: Libraries
Classifier: Typing :: Typed
Requires-Dist: ag-ui-protocol (>=0.1.8,<0.2.0)
Requires-Dist: aiosqlite (>=0.21.0,<0.22.0)
Requires-Dist: arize-phoenix (>=11.22.0,<12.0.0)
Requires-Dist: arize-phoenix-otel (>=0.2.0,<1.0.0)
Requires-Dist: fastapi (>=0.116.1,<0.117.0)
Requires-Dist: google-adk (>=1.9.0,<2.0.0)
Requires-Dist: httpx (>=0.28.1,<0.29.0)
Requires-Dist: langchain (>=0.3.27,<0.4.0)
Requires-Dist: langchain-core (>=0.3.72,<0.4.0)
Requires-Dist: langchain-google-vertexai (>=2.0.27,<3.0.0)
Requires-Dist: langfuse (>=3.2.2,<4.0.0)
Requires-Dist: langgraph (>=0.6.3,<0.7.0)
Requires-Dist: langgraph-checkpoint-sqlite (>=2.0.11,<3.0.0)
Requires-Dist: openinference-instrumentation-langchain (>=0.1.13,<1.0.0)
Requires-Dist: pydantic (>=2.11.7,<3.0.0)
Requires-Dist: streamlit (>=1.47.1,<2.0.0)
Requires-Dist: uvicorn (>=0.35.0,<0.36.0)
Project-URL: Documentation, https://github.com/geoffreyharrazi/idun-agent-manager/tree/main/libs/idun_agent_engine
Project-URL: Homepage, https://github.com/geoffreyharrazi/idun-agent-manager
Project-URL: Issues, https://github.com/geoffreyharrazi/idun-agent-manager/issues
Project-URL: Repository, https://github.com/geoffreyharrazi/idun-agent-manager
Description-Content-Type: text/markdown

# Idun Agent Engine - User Guide

The Idun Agent Engine provides a simple, powerful way to turn your conversational AI agents into production-ready web services. With just a few lines of code, you can expose your LangGraph, CrewAI, or custom agents through a FastAPI server with built-in features like streaming, persistence, and monitoring.

## 🚀 Quick Start

### Installation
```bash
pip install idun-agent-engine
```

### Basic Usage

```python
from idun_agent_engine import create_app, run_server

# Create your FastAPI app with your agent
app = create_app(config_path="config.yaml")

# Run the server
run_server(app, port=8000)
```

That's it! Your agent is now running at `http://localhost:8000` with full API documentation at `http://localhost:8000/docs`.

## 📋 Configuration

### Option 1: YAML Configuration File

Create a `config.yaml` file:

```yaml
engine:
  api:
    port: 8000
  telemetry:
    provider: "langfuse"

agent:
  type: "langgraph"
  config:
    name: "My Awesome Agent"
    graph_definition: "my_agent.py:graph"
    checkpointer:
      type: "sqlite"
      db_url: "sqlite:///agent.db"
```

### Option 2: Programmatic Configuration

```python
from idun_agent_engine import ConfigBuilder, create_app, run_server

config = (ConfigBuilder()
          .with_api_port(8080)
          .with_langgraph_agent(
              name="My Agent",
              graph_definition="my_agent.py:graph",
              sqlite_checkpointer="agent.db")
          .build())

app = create_app(config_dict=config)
run_server(app)
```

## 🤖 Supported Agent Types

### LangGraph Agents

```python
# Your LangGraph agent file (my_agent.py)
from langgraph.graph import StateGraph, END
from typing import TypedDict

class AgentState(TypedDict):
    messages: list

def my_node(state):
    # Your agent logic here
    return {"messages": [("ai", "Hello from LangGraph!")]}

graph = StateGraph(AgentState)
graph.add_node("agent", my_node)
graph.set_entry_point("agent")
graph.add_edge("agent", END)
```

### Future Agent Types
- CrewAI agents (coming soon)
- AutoGen agents (coming soon)
- Custom agent implementations

## 🌐 API Endpoints

Once your server is running, you get these endpoints automatically:

### POST `/agent/invoke`
Send a single message and get a complete response:

```bash
curl -X POST "http://localhost:8000/agent/invoke" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Hello, how are you?",
    "session_id": "user-123"
  }'
```

### POST `/agent/stream`
Stream responses in real-time:

```bash
curl -X POST "http://localhost:8000/agent/stream" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Tell me a story",
    "session_id": "user-123"
  }'
```

### GET `/health`
Health check for monitoring:

```bash
curl "http://localhost:8000/health"
```

## 🔧 Advanced Usage

### Development Mode
```python
# Enable auto-reload for development
run_server(app, reload=True)
```

### Production Deployment
```python
# Run with multiple workers for production
run_server(app, workers=4, host="0.0.0.0", port=8000)
```

### One-Line Server
```python
from idun_agent_engine.core.server_runner import run_server_from_config

# Create and run server in one call
run_server_from_config("config.yaml", port=8080, reload=True)
```

### Custom FastAPI Configuration
```python
from idun_agent_engine import create_app
from fastapi.middleware.cors import CORSMiddleware

app = create_app("config.yaml")

# Add custom middleware
app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],
    allow_methods=["*"],
    allow_headers=["*"],
)

# Add custom routes
@app.get("/custom")
def custom_endpoint():
    return {"message": "Custom endpoint"}
```

## 🛠️ Configuration Reference

### Engine Configuration
```yaml
engine:
  api:
    port: 8000                    # Server port
  telemetry:
    provider: "langfuse"          # Telemetry provider
```

### LangGraph Agent Configuration
```yaml
agent:
  type: "langgraph"
  config:
    name: "Agent Name"            # Human-readable name
    graph_definition: "path.py:graph"  # Path to your graph
    checkpointer:                 # Optional persistence
      type: "sqlite"
      db_url: "sqlite:///agent.db"
    store:                        # Optional store (future)
      type: "memory"
```

## 📚 Examples

Check out the `examples/` directory for complete working examples:

- **Basic LangGraph Agent**: Simple question-answering agent
- **ConfigBuilder Usage**: Programmatic configuration
- **Custom Middleware**: Adding authentication and CORS
- **Production Setup**: Multi-worker deployment configuration

## 🔍 Validation and Debugging

```python
from idun_agent_engine.utils.validation import validate_config_dict, diagnose_setup

# Validate your configuration
config = {...}
errors = validate_config_dict(config)
if errors:
    print("Configuration errors:", errors)

# Diagnose your setup
diagnosis = diagnose_setup()
print("System diagnosis:", diagnosis)
```

## 🚀 Deployment

### Docker
```dockerfile
FROM python:3.11-slim

COPY requirements.txt .
RUN pip install -r requirements.txt

COPY . .

CMD ["python", "-m", "idun_agent_engine", "run", "config.yaml"]
```

### Cloud Platforms
- Heroku: `Procfile` with `web: python main.py`
- Railway: Deploy with one click
- AWS Lambda: Use with Mangum adapter
- Google Cloud Run: Deploy Docker container

## 🤝 Contributing

The Idun Agent Engine is designed to be extensible. To add support for new agent frameworks:

1. Implement the `BaseAgent` interface
2. Add configuration models for your agent type
3. Register your agent in the factory
4. Submit a pull request!

## 📖 Documentation

- [Full API Documentation](https://docs.idun-agent-engine.com)
- [Agent Framework Guide](https://docs.idun-agent-engine.com/frameworks)
- [Deployment Guide](https://docs.idun-agent-engine.com/deployment)
- [Contributing Guide](https://docs.idun-agent-engine.com/contributing)

## 📄 License

MIT License - see LICENSE file for details.

---

### Release & Publishing

This package is built with Poetry. To publish a new release to PyPI:

1. Update version in `pyproject.toml`.
2. Commit and tag with the pattern `idun-agent-engine-vX.Y.Z`.
3. Push the tag to GitHub. The `Publish idun-agent-engine` workflow will build and publish to PyPI using `PYPI_API_TOKEN` secret.

Manual build (optional):

```bash
cd libs/idun_agent_engine
poetry build
```

