veloryn-xray 0.1.0

Deterministic lexical execution analysis for multi-step LLM workflows.

X-Ray

X-Ray is a deterministic execution-analysis engine for multi-step LLM workflows.

X-Ray analyzes ordered output traces to decide whether a run forms one evolving execution trajectory, where structural contribution peaks, and how much token volume appears after that peak.

X-Ray is infrastructure, not an LLM judge.

Status: Beta (v0.1.0)

Why X-Ray Exists

Multi-step LLM systems often continue executing after meaningful contribution has already peaked.

Additional execution may:

• repeat earlier work
• increase token cost without adding signal
• drift across tasks
• create apparent progress without meaningful structural change

X-Ray analyzes the execution trajectory itself.

Install

Package install command:

pip install veloryn-xray

Editable local install:

pip install -e .

SDK

from veloryn.xray import analyze_structured, analyze_raw

Structured SDK Example

from veloryn.xray import analyze_structured

result = analyze_structured(
    {
        "steps": [
            {"output": "sort descending"},
            {"output": "use reverse=True"},
        ]
    }
)

print(result.to_dict())

Current runtime shape:

{
    "is_valid": True,
    "verdict": {
        "peak_step": 2,
        "should_stop_at": 2,
        "waste_percentage": 0,
    },
    "summary": {"reason": "Most value was captured early."},
    "meta": {"version": "0.1.0"},
    "timeline": [
        {"step": 1, "label": "improving"},
        {"step": 2, "label": "peak"},
    ],
    "analysis": {
        "signals": {
            "redundancy_trend": "stable",
            "contribution_trend": "stable",
        }
    }
}

X-Ray is:

• deterministic
• lexical
• bounded
• typed at the SDK boundary

X-Ray is not:

• a semantic understanding system
• an embeddings-based analyzer
• a correctness evaluator
• a workflow control system

Raw SDK Example

from veloryn.xray import analyze_raw

result = analyze_raw("sort descending\nuse reverse=True")
print(result.to_dict())

Raw mode parses newline-separated steps or JSON payloads and returns the same typed SDK result shape.

Fail-Safe SDK Example

from veloryn.xray import analyze_structured

result = analyze_structured(
    {
        "steps": [
            {"output": "capital of france"},
            {"output": "capital of germany"},
        ]
    }
)

print(result.to_dict())

Canonical fail-safe SDK output:

{
    "is_valid": False,
    "verdict": {"message": "No clear execution pattern detected."},
    "summary": {"reason": "This does not appear to be a single evolving task."},
    "meta": {"version": "0.1.0"},
}

Fail-safe omits:

• timeline
• analysis
• internal signals

CLI

xray trace.json
xray trace.json --analysis
xray trace.json --debug

## Serialization Example

```python
import json

from veloryn.xray import analyze_structured

result = analyze_structured(
    {
        "steps": [
            {"output": "a"},
            {"output": "a"},
        ]
    }
)

payload = result.to_dict()
print(json.dumps(payload))

Input Shape

Structured SDK input must be:

{
    "steps": [
        {"output": "step 1 text"},
        {"output": "step 2 text"},
    ]
}

Rules:

• top-level must be a dict
• steps must exist
• steps must be a list
• each step must contain string output

Invalid schema raises ValueError.

Execution invalidity returns fail-safe.

Determinism

X-Ray uses no randomness, no embeddings, no semantic model, and no LLM calls.

For the same input and same algorithm versions, output is stable.

Peak selection uses a stabilized selector trajectory rather than raw normalized contributions directly. CLI and UI plots are aligned to the final selected peak.

Validation

Run Python tests:

python -m unittest discover -s tests

Build UI:

npm run build