Metadata-Version: 2.4
Name: sigrank-standard
Version: 0.1.5
Summary: TTEOP (Token Telemetry Evaluation Operator Protocol) v0.1-draft — canonical portable five-metric core for AI operator token-processing efficiency. No dependencies.
Author: SunrisesIllNeverSee
License: Apache-2.0
Project-URL: Homepage, https://signalaf.com/standard
Project-URL: Repository, https://github.com/SunrisesIllNeverSee/otep-spec
Project-URL: Documentation, https://github.com/SunrisesIllNeverSee/otep-spec#readme
Project-URL: Bug Tracker, https://github.com/SunrisesIllNeverSee/otep-spec/issues
Keywords: sigrank,signalaf,ai-operators,token-efficiency,yield-cascade,telemetry,benchmark,standard,mcp
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# sigrank-standard (Python)

Portable five-metric core for AI operator token-processing efficiency.
Conforms to the TTEOP v0.1-draft specification.

> **Note:** The PyPI distribution name remains `sigrank-standard` for backward
> compatibility with existing installs. The canonical protocol name is TTEOP
> (Token Telemetry Evaluation Operator Protocol). See `teps/TEP-0001.md`.

## Install

```bash
pip install sigrank-standard
```

## Usage

### Compute metrics

```python
from sigrank_standard import compute_metrics, build_record

# Four token pillars: input, output, cache_write, cache_read
result = compute_metrics(
    input_tokens=1_251_211,
    output_tokens=11_296_121,
    cache_write=128_196_310,
    cache_read=2_555_179_769,
)
print(result["metrics"])
# {'yield': 18436.98, 'leverage': 2042.2, 'velocity': 9.028, 'output_fraction': 0.9003, 'log_leverage': 3.31}
```

### Build a full record

```python
from sigrank_standard import build_record
import json

record = build_record(
    input_tokens=1_251_211,
    output_tokens=11_296_121,
    cache_write=128_196_310,
    cache_read=2_555_179_769,
    provider="anthropic",
    model="claude-sonnet-4",
    tool="claude-code",
)
print(json.dumps(record, indent=2))
```

### Run conformance suite

```bash
sigrank-conformance
# or
python -m sigrank_standard
```

## Metrics

| Metric | Formula | Description |
|--------|---------|-------------|
| Yield (Υ) | `(cache_read * output) / input^2` | Token cascade efficiency |
| Leverage | `cache_read / input` | Context reuse |
| Velocity | `output / input` | Output amplification |
| output_fraction | `output / (input + output)` | Output share of total tokens |
| log_leverage | `log10(cache_read / input)` | Log-scaled context reuse |

Legacy aliases (deprecated): SNR → output_fraction, 10xDEV → log_leverage.

## Null semantics

- When a denominator is zero, the metric is `None` (not 0 or Infinity)
- When `cache_read` is `None`, Yield, Leverage, and log_leverage are `None`
- When `cache_write` is `None`, log_leverage is `None`

## Spec

TTEOP v0.1-draft (Token Telemetry Evaluation Operator Protocol). See [signalaf.com/standard](https://signalaf.com/standard).

## License

Apache-2.0
