Metadata-Version: 2.4
Name: velenai
Version: 0.1.0
Summary: Agent economics SDK — track ROI, KPIs, and cost for AI agents in 2 lines of code
Project-URL: Homepage, https://github.com/loladebabalola/velenai
Project-URL: Repository, https://github.com/loladebabalola/velenai
Project-URL: Documentation, https://github.com/loladebabalola/velenai/tree/main/sdk
Project-URL: Issues, https://github.com/loladebabalola/velenai/issues
Author-email: Lolade Babalola <joshua@humigence.com>
License-Expression: MIT
Keywords: agents,ai,autogen,crewai,economics,kpi,langgraph,llm,observability,roi,telemetry
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
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: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.9
Requires-Dist: httpx>=0.24
Provides-Extra: autogen
Requires-Dist: pyautogen>=0.2; extra == 'autogen'
Provides-Extra: crewai
Requires-Dist: crewai>=0.30; extra == 'crewai'
Provides-Extra: langgraph
Requires-Dist: langgraph>=0.1; extra == 'langgraph'
Description-Content-Type: text/markdown

# 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
