Metadata-Version: 2.4
Name: veloryn-xray
Version: 0.1.0
Summary: Deterministic lexical execution analysis for multi-step LLM workflows.
Author: Veloryn Intelligence
Project-URL: Homepage, https://github.com/veloryn-intel/veloryn-xray
Project-URL: Source, https://github.com/veloryn-intel/veloryn-xray
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: matplotlib
Requires-Dist: tiktoken
Dynamic: license-file

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

```bash
pip install veloryn-xray
```

Editable local install:

```bash
pip install -e .
```

## SDK

```python
from veloryn.xray import analyze_structured, analyze_raw
```

## Structured SDK Example

```python
from veloryn.xray import analyze_structured

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

print(result.to_dict())
```

Current runtime shape:

```python
{
    "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

```python
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

```python
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:

```python
{
    "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

```bash
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:

```python
{
    "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:

```bash
python -m unittest discover -s tests
```

Build UI:

```bash
npm run build
```
