Skip to main content

anySQL

SQL Analytics for AI Systems

From vibes to queries.

CI Python 3.10+ License PyPI


Quick Start · How It Works · 5 Use Cases · Installation · CLI Usage · Examples


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

# 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
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

pip install anysql-sdk

Provider extras

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

# 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
# Run combined demo (works without API keys)
python examples/realtime_combined_demo.py

Adapter Usage

OpenAI

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

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

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

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/ 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.

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

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 for the development setup, the checks CI runs, and how to add an adapter.


Security

Please report vulnerabilities privately through GitHub security advisories, not in a public issue. See SECURITY.md for what to include and what's in scope.


License

Apache License 2.0


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

anySQL is managed by OpenAstra · anysql.org

PyPI · GitHub · Docs


Metadata

Release files for anysql-sdk 0.3.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for anysql-sdk 0.3.1
File Size Uploaded Provenance Actions
anysql_sdk-0.3.1.tar.gz 46.6 kB With provenance Details for anysql_sdk-0.3.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for anysql-sdk 0.3.1
File Interpreter ABI Platform Actions
anysql_sdk-0.3.1-py3-none-any.whl Python 3 none any Details for anysql_sdk-0.3.1-py3-none-any.whl

Total release size: 75.4 kB

Release files / anysql_sdk-0.3.1.tar.gz

Download URL anysql_sdk-0.3.1.tar.gz
Size 46.6 kB
Tags Source
SHA-256 checksum
How to use checksums
635971dbed7981ba92f6374e7793208657c32b42e9924edcea0cb6decf56cbf1
BLAKE2b-256 checksum
How to use checksums
c4da87a4b246b57447610187b1c5e372e2648de9e9611ea19b0e9e4eb35f2c0a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

Release files / anysql_sdk-0.3.1-py3-none-any.whl

Download URL anysql_sdk-0.3.1-py3-none-any.whl
Size 28.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
6cca0aee289859a75da391996e0a20052c7b177f355da74d4f2013f9374271dd
BLAKE2b-256 checksum
How to use checksums
f4529115b3fa835a9166d6f663500a90e1bf7c983453283bdf236cefbfebdf76
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

Security for anysql-sdk 0.3.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for anysql_sdk-0.3.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page