# VelenAI SDK

Agent economics in 2 lines of code. Track ROI, KPIs, and cost for your AI agents.

**Langfuse is the debugger. VelenAI is the CFO.**

## Install

```bash
pip install velenai
```

With framework adapters:

```bash
pip install velenai[crewai]    # CrewAI adapter
pip install velenai[langgraph]  # LangGraph adapter
pip install velenai[autogen]    # AutoGen adapter
```

## Quick Start

```python
from velenai_sdk import VelenAI

vai = VelenAI(api_key="your-key", api_secret="your-secret", host="http://localhost:8000")
```

### Decorator (simplest)

```python
@vai.track("my-agent")
def run_agent(query: str):
    result = llm.chat(query)
    return result

# Async works too
@vai.track("my-async-agent")
async def run_agent(query: str):
    return await llm.chat(query)
```

### Context Manager (more control)

```python
with vai.trace("my-agent") as t:
    result = do_work()
    t.success = True
    t.tokens = 150
    t.cost_usd = 0.003
    t.metadata["model"] = "gpt-4"
```

### Manual

```python
vai.emit(
    agent_id="my-agent",
    success=True,
    latency_ms=1200,
    tokens=150,
    cost_usd=0.003,
    metadata={"model": "gpt-4"},
)
```

## Framework Adapters

### CrewAI

```python
from velenai_sdk import VelenAI
from velenai_sdk.adapters.crewai import VelenAICrewCallback

vai = VelenAI()
crew = Crew(
    agents=[researcher, writer],
    tasks=[research_task, write_task],
    callbacks=[VelenAICrewCallback(vai)]
)
```

### LangGraph

```python
from velenai_sdk import VelenAI
from velenai_sdk.adapters.langgraph import instrument_graph

vai = VelenAI()
graph = StateGraph(...).compile()
graph = instrument_graph(vai, graph, agent_id="my-workflow")
result = graph.invoke(input)
```

Or as a LangChain callback:

```python
from velenai_sdk.adapters.langgraph import VelenAILangGraphCallback

result = graph.invoke(input, config={"callbacks": [VelenAILangGraphCallback(vai)]})
```

### AutoGen

```python
from velenai_sdk import VelenAI
from velenai_sdk.adapters.autogen import instrument_agent

vai = VelenAI()
assistant = AssistantAgent("analyst", llm_config=llm_config)
assistant = instrument_agent(vai, assistant)
```

## Environment Variables

Instead of passing keys to the constructor:

```bash
export VELENAI_API_KEY=your-key
export VELENAI_API_SECRET=your-secret
export VELENAI_HOST=http://localhost:8000
```

```python
vai = VelenAI()  # picks up from env
```

## Features

- Sync and async support
- Background batching (events queued and flushed every 5s)
- HMAC-signed requests (replay-protected)
- Fire-and-forget (never blocks your agent)
- Framework adapters: CrewAI, LangGraph, AutoGen
- Zero dependencies beyond `httpx`
- Self-hosted and open source

## License

MIT
