Metadata-Version: 2.4
Name: kpi-agentes
Version: 0.1.0
Summary: SDK para monitoramento e observabilidade de agentes de IA — KPI Agentes
Project-URL: Homepage, https://github.com/seu-usuario/kpi-agentes
Project-URL: Repository, https://github.com/seu-usuario/kpi-agentes
Project-URL: Bug Tracker, https://github.com/seu-usuario/kpi-agentes/issues
License: MIT
License-File: LICENSE
Keywords: agents,ai,kpi,llm,monitoring,observability,rag
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.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: httpx>=0.24.0
Provides-Extra: dev
Requires-Dist: build; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: pytest-asyncio; extra == 'dev'
Requires-Dist: twine; extra == 'dev'
Description-Content-Type: text/markdown

# kpi-agentes

SDK Python para monitoramento e observabilidade de agentes de IA.

Integre qualquer agente LLM em segundos e acompanhe **Faithfulness**, **Relevancy**,
**latência**, **custo por token** e muito mais no painel KPI Agentes.

## Instalação

```bash
pip install kpi-agentes
```

## Início rápido

```python
import time
import asyncio
from kpi_agentes import KPIReporter

# Inicialize uma vez (após as configs globais do seu app)
kpi = KPIReporter(
    agent_id = "uuid-do-seu-agente",   # obtido no painel KPI Agentes
    base_url = "https://seu-servidor.com",
)

# No endpoint de chat — fire-and-forget, não atrasa a resposta
@app.post("/chat")
async def chat(request):
    _t0 = time.monotonic()
    result = await run_agent(request.message)

    asyncio.create_task(kpi.report(
        question         = request.message,
        answer           = result["reply"],
        context_chunks   = result.get("context_chunks", []),   # habilita RAG metrics
        provider         = "gemini",
        model            = "gemini-2.5-flash",
        total_latency_ms = int((time.monotonic() - _t0) * 1000),
        status           = "completed",
    ))

    return result
```

## Parâmetros do `KPIReporter`

| Parâmetro         | Tipo    | Obrigatório | Descrição |
|-------------------|---------|-------------|-----------|
| `agent_id`        | `str`   | ✅          | UUID do agente no painel KPI |
| `agent_version_id`| `str`   | ❌          | UUID da versão (para comparação A/B) |
| `base_url`        | `str`   | ❌          | URL do backend KPI (padrão: `http://localhost:8001`) |
| `timeout`         | `float` | ❌          | Timeout HTTP em segundos (padrão: `8.0`) |
| `enabled`         | `bool`  | ❌          | `False` desativa sem remover código (padrão: `True`) |

## Parâmetros do `kpi.report()`

| Parâmetro           | Tipo           | Descrição |
|---------------------|----------------|-----------|
| `question`          | `str`          | Pergunta do usuário |
| `answer`            | `str`          | Resposta do agente |
| `context_chunks`    | `list[str]`    | Trechos do RAG (habilita Faithfulness/Relevancy) |
| `provider`          | `str`          | Ex: `"gemini"`, `"openai"`, `"groq"` |
| `model`             | `str`          | Ex: `"gemini-2.5-flash"`, `"gpt-4o-mini"` |
| `total_latency_ms`  | `int`          | Latência total em ms |
| `ttft_ms`           | `int`          | Time to First Token em ms |
| `prompt_tokens`     | `int`          | Tokens de entrada |
| `completion_tokens` | `int`          | Tokens de saída |
| `tool_results`      | `list[dict]`   | Resultados de tool calls |
| `user_guid`         | `str`          | ID do usuário (anonimizado) |
| `session_id`        | `str`          | ID da sessão |
| `status`            | `str`          | `"completed"` \| `"error"` \| `"timeout"` |
| `metadata`          | `dict`         | Dados adicionais livres |

## KPIs monitorados

- **Faithfulness** — fidelidade da resposta ao contexto RAG
- **Relevancy** — relevância da resposta à pergunta
- **Latência** — p50, p95, p99 e média
- **TTFT** — Time to First Token
- **Custo por interação** — baseado em token usage
- **Success Rate** — taxa de resoluções bem-sucedidas
- **Error Rate** — taxa de erros
- **Tool Calls** — rastreamento de chamadas de ferramentas

## Requisitos

- Python 3.10+
- `httpx` (instalado automaticamente)
- Backend **KPI Agentes** rodando e acessível

## Licença

MIT
