Metadata-Version: 2.5
Name: anysql-sdk
Version: 0.3.0
Summary: SQL analytics for AI systems — query LLM responses, agent traces, and RAG pipelines like a database
Project-URL: Homepage, https://anysql.org
Project-URL: Repository, https://github.com/sadayamuthu/anySQL
Project-URL: Documentation, https://docs.anysql.org
Project-URL: Issues, https://github.com/sadayamuthu/anySQL/issues
Author: Karthikeyan Sadayamuthu
License: Apache-2.0
License-File: LICENSE
Keywords: agents,ai,anthropic,duckdb,eval,llm,observability,openai,rag,sql
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: duckdb>=0.10.0
Requires-Dist: pandas>=2.0.0
Requires-Dist: pyarrow>=14.0.0
Provides-Extra: all
Requires-Dist: anthropic>=0.25.0; extra == 'all'
Requires-Dist: langchain>=0.2.0; extra == 'all'
Requires-Dist: openai>=1.0.0; extra == 'all'
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.25.0; extra == 'anthropic'
Provides-Extra: dev
Requires-Dist: black; extra == 'dev'
Requires-Dist: pytest-asyncio; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff==0.17.3; extra == 'dev'
Provides-Extra: langchain
Requires-Dist: langchain>=0.2.0; extra == 'langchain'
Provides-Extra: openai
Requires-Dist: openai>=1.0.0; extra == 'openai'
Description-Content-Type: text/markdown

<div align="center">

# anySQL

<h3>SQL Analytics for AI Systems</h3>

<p>From vibes to queries.</p>

[![CI](https://img.shields.io/github/actions/workflow/status/sadayamuthu/anySQL/pr-check.yml?event=pull_request&label=CI&style=flat-square)](https://github.com/sadayamuthu/anySQL/actions/workflows/pr-check.yml)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue?style=flat-square)](https://www.python.org/downloads/)
[![License](https://img.shields.io/github/license/sadayamuthu/anySQL?style=flat-square)](LICENSE)
[![PyPI](https://img.shields.io/pypi/v/anysql-sdk?style=flat-square)](https://pypi.org/project/anysql-sdk/)

---

[Quick Start](#quick-start) · [How It Works](#how-it-works) · [5 Use Cases](#the-5-use-cases) · [Installation](#installation) · [CLI Usage](#cli-usage) · [Examples](#examples)

</div>

---

## What is anySQL?

anySQL is an open-source SQL analytics engine for AI systems. It lets engineers query LLM responses, agent traces, and RAG pipelines with standard SQL — powered by DuckDB in-memory, persisted to SQLite, with zero configuration.

AI engineers debug with `print()` statements, JSON log files, and pre-built dashboards that show what the tool designer thought you'd want to see. What's missing is raw SQL over normalized AI telemetry data — specifically the cross-layer JOIN that lets you ask whether your RAG pipeline is failing at retrieval or generation.

---

## Quick Start

```bash
# Install
pip install anysql-sdk

# Install with provider support
pip install "anysql-sdk[openai]"
pip install "anysql-sdk[anthropic]"
pip install "anysql-sdk[all]"        # OpenAI + Anthropic + LangChain
```

```python
import anysql

# Initialize (in-memory by default, or pass a file path for persistence)
db = anysql.init()

# Wrap your OpenAI client — chat.completions.create calls are auto-logged
client = anysql.openai(db).wrap(openai_client)

# Wrap your Anthropic client — messages.create calls are auto-logged
client = anysql.claude(db).wrap(anthropic_client)

# Tag pipeline runs for cost attribution
@anysql.context(feature="search", tags={"version": "v2"})
def run_search(query):
    ...

# Query anything with standard SQL
df = db.query("SELECT model, AVG(cost_usd) FROM llm_responses GROUP BY model")

# Or use built-in analytics methods
df = db.model_comparison()       # UC1: multi-model comparison
df = db.prompt_regressions()     # UC2: regression detection
df = db.cost_by_feature()        # UC3: cost attribution
df = db.tool_failure_rates()     # UC4: agent debugging
df = db.rag_failure_modes()      # UC5: RAG forensics
```

---

## How It Works

```
User Code
    │
    ├── @anysql.context(feature="x")     ← Python contextvars, sync+async safe
    ├── OpenAI/Claude wrapped client      ← transparent proxy, one-line swap
    ├── AgentTracer                       ← manual tool-call and step tracing
    └── RAGTracer.after_retrieval()       ← auto-detects LangChain/LlamaIndex/dict
              │
              ▼ insert()
    AnySQL engine
    ├── in-memory buffer (dict lists per table)
    ├── SQLite persistence (JSON blobs, cross-session)
    └── DuckDB (Arrow views, SQL at query time)
              │
              ▼ query()
    6 PyArrow tables as DuckDB views:
    llm_responses, eval_results, pipeline_runs,
    agent_tool_calls, agent_trace, rag_chunks
```

**Key design decisions:**
- Schema enforcement at Arrow layer — SQLite stores raw JSON, validation happens at query time
- Dot-namespace tables (`llm.responses`) map to flat SQL view names (`llm_responses`)
- Contextvars for async-safe tagging — no manual pass-through required within a task (new threads start with an empty context unless you copy it with `contextvars.copy_context()`)

---

## The 6 Canonical Tables

| Table | Use Cases | Join Keys |
|-------|-----------|-----------|
| `llm_responses` | UC1, UC2 | `response_id` |
| `eval_results` | UC1, UC2, UC5 | `response_id`, `run_id`, `query_id` |
| `pipeline_runs` | UC3 | `run_id`, `session_id` |
| `agent_tool_calls` | UC4 | `session_id` |
| `agent_trace` | UC4 | `session_id` |
| `rag_chunks` | UC5 | `query_id` ← cross-layer join key |

---

## The 5 Use Cases

| UC | Name | Key Methods | What It Answers |
|----|------|-------------|-----------------|
| UC1 | Multi-Model Comparison | `model_comparison()`, `model_by_task()` | Which model performs best on my task? |
| UC2 | Prompt Regression Detection | `prompt_regressions()`, `eval_debt()`, `silent_degradation()` | Did my last prompt change break something? |
| UC3 | Cost Attribution | `cost_by_feature()`, `cost_anomalies()` | Which feature is burning my LLM budget? |
| UC4 | Agent Debugging | `tool_failure_rates()`, `loop_detector()`, `session_diff()`, `human_intervention_points()` | Where is my agent getting stuck? |
| UC5 | RAG Forensics | `rag_failure_modes()`, `chunk_quality_ranking()`, `similarity_calibration()` | Is my RAG failing at retrieval or generation? |

The cross-layer join (UC5) is the killer feature — `query_id` threads RAG retrieval to eval results, enabling retrieval vs. generation failure classification.

---

## Installation

### From PyPI

```bash
pip install anysql-sdk
```

### Provider extras

```bash
pip install "anysql-sdk[openai]"      # + openai>=1.0.0
pip install "anysql-sdk[anthropic]"   # + anthropic>=0.25.0
pip install "anysql-sdk[langchain]"   # + langchain>=0.2.0
pip install "anysql-sdk[all]"         # everything
```

---

## CLI Usage

```bash
# Run a SQL query against a persisted database (default: ./anysql.db)
anysql query "SELECT model, COUNT(*) FROM llm_responses GROUP BY model"

# Show row counts for all tables
anysql stats

# Query a specific database file
anysql query "SELECT * FROM eval_results LIMIT 10" --db ./myproject.db
```

---

## Examples

Three runnable demos are included in `examples/`. All auto-detect missing API keys and fall back to mock mode. The articles are short samples embedded in each script, written in the style of each dataset's topics — no downloads required.

| Demo | Embedded sample articles | Models |
|------|---------|--------|
| `realtime_openai_demo.py` | 12, BBC News-style topics | `gpt-4o`, `gpt-4o-mini` |
| `realtime_claude_demo.py` | 15, AG News-style topics | `claude-sonnet-4-6`, `claude-haiku-4-5` |
| `realtime_combined_demo.py` | 20, Reuters R8-style topics | All 4 models head-to-head |

```bash
# Run combined demo (works without API keys)
python examples/realtime_combined_demo.py
```

---

## Adapter Usage

### OpenAI

```python
import openai
import anysql

db = anysql.init()
client = anysql.openai(db).wrap(openai.OpenAI())

# chat.completions.create calls are now logged automatically
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Summarize this article..."}]
)
```

### Anthropic

```python
import anthropic
import anysql

db = anysql.init()
client = anysql.claude(db).wrap(anthropic.Anthropic())

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Classify this text..."}]
)
```

### Agent Tracing

```python
tracer = anysql.agent_tracer(db, session_id="sess-001")

# Manual tracing
tracer.trace_tool_call(
    "web_search",
    input={"query": "latest news"},
    output={"results": [...]},
    status="success",
    latency_ms=320,
)
tracer.trace_step("llm_call", description="Summarize results")
```

`AgentTracer` also has `on_tool_start`, `on_tool_end`, `on_tool_error`, `on_agent_action` and `on_agent_finish` methods named after LangChain's callback hooks, which you can call from your own framework code. It does not subclass LangChain's `BaseCallbackHandler`, so passing it in `callbacks=[...]` to LangChain does not work in this release.

### RAG Tracing

```python
rag = anysql.rag_tracer(db)

query = "What is anySQL?"
query_id = rag.before_retrieval(query)
chunks = vectorstore.similarity_search_with_score(query)  # (doc, score) tuples
rag.after_retrieval(query_id=query_id, chunks=chunks)

# Record eval result with cross-layer join key (passed = score >= 0.7)
rag.record_eval(
    query_id=query_id,
    score=0.92,
    actual=answer,
    factuality=0.95,
)
```

---

## IDE Proxy (anysql-proxy)

[`proxy/`](proxy/) holds **anysql-proxy**, a local HTTP proxy that sits between an AI coding
assistant (Cursor, Claude Code, Windsurf, VS Code with Continue, Zed) and the OpenAI or
Anthropic API. It forwards each request unchanged, streams the response back, and logs
tokens, cost, latency, IDE and file context to a local DuckDB file, with Parquet snapshots
for other tools. API keys are stored encrypted. It is a separate package with its own
dependencies; see [proxy/README.md](proxy/README.md).

```bash
pip install "anysql-proxy @ git+https://github.com/sadayamuthu/anySQL#subdirectory=proxy"
anysql-proxy keys set anthropic sk-ant-...
anysql-proxy start
anysql-proxy setup claude-code
```

---

## Development

```bash
pip install -e ".[dev]"

pytest tests/ -v --tb=short   # Run tests
ruff check anysql/            # Lint
ruff format --check anysql/   # Check formatting (ruff format anysql/ to fix)

# Proxy
pip install -e "proxy[dev]"
(cd proxy && pytest tests/ -v --tb=short)
ruff check proxy/ && ruff format --check proxy/
```

---

## Repository Structure

```
anySQL/
├── anysql/
│   ├── __init__.py        # Public API surface
│   ├── engine.py          # DuckDB engine + UC analytics methods
│   ├── schema.py          # 6 PyArrow schemas
│   ├── storage.py         # SQLite persistence
│   ├── context.py         # @context decorator + context_scope()
│   ├── cli.py             # CLI entry point
│   ├── adapters/
│   │   ├── openai.py      # OpenAI transparent proxy
│   │   ├── claude.py      # Anthropic transparent proxy
│   │   └── generic.py     # Generic JSON/dict adapter
│   └── tracers/
│       ├── agent.py       # AgentTracer (manual tracing + LangChain-style hooks)
│       └── rag.py         # RAGTracer (LangChain/LlamaIndex/dict)
├── tests/                 # SDK tests (pytest)
├── proxy/                 # anysql-proxy: local IDE LLM proxy (separate package)
├── examples/              # 3 runnable demos
└── docs/
    └── QUERIES.md         # Canonical SQL query library
```

---

## Contributing

Bug reports, adapters and fixes are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for the development setup, the checks CI runs, and how to add an adapter.

---

## Security

Please report vulnerabilities privately through [GitHub security advisories](https://github.com/sadayamuthu/anySQL/security/advisories/new), not in a public issue. See [SECURITY.md](SECURITY.md) for what to include and what's in scope.

---

## License

[Apache License 2.0](LICENSE)

---

<div align="center">

**anySQL is an open-source SQL analytics engine for AI systems**

anySQL is managed by [OpenAstra](https://openastra.org) · [anysql.org](https://anysql.org)

[PyPI](https://pypi.org/project/anysql-sdk/) · [GitHub](https://github.com/sadayamuthu/anySQL) · [Docs](https://docs.anysql.org)

</div>

---
