Metadata-Version: 2.4
Name: logicgaze
Version: 1.5.0
Summary: LogicGaze SDK — AI-native observability for tracing, evaluating, and monitoring production LLM applications. Instrument OpenAI, Anthropic, and any LLM with one line of code.
Project-URL: Homepage, https://github.com/VikneeshVG/logicgaze
Project-URL: Repository, https://github.com/VikneeshVG/logicgaze
Project-URL: Issues, https://github.com/VikneeshVG/logicgaze/issues
Author-email: Vikneesh VG <vikneeshwaran.k@ventragate.com>
License: MIT
License-File: LICENSE
Keywords: ai,anthropic,cohere,evaluation,google,langchain,litellm,llm,logicgaze,observability,openai,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.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 :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Requires-Dist: httpx>=0.26.0
Provides-Extra: all
Requires-Dist: click>=8.0.0; extra == 'all'
Requires-Dist: cohere>=5.0.0; extra == 'all'
Requires-Dist: docker>=6.0.0; extra == 'all'
Requires-Dist: google-genai>=1.0.0; extra == 'all'
Requires-Dist: groq>=0.9.0; extra == 'all'
Requires-Dist: langchain-core>=0.1.0; extra == 'all'
Requires-Dist: langchain>=0.1.0; extra == 'all'
Requires-Dist: litellm>=1.0.0; extra == 'all'
Requires-Dist: mistralai>=1.0.0; extra == 'all'
Requires-Dist: psutil>=5.9.0; extra == 'all'
Requires-Dist: pyyaml>=6.0; extra == 'all'
Requires-Dist: schedule>=1.2.0; extra == 'all'
Requires-Dist: tomli>=2.0.0; extra == 'all'
Provides-Extra: cohere
Requires-Dist: cohere>=5.0.0; extra == 'cohere'
Provides-Extra: dev
Requires-Dist: build>=1.0.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: respx>=0.20.0; extra == 'dev'
Requires-Dist: twine>=4.0.0; extra == 'dev'
Provides-Extra: google
Requires-Dist: google-genai>=1.0.0; extra == 'google'
Provides-Extra: groq
Requires-Dist: groq>=0.9.0; extra == 'groq'
Provides-Extra: langchain
Requires-Dist: langchain-core>=0.1.0; extra == 'langchain'
Requires-Dist: langchain>=0.1.0; extra == 'langchain'
Provides-Extra: litellm
Requires-Dist: litellm>=1.0.0; extra == 'litellm'
Provides-Extra: mistral
Requires-Dist: mistralai>=1.0.0; extra == 'mistral'
Provides-Extra: security
Requires-Dist: click>=8.0.0; extra == 'security'
Requires-Dist: psutil>=5.9.0; extra == 'security'
Requires-Dist: pyyaml>=6.0; extra == 'security'
Requires-Dist: schedule>=1.2.0; extra == 'security'
Requires-Dist: tomli>=2.0.0; extra == 'security'
Provides-Extra: security-containers
Requires-Dist: click>=8.0.0; extra == 'security-containers'
Requires-Dist: docker>=6.0.0; extra == 'security-containers'
Requires-Dist: psutil>=5.9.0; extra == 'security-containers'
Requires-Dist: pyyaml>=6.0; extra == 'security-containers'
Requires-Dist: schedule>=1.2.0; extra == 'security-containers'
Requires-Dist: tomli>=2.0.0; extra == 'security-containers'
Description-Content-Type: text/markdown

# logicgaze

[![PyPI version](https://img.shields.io/pypi/v/logicgaze.svg)](https://pypi.org/project/logicgaze/)
[![Python 3.9+](https://img.shields.io/pypi/pyversions/logicgaze.svg)](https://pypi.org/project/logicgaze/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**LogicGaze SDK** — AI-native observability for production LLM applications.

Instrument OpenAI, Anthropic, and any LLM with one line of code. Every call is automatically traced, cost-attributed, and visible in the [LogicGaze](https://logicgaze.com) dashboard.

## Features

- **Zero-config tracing** — wrap your existing client, get full observability instantly
- **Cost tracking** — token-level cost attribution per model, provider, and session
- **Distributed traces** — full span trees across LLM calls, tool calls, agents, and retrievals
- **Guardrails** — PII detection, prompt injection detection, harmful content filtering
- **LLM-as-Judge** — async evaluation scoring (faithfulness, relevance, coherence, hallucination)
- **OpenTelemetry** — ingest traces from any OTel-compatible SDK via OTLP HTTP

## Installation

```bash
pip install logicgaze
```

## Quick Start

### 1. Initialize once at startup

```python
import logicgaze

logicgaze.init(
    api_key="lgz_...",               # LogicGaze API key
    base_url="https://your-logicgaze-backend.com",
)
```

Set `LOGICGAZE_API_KEY` in your environment to avoid passing `api_key` explicitly.

### 2. Wrap your AI client

**OpenAI**
```python
from openai import OpenAI
import logicgaze

logicgaze.init(api_key="lgz_...")
client = logicgaze.wrap_openai(OpenAI())

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello!"}],
)
print(response.choices[0].message.content)
```

**Anthropic**
```python
from anthropic import Anthropic
import logicgaze

logicgaze.init(api_key="lgz_...")
client = logicgaze.wrap_anthropic(Anthropic())

response = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello!"}],
)
print(response.content[0].text)
```

### 3. Group calls with `TraceContext`

```python
from logicgaze import TraceContext, wrap_openai
from openai import OpenAI

client = wrap_openai(OpenAI())

with TraceContext(session_id="sess-abc", user_id="user-42", service_name="chat-api"):
    # All calls inside share the same trace in the dashboard
    client.chat.completions.create(model="gpt-4o", messages=[...])
    client.chat.completions.create(model="gpt-4o", messages=[...])
```

### 4. Use `@traceable` on functions

```python
from logicgaze import traceable, wrap_openai
from openai import OpenAI

client = wrap_openai(OpenAI())

@traceable(session_id="sess-1", service_name="recommendation-engine")
def recommend(user_query: str):
    return client.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": user_query}],
    )

# Async functions are fully supported
@traceable(service_name="summarizer")
async def summarize(text: str):
    return await client.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": f"Summarize: {text}"}],
    )
```

### 5. Query traces programmatically

```python
from logicgaze import get_client

lg = get_client()

# List recent traces
traces = lg.list_traces(service_name="chat-api", page_size=20)

# Get a specific trace with all spans
trace = lg.get_trace("trace-uuid-here", include_spans=True)

# Dashboard overview (last 24 h)
overview = lg.get_dashboard(window_hours=24)
print(overview["total_requests"], overview["total_cost_usd"])

# Estimate cost before a call
estimate = lg.estimate_cost("openai", "gpt-4o", prompt_tokens=500, completion_tokens=200)
```

## Configuration

| Parameter | Environment variable | Default |
|-----------|---------------------|---------|
| `api_key` | `LOGICGAZE_API_KEY` | — |
| `base_url` | `LOGICGAZE_BASE_URL` | `http://localhost:8000` |
| `timeout` | — | `30.0` s |

## API Reference

### `logicgaze.init(api_key, base_url, timeout)`
Initialize the global client. Call once at application startup.

### `wrap_openai(client, *, service_name=None)`
Patches `client.chat.completions.create` (sync & async). Returns the same client object.

### `wrap_anthropic(client, *, service_name=None)`
Patches `client.messages.create` (sync & async). Returns the same client object.

### `TraceContext(*, project, trace_id, session_id, user_id, service_name, tags)`
Context manager (sync & async). Injects trace metadata into every gateway call made within the block.

### `@traceable(*, name, project, session_id, user_id, service_name, tags, run_type)`
Decorator that wraps the function body in a `TraceContext`. Works with sync and async functions.

### `LogicGazeClient` methods

| Method | Description |
|--------|-------------|
| `chat_completion(provider, model, messages, **kwargs)` | Proxied LLM call via gateway |
| `achat_completion(...)` | Async version |
| `list_traces(**filters)` | List traces with optional filters |
| `get_trace(trace_id, include_spans)` | Fetch a trace and its spans |
| `get_spans(trace_id)` | Fetch all spans for a trace |
| `get_agent_graph(trace_id)` | Fetch the visual agent execution graph |
| `get_dashboard(window_hours)` | Aggregated dashboard metrics |
| `get_model_distribution(window_hours)` | Token & cost breakdown by model |
| `get_provider_breakdown(window_hours)` | Breakdown by AI provider |
| `estimate_cost(provider, model, prompt_tokens, completion_tokens)` | Pre-call cost estimate |
| `list_model_costs(provider)` | Pricing table for a provider |
| `get_guardrails_summary(window_hours)` | Guardrail event summary |

## Requirements

- Python 3.9+
- `httpx >= 0.26.0`

## Links

- **Dashboard**: [logicgaze.com](https://logicgaze.com)
- **Documentation**: [docs.logicgaze.com](https://docs.logicgaze.com)
- **GitHub**: [github.com/VikneeshVG/logicgaze](https://github.com/VikneeshVG/logicgaze)
- **PyPI**: [pypi.org/project/logicgaze](https://pypi.org/project/logicgaze/)

## License

MIT
