X-Ray

Deterministic. Lexical. Bounded.

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

It analyzes execution traces to determine:

• whether a run forms a valid evolving execution trajectory
• where structural contribution peaks
• where execution transitions from structural contribution into repetition or redundancy

X-Ray analyzes execution structure, not semantic correctness.

Status: Beta (v0.1.0)

Core execution analysis behavior and fail-safe boundaries are stable. Interpretation and visualization layers may evolve across minor versions.

Why Execution Analysis Exists

Multi-step AI systems often continue executing after structural contribution has already peaked.

Additional execution may:

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

Most systems constrain execution using:

• retry limits
• budget ceilings
• step caps
• timeout policies

But these mechanisms do not evaluate whether execution is still producing structural contribution.

X-Ray analyzes the execution trajectory itself.

---

Example Behaviors

Valid execution:

[
  {"output": "sort descending"},
  {"output": "use reverse=True"}
]

Invalid execution:

[
  {"output": "capital of france"},
  {"output": "capital of germany"}
]

The first represents operational refinement.

The second represents independent topical fragments rather than a continuous execution trajectory.

---

Example Trace

[
  {"output": "Explain transformers simply"},
  {"output": "Expand explanation"},
  {"output": "Add technical detail"},
  {"output": "Add examples"},
  {"output": "Continue expanding"}
]

Real Workflow Replay

Example replay of a real CrewAI multi-agent workflow analyzed through X-Ray.

What X-Ray Does

X-Ray provides:

• execution validity enforcement
• trajectory continuity analysis
• redundancy visibility
• execution transition detection
• deterministic execution analysis

Valid executions may produce:

• peak-step detection
• waste estimation
• execution timelines
• structural contribution analysis

Invalid executions terminate in fail-safe mode and do not expose:

• trajectory analysis
• plots
• contribution signals
• internal metrics

---

Real Workflow Examples

The repository includes deterministic replay fixtures and provider-backed workflow captures from:

• OpenAI iterative refinement workflows
• Claude refinement traces
• LangChain runnable chains
• LangChain official workflow patterns
• CrewAI multi-agent workflows

Examples are stored as replayable execution traces and analyzed locally through the packaged SDK.

See:

• LangChain official examples
• CrewAI official examples
• Claude refinement example
• Retry loop examples

Some live-provider example outputs may drift over time as upstream model behavior changes. Committed replay fixtures remain deterministic once captured.

Deterministic Replay

Committed workflow fixtures replay locally without live provider calls.

Live capture scripts are optional and provider-specific.

Once captured, traces replay deterministically through the SDK, CLI, and UI.

---

Design Principles

X-Ray is:

• deterministic
  the same input and algorithm versions produce identical output

• lexical
  continuity and redundancy are based on token-level overlap

• bounded
  invalid execution returns fail-safe instead of speculative analysis

• infrastructure-oriented
  designed for reproducible execution analysis and integration

X-Ray is not:

• a semantic reasoning system
• an embeddings-based analyzer
• an LLM evaluator
• a correctness scoring system
• an agent framework
• a workflow orchestrator

---

Install

pip install veloryn-xray

Editable local install:

pip install -e xray

SDK

from veloryn.xray import analyze_structured, analyze_raw

The SDK surface is intentionally minimal and deterministic.

---

Quick Start

from veloryn.xray import analyze_structured

data = {
    "steps": [
        {"output": "sort descending"},
        {"output": "use reverse=True"},
    ]
}

result = analyze_structured(data)

if result.is_valid:
    print(result.verdict.peak_step)
    print(result.verdict.waste_percentage)
    print(result.summary.reason)
else:
    print(result.verdict.message)

---

3-Minute Replay

Capture a workflow trace through a LangChain callback:

from veloryn.xray.langchain import XRayCallbackHandler

handler = XRayCallbackHandler()

chain.invoke(
    {"topic": "Queue-based retry handling for flaky infrastructure APIs"},
    config={"callbacks": [handler]},
)

handler.save_trace("callback_trace.json")

Install the optional LangChain dependencies for local repository development:

pip install -e ".[langchain]"

The LangChain optional extra will be included in a future PyPI release.

Replay the captured trace through X-Ray:

python -m cli.main callback_trace.json

Example replay output:

[VERDICT]
Execution should have stopped at Step 1.

[WASTE]
85% of execution happened after that.

[WHY]
Later steps mostly repeated earlier output.

[TIMELINE]
Step 1 → Peak
Step 2 → Repeating
Step 3 → Repeating
Step 4 → Repeating
Step 5 → Repeating

Replay remains deterministic for the same trace and algorithm version.

See also:

• examples/langchain_callback/
• examples/crewai_callback/

Local UI

Run the local replay inspection UI:

npm install
npm run dev

Open:

http://localhost:5173

Load a replay trace such as:

• examples/langchain_callback/callback_trace.json
• examples/crewai_callback/callback_trace.json

The UI visualizes:

• contribution progression
• redundancy growth
• execution timeline
• peak contribution step

---

Why Lexical Instead of Semantic

X-Ray intentionally avoids embeddings, semantic similarity, and LLM-based interpretation.

This preserves:

• determinism
• reproducibility
• stable SDK contracts
• explainable execution boundaries

---

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.

See docs/determinism.md.

Documentation

• Architecture
• Engine Flow
• Execution Validity
• Fail-Safe Contract
• SDK Contract
• Determinism
• Invariants
• Versioning
• Testing
• Limitations
• Philosophy

---

License

Copyright (c) 2026 Veloryn Intelligence

Licensed under the Apache License, Version 2.0.