tracia 0.0.1__tar.gz → 0.1.1__tar.gz

tracia-0.1.1/.claude/settings.local.json

@@ -0,0 +1,48 @@
+{
+  "permissions": {
+    "allow": [
+      "WebFetch(domain:ai-sdk.dev)",
+      "WebFetch(domain:github.com)",
+      "WebFetch(domain:mintlify.com)",
+      "WebSearch",
+
+      "Bash(python:*)",
+      "Bash(python3:*)",
+      "Bash(python manage.py:*)",
+      "Bash(pip install:*)",
+      "Bash(pip show:*)",
+      "Bash(/opt/homebrew/bin/python3.10:*)",
+      "Bash(/opt/homebrew/bin/python3.10 -m pip install:*)",
+
+      "Bash(npm install:*)",
+      "Bash(npm run build:*)",
+      "Bash(npm run dev:*)",
+      "Bash(npm test:*)",
+      "Bash(npm show:*)",
+      "Bash(npm view:*)",
+      "Bash(npm ls:*)",
+      "Bash(npx tsc:*)",
+      "Bash(npx vitest run:*)",
+      "Bash(pnpm test:*)",
+      "Bash(pnpm typecheck:*)",
+
+      "Bash(mint dev:*)",
+
+      "Bash(find:*)",
+      "Bash(tree:*)",
+      "Bash(grep:*)",
+      "Bash(ls:*)",
+      "Bash(cat:*)",
+      "Bash(xargs:*)",
+      "Bash(curl:*)",
+
+      "Bash(git show:*)",
+      "Bash(git diff:*)",
+      "Bash(git log:*)",
+      "Bash(git status:*)",
+      "Bash(git branch:*)",
+      "Bash(git check-ignore:*)",
+      "Bash(git -C /Users/dm/work/tracia/*:*)"
+    ]
+  }
+}

tracia-0.1.1/.gitignore

@@ -0,0 +1,30 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+dist/
+build/
+*.egg-info/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.mypy_cache/
+
+# OS
+.DS_Store
+Thumbs.db

tracia-0.1.1/CLAUDE.md

@@ -0,0 +1,112 @@
+# Tracia Python SDK
+
+Python SDK for Tracia — the developer tool for storing, testing, and tracing LLM prompts. Published to PyPI as `tracia`.
+
+This is the Python counterpart to `tracia-node`. Both SDKs implement the same v1 API surface. See `~/work/tracia/sdk-parity.md` for the canonical mapping between them.
+
+## Coding Standards
+
+### Naming
+- ALWAYS use descriptive variable/parameter names
+- NEVER use single-letter names (`p`, `r`, `k`) except in trivial callbacks like list comprehensions
+- Use domain terminology: `prompt`, `span`, `provider`, `api_key`
+
+### Comments
+- Do NOT add comments that just describe what's obvious from names
+- Only comment on WHY, not WHAT
+
+### Enums and Constants
+- ALWAYS use enums/constants for fixed values, never hardcoded strings
+- Enums defined in `tracia/_errors.py` (TraciaErrorCode) and `tracia/_types.py` (LLMProvider)
+
+## Tech Stack
+
+- Python 3.10+
+- httpx for HTTP requests (sync + async)
+- Pydantic 2.0+ for type definitions and validation
+- LiteLLM for unified LLM provider abstraction
+- Hatchling for building
+- pytest + pytest-asyncio for testing
+- mypy (strict) for type checking
+- ruff for linting
+
+## Project Structure
+
+```
+tracia-python/
+├── tracia/
+│   ├── __init__.py          # Public API exports (55+ types)
+│   ├── _client.py           # Main Tracia class (run_local, sessions, span scheduling)
+│   ├── _types.py            # All Pydantic type definitions
+│   ├── _http.py             # HttpClient + AsyncHttpClient (httpx-based)
+│   ├── _llm.py              # LiteLLM wrapper (provider resolution, message conversion)
+│   ├── _session.py          # TraciaSession (multi-turn trace linking)
+│   ├── _streaming.py        # LocalStream + AsyncLocalStream
+│   ├── _errors.py           # TraciaError + TraciaErrorCode enum
+│   ├── _utils.py            # ID generation, validation, variable interpolation
+│   ├── _constants.py        # BASE_URL, timeouts, retry config, env var mapping
+│   ├── py.typed             # PEP 561 marker
+│   └── resources/
+│       ├── __init__.py
+│       ├── prompts.py       # Prompts resource (list, get, create, update, delete, run)
+│       └── spans.py         # Spans resource (create, get, list, evaluate)
+├── tests/
+│   ├── test_client.py
+│   ├── test_errors.py
+│   ├── test_llm.py
+│   ├── test_types.py
+│   └── test_utils.py
+└── pyproject.toml           # Build config + dependencies
+```
+
+## Key Patterns
+
+### Dual sync/async
+Every public method has both sync and async variants. Async methods use the `a` prefix:
+- `run_local()` / `arun_local()`
+- `prompts.list()` / `prompts.alist()`
+- `spans.create()` / `spans.acreate()`
+- `flush()` / `aflush()`
+- `close()` / `aclose()`
+
+### Pydantic models with camelCase aliases
+All types use snake_case fields with `Field(alias="camelCase")` for API serialization:
+```python
+class RunLocalResult(BaseModel):
+    model_config = ConfigDict(populate_by_name=True)
+    span_id: str = Field(alias="spanId")
+    trace_id: str = Field(alias="traceId")
+```
+
+### Background span creation
+Spans are submitted to the API in the background using `ThreadPoolExecutor`. Max 1000 pending spans, 2 retry attempts with 500ms delay.
+
+### LiteLLM integration
+Provider abstraction via LiteLLM. Supports OpenAI, Anthropic, Google. LiteLLM is imported dynamically with a helpful error message if missing.
+
+### Context manager support
+```python
+with Tracia(api_key="...") as client:
+    result = client.run_local(...)
+# Resources cleaned up automatically
+```
+
+## How to Add New Methods
+
+1. Add the type definitions to `tracia/_types.py` (Pydantic BaseModel, snake_case fields, camelCase aliases)
+2. Add the method to the appropriate resource (`resources/prompts.py` or `resources/spans.py`) or to `_client.py`
+3. Create BOTH sync and async variants
+4. Export new types from `tracia/__init__.py`
+5. Update `~/work/tracia/sdk-parity.md` with the new mapping
+6. Check `~/work/tracia/tracia-node/` to verify the Node SDK has the equivalent
+
+## Commands
+
+```bash
+pip install -e ".[dev]"           # Install with dev dependencies
+pytest                            # Run tests
+pytest --cov=tracia               # Run tests with coverage
+mypy tracia/                      # Type checking (strict)
+ruff check tracia/                # Lint
+ruff format tracia/               # Format
+```

tracia-0.1.1/PKG-INFO

@@ -0,0 +1,277 @@
+Metadata-Version: 2.4
+Name: tracia
+Version: 0.1.1
+Summary: LLM prompt management and tracing SDK
+Project-URL: Homepage, https://tracia.io
+Project-URL: Documentation, https://docs.tracia.io
+Project-URL: Repository, https://github.com/tracia/tracia-python
+Project-URL: Issues, https://github.com/tracia/tracia-python/issues
+Author-email: Tracia <hello@tracia.io>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai,anthropic,chatgpt,claude,gemini,google,litellm,llm,observability,openai,prompt,tracing
+Classifier: Development Status :: 4 - Beta
+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: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.25.0
+Requires-Dist: litellm>=1.30.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: typing-extensions>=4.0.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: respx>=0.20.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Tracia
+
+**LLM prompt management and tracing SDK for Python**
+
+[![PyPI version](https://badge.fury.io/py/tracia.svg)](https://badge.fury.io/py/tracia)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## What is Tracia?
+
+Tracia is a modern LLM prompt management and tracing platform. This Python SDK provides:
+
+- **Unified LLM Access** - Call OpenAI, Anthropic, Google, and 100+ providers through a single interface (powered by LiteLLM)
+- **Automatic Tracing** - Every LLM call is automatically traced with latency, token usage, and cost
+- **Prompt Management** - Store, version, and manage your prompts in the cloud
+- **Session Linking** - Easily link related calls for multi-turn conversations
+
+## Installation
+
+```bash
+pip install tracia
+```
+
+You'll also need API keys for the LLM providers you want to use:
+```bash
+export OPENAI_API_KEY="sk-..."
+export ANTHROPIC_API_KEY="sk-ant-..."
+export GOOGLE_API_KEY="..."
+```
+
+## Quick Start
+
+```python
+from tracia import Tracia
+
+# Initialize the client
+client = Tracia(api_key="your_tracia_api_key")
+
+# Run a local prompt
+result = client.run_local(
+    model="gpt-4o",
+    messages=[{"role": "user", "content": "Hello!"}]
+)
+print(result.text)
+print(f"Tokens: {result.usage.total_tokens}")
+```
+
+## Streaming
+
+```python
+# Stream the response
+stream = client.run_local(
+    model="gpt-4o",
+    messages=[{"role": "user", "content": "Tell me a story"}],
+    stream=True
+)
+
+for chunk in stream:
+    print(chunk, end="", flush=True)
+
+# Get the final result (stream.result is a Future[StreamResult])
+final = stream.result.result()
+print(f"\nTotal tokens: {final.usage.total_tokens}")
+```
+
+## Multi-turn Conversations with Sessions
+
+```python
+# Create a session for linked conversations
+session = client.create_session()
+
+# First message
+r1 = session.run_local(
+    model="gpt-4o",
+    messages=[{"role": "user", "content": "My name is Alice"}]
+)
+
+# Follow-up - automatically linked to the same trace
+r2 = session.run_local(
+    model="gpt-4o",
+    messages=[
+        {"role": "user", "content": "My name is Alice"},
+        {"role": "assistant", "content": r1.text},
+        {"role": "user", "content": "What's my name?"}
+    ]
+)
+```
+
+## Function Calling
+
+```python
+from tracia import ToolDefinition, ToolParameters, JsonSchemaProperty
+
+# Define a tool
+tools = [
+    ToolDefinition(
+        name="get_weather",
+        description="Get the current weather",
+        parameters=ToolParameters(
+            properties={
+                "location": JsonSchemaProperty(
+                    type="string",
+                    description="City name"
+                )
+            },
+            required=["location"]
+        )
+    )
+]
+
+result = client.run_local(
+    model="gpt-4o",
+    messages=[{"role": "user", "content": "What's the weather in Paris?"}],
+    tools=tools
+)
+
+if result.tool_calls:
+    for call in result.tool_calls:
+        print(f"Tool: {call.name}, Args: {call.arguments}")
+```
+
+## Variable Interpolation
+
+```python
+result = client.run_local(
+    model="gpt-4o",
+    messages=[
+        {"role": "system", "content": "You are a helpful assistant named {{name}}."},
+        {"role": "user", "content": "Hello!"}
+    ],
+    variables={"name": "Claude"}
+)
+```
+
+## Prompts API
+
+```python
+# List all prompts
+prompts = client.prompts.list()
+
+# Get a specific prompt
+prompt = client.prompts.get("my-prompt")
+
+# Run a prompt template
+result = client.prompts.run(
+    "my-prompt",
+    variables={"name": "World"}
+)
+```
+
+## Spans API
+
+```python
+from tracia import Eval, EvaluateOptions
+
+# List spans
+spans = client.spans.list()
+
+# Evaluate a span
+client.spans.evaluate(
+    "sp_xxx",
+    EvaluateOptions(
+        evaluator="quality",
+        value=Eval.POSITIVE,  # or Eval.NEGATIVE
+        note="Great response!",
+    ),
+)
+```
+
+## Async Support
+
+All methods have async variants:
+
+```python
+import asyncio
+
+async def main():
+    async with Tracia(api_key="...") as client:
+        result = await client.arun_local(
+            model="gpt-4o",
+            messages=[{"role": "user", "content": "Hello!"}]
+        )
+        print(result.text)
+
+asyncio.run(main())
+```
+
+## Supported Providers
+
+Via LiteLLM, Tracia supports 100+ providers including:
+
+- **OpenAI**: gpt-4o, gpt-4, gpt-3.5-turbo, o1, o3
+- **Anthropic**: claude-3-opus, claude-sonnet-4, claude-3-haiku
+- **Google**: gemini-2.0-flash, gemini-2.5-pro
+- And many more...
+
+## Error Handling
+
+```python
+from tracia import TraciaError, TraciaErrorCode
+
+try:
+    result = client.run_local(...)
+except TraciaError as e:
+    if e.code == TraciaErrorCode.MISSING_PROVIDER_API_KEY:
+        print("Please set your API key")
+    elif e.code == TraciaErrorCode.PROVIDER_ERROR:
+        print(f"LLM error: {e.message}")
+```
+
+## Configuration Options
+
+```python
+client = Tracia(
+    api_key="...",
+    base_url="https://app.tracia.io",  # Custom API URL
+    on_span_error=lambda e, span_id: print(f"Span error: {e}")
+)
+
+result = client.run_local(
+    model="gpt-4o",
+    messages=[...],
+    temperature=0.7,
+    max_output_tokens=1000,
+    timeout_ms=30000,
+    tags=["production"],
+    user_id="user_123",
+    session_id="session_456",
+    send_trace=True,  # Set to False to disable tracing
+)
+```
+
+## Learn More
+
+- Website: [tracia.io](https://tracia.io)
+- Documentation: [docs.tracia.io](https://docs.tracia.io)
+- GitHub: [github.com/tracia](https://github.com/tracia)
+
+## License
+
+MIT

tracia-0.1.1/README.md

@@ -0,0 +1,241 @@
+# Tracia
+
+**LLM prompt management and tracing SDK for Python**
+
+[![PyPI version](https://badge.fury.io/py/tracia.svg)](https://badge.fury.io/py/tracia)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## What is Tracia?
+
+Tracia is a modern LLM prompt management and tracing platform. This Python SDK provides:
+
+- **Unified LLM Access** - Call OpenAI, Anthropic, Google, and 100+ providers through a single interface (powered by LiteLLM)
+- **Automatic Tracing** - Every LLM call is automatically traced with latency, token usage, and cost
+- **Prompt Management** - Store, version, and manage your prompts in the cloud
+- **Session Linking** - Easily link related calls for multi-turn conversations
+
+## Installation
+
+```bash
+pip install tracia
+```
+
+You'll also need API keys for the LLM providers you want to use:
+```bash
+export OPENAI_API_KEY="sk-..."
+export ANTHROPIC_API_KEY="sk-ant-..."
+export GOOGLE_API_KEY="..."
+```
+
+## Quick Start
+
+```python
+from tracia import Tracia
+
+# Initialize the client
+client = Tracia(api_key="your_tracia_api_key")
+
+# Run a local prompt
+result = client.run_local(
+    model="gpt-4o",
+    messages=[{"role": "user", "content": "Hello!"}]
+)
+print(result.text)
+print(f"Tokens: {result.usage.total_tokens}")
+```
+
+## Streaming
+
+```python
+# Stream the response
+stream = client.run_local(
+    model="gpt-4o",
+    messages=[{"role": "user", "content": "Tell me a story"}],
+    stream=True
+)
+
+for chunk in stream:
+    print(chunk, end="", flush=True)
+
+# Get the final result (stream.result is a Future[StreamResult])
+final = stream.result.result()
+print(f"\nTotal tokens: {final.usage.total_tokens}")
+```
+
+## Multi-turn Conversations with Sessions
+
+```python
+# Create a session for linked conversations
+session = client.create_session()
+
+# First message
+r1 = session.run_local(
+    model="gpt-4o",
+    messages=[{"role": "user", "content": "My name is Alice"}]
+)
+
+# Follow-up - automatically linked to the same trace
+r2 = session.run_local(
+    model="gpt-4o",
+    messages=[
+        {"role": "user", "content": "My name is Alice"},
+        {"role": "assistant", "content": r1.text},
+        {"role": "user", "content": "What's my name?"}
+    ]
+)
+```
+
+## Function Calling
+
+```python
+from tracia import ToolDefinition, ToolParameters, JsonSchemaProperty
+
+# Define a tool
+tools = [
+    ToolDefinition(
+        name="get_weather",
+        description="Get the current weather",
+        parameters=ToolParameters(
+            properties={
+                "location": JsonSchemaProperty(
+                    type="string",
+                    description="City name"
+                )
+            },
+            required=["location"]
+        )
+    )
+]
+
+result = client.run_local(
+    model="gpt-4o",
+    messages=[{"role": "user", "content": "What's the weather in Paris?"}],
+    tools=tools
+)
+
+if result.tool_calls:
+    for call in result.tool_calls:
+        print(f"Tool: {call.name}, Args: {call.arguments}")
+```
+
+## Variable Interpolation
+
+```python
+result = client.run_local(
+    model="gpt-4o",
+    messages=[
+        {"role": "system", "content": "You are a helpful assistant named {{name}}."},
+        {"role": "user", "content": "Hello!"}
+    ],
+    variables={"name": "Claude"}
+)
+```
+
+## Prompts API
+
+```python
+# List all prompts
+prompts = client.prompts.list()
+
+# Get a specific prompt
+prompt = client.prompts.get("my-prompt")
+
+# Run a prompt template
+result = client.prompts.run(
+    "my-prompt",
+    variables={"name": "World"}
+)
+```
+
+## Spans API
+
+```python
+from tracia import Eval, EvaluateOptions
+
+# List spans
+spans = client.spans.list()
+
+# Evaluate a span
+client.spans.evaluate(
+    "sp_xxx",
+    EvaluateOptions(
+        evaluator="quality",
+        value=Eval.POSITIVE,  # or Eval.NEGATIVE
+        note="Great response!",
+    ),
+)
+```
+
+## Async Support
+
+All methods have async variants:
+
+```python
+import asyncio
+
+async def main():
+    async with Tracia(api_key="...") as client:
+        result = await client.arun_local(
+            model="gpt-4o",
+            messages=[{"role": "user", "content": "Hello!"}]
+        )
+        print(result.text)
+
+asyncio.run(main())
+```
+
+## Supported Providers
+
+Via LiteLLM, Tracia supports 100+ providers including:
+
+- **OpenAI**: gpt-4o, gpt-4, gpt-3.5-turbo, o1, o3
+- **Anthropic**: claude-3-opus, claude-sonnet-4, claude-3-haiku
+- **Google**: gemini-2.0-flash, gemini-2.5-pro
+- And many more...
+
+## Error Handling
+
+```python
+from tracia import TraciaError, TraciaErrorCode
+
+try:
+    result = client.run_local(...)
+except TraciaError as e:
+    if e.code == TraciaErrorCode.MISSING_PROVIDER_API_KEY:
+        print("Please set your API key")
+    elif e.code == TraciaErrorCode.PROVIDER_ERROR:
+        print(f"LLM error: {e.message}")
+```
+
+## Configuration Options
+
+```python
+client = Tracia(
+    api_key="...",
+    base_url="https://app.tracia.io",  # Custom API URL
+    on_span_error=lambda e, span_id: print(f"Span error: {e}")
+)
+
+result = client.run_local(
+    model="gpt-4o",
+    messages=[...],
+    temperature=0.7,
+    max_output_tokens=1000,
+    timeout_ms=30000,
+    tags=["production"],
+    user_id="user_123",
+    session_id="session_456",
+    send_trace=True,  # Set to False to disable tracing
+)
+```
+
+## Learn More
+
+- Website: [tracia.io](https://tracia.io)
+- Documentation: [docs.tracia.io](https://docs.tracia.io)
+- GitHub: [github.com/tracia](https://github.com/tracia)
+
+## License
+
+MIT