xray-logger 0.1.0

Decision-level observability for ML/LLM pipelines

X-Ray Logger

Decision-level observability for ML/LLM pipelines.

X-Ray captures why decisions were made—candidates considered, filters applied, scores computed, and reasoning behind each step—not just what functions ran.

Quick Start

1. Start the Server

docker run -d -p 8000:8000 \
  -e XRAY_DATABASE_URL=sqlite+aiosqlite:///./xray.db \
  ghcr.io/mohit-nagaraj/xray-logger:latest

2. Install the SDK

pip install xray-logger

3. Instrument Your Code

from xray_logger import init_xray, step, attach_reasoning

client = init_xray(base_url="http://localhost:8000")

@step(step_type="filter")
def filter_items(items, threshold=0.5):
    result = [i for i in items if i["score"] >= threshold]
    attach_reasoning({"threshold": threshold, "removed": len(items) - len(result)})
    return result

with client.start_run("my-pipeline"):
    filtered = filter_items(items)

Features

• Decision Transparency - Capture candidates, scores, and reasoning at each step
• Lightweight SDK - Simple decorators, fail-open design
• FastAPI Middleware - Automatic HTTP request instrumentation
• Query API - Filter runs by pipeline, user, status

Documentation

• Quick Start Guide
• Architecture
• Examples

Step Types

Type	Use Case
filter	Removing candidates by criteria
rank	Ordering candidates by score
llm	LLM/AI model calls
retrieval	Fetching external data
transform	Data transformations

Self-Hosting with Docker Compose

git clone https://github.com/mohit-nagaraj/xray-logger.git
cd xray-logger
cp .env.example .env
docker-compose up -d

License

MIT