Metadata-Version: 2.4
Name: gaunt
Version: 0.1.0
Summary: Python SDK for logging LLM traces to an analytics scoring API.
Project-URL: Homepage, https://example.com/gaunt
Project-URL: Repository, https://github.com/your-org/gaunt
Project-URL: Issues, https://github.com/your-org/gaunt/issues
Author: LLM Analytics Team
License: MIT
Keywords: analytics,evaluation,llm,observability,rag,sdk
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: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: httpx<1.0,>=0.24
Requires-Dist: pydantic<3.0,>=2.0
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: mypy>=1.8; extra == 'dev'
Requires-Dist: pytest>=7.4; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Requires-Dist: twine>=5.0; extra == 'dev'
Description-Content-Type: text/markdown

# LLM Analytics Python SDK

Python SDK for collecting LLM app traces (chat, RAG, vision, structured output), standardizing them, and sending them to an Analytics Bank API for scoring.

## Features
- Pydantic v2 strict payload models.
- Sync and async clients via `httpx`.
- Built-in scoring tags via `ScoringTag`.
- Automatic UUID generation for `trace_id`.

## Installation
```bash
pip install gaunt
```

For local development:
```bash
pip install -e ".[dev]"
```

## Quickstart
```python
from gaunt import Client, ScoringTag

client = Client(
    api_key="sk_live_xxx",
    base_url="https://analytics-bank.example.com",
)

result = client.log(
    project_id="project_123",
    inputs={
        "messages": [
            {"role": "system", "content": "You are a concise assistant."},
            {"role": "user", "content": "What is RAG?"},
        ],
        "rag_context": [
            {"content": "RAG combines retrieval and generation.", "source_id": "doc-1"},
        ],
    },
    outputs={
        "raw": "RAG uses retrieved knowledge to ground generations.",
    },
    expected={"topic": "rag"},
    metadata={"env": "prod"},
    scoring_tags=[
        ScoringTag.RAG_FAITHFULNESS,
        ScoringTag.ANSWER_CORRECTNESS,
    ],
)

print(result)
client.close()
```

## Scoring Tags
- `ScoringTag.SCHEMA_VALIDITY` -> `score:schema_validity`
- `ScoringTag.RAG_FAITHFULNESS` -> `score:rag_faithfulness`
- `ScoringTag.VISION_HALLUCINATION` -> `score:vision_hallucination`
- `ScoringTag.TOXICITY` -> `score:toxicity`
- `ScoringTag.NUMERIC_SCORING` -> `score:numeric_scoring`
- `ScoringTag.ANSWER_CORRECTNESS` -> `score:answer_correctness`

## Payload Shape
The SDK emits payloads in this form:

```json
{
  "project_id": "project_123",
  "trace_id": "uuid...",
  "inputs": {
    "messages": [],
    "images": [],
    "rag_context": [],
    "json_schema": {}
  },
  "outputs": {
    "raw": "...",
    "parsed": {}
  },
  "expected": {},
  "metadata": {},
  "config": {
    "scoring_tags": ["score:rag_faithfulness", "score:schema_validity"]
  }
}
```

## Testing
```bash
pytest -q
```

## Publishing
See `docs/publishing.md` for a release checklist and TestPyPI/PyPI upload commands.
