Metadata-Version: 2.4
Name: onetrace-explain
Version: 0.1.0
Summary: A suggested explanation of a onetrace comparison: AI-generated, checked against the record, never a verdict
Author-email: Shamik Saha <shamik.saha.rcciit@gmail.com>
License-Expression: Apache-2.0
Project-URL: Issues, https://github.com/shamiksaharcciit-oss/onetrace-issues
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: onetrace<0.5,>=0.4

# onetrace-explain

A suggested explanation of a onetrace comparison: **AI-generated, may be wrong**, and checked
against the record before anyone reads it. Never a verdict: onetrace's verdicts and exit codes are
what they are without it, and its exit codes say nothing about the runs. Don't use it as a CI gate.

```
onetrace localize runs/a runs/b --for answer --out report
onetrace-explain report --dry-run          # the packet exactly as it would be sent; nothing sent
onetrace-explain report --model anthropic:<model name>
```

- **What is sent:** a packet built from the report and the two runs' receipts: verdicts, stage
  names and edges, outcome classes, digests and sizes, instrument names and versions, and the
  constants that differ with both values (`--redact NAME` sends a name and digest only). Kept text
  only with `--include-text`. A constant's value goes as the run recorded it, a path or a token
  included; `--redact NAME` keeps it out. Never this machine's own paths, an environment variable,
  the model key, a signing key or an anchor's proof. The first send of a kind of item to an endpoint asks first (`--yes` for scripts).
- **The model:** yours, named in `~/.config/onetrace/explain.toml`:

  ```toml
  [model]
  provider = "anthropic"          # or "openai" (any OpenAI-compatible endpoint, local ones too)
  name = "<model name>"
  key_env = "ANTHROPIC_API_KEY"   # the variable holding the key; the key is never written anywhere
  # base_url = "http://localhost:8000/v1"   # for an openai-compatible server
  ```
- **The post-check,** with no model: a claim is dropped when it cites nothing, cites what the packet
  doesn't hold, quotes a value its cites don't hold, or says what caused a difference. What's shown
  says how many were dropped, and why.
- **Checks, not conclusions:** each suggestion comes with onetrace commands to run. A lead is
  confirmed or ruled out only by what those report.
- **Recorded:** every explanation is a onetrace run of its own, under `<out>/explain/<run id>/`,
  which `onetrace-verify` checks like any run.
