Metadata-Version: 2.4
Name: origami-trace
Version: 0.1.3
Summary: Trace experiment capture, hosted query, artifact download, and MCP client.
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# Origami Trace

`origami-trace` ships the public `otrace` client for recording experiment runs in a hosted Trace project and reading those hosted runs back from the command line or MCP.

Use it when a training, evaluation, or data-processing run should upload its command, setup, logs, metrics, tables, and artifacts so the results are inspectable later.

## Install

```bash
pip install origami-trace
```

## Authenticate

Create a Trace project API key in the Trace dashboard, then initialize a workspace:

```bash
export TRACE_API_KEY="trc_your_key_here"
otrace init
otrace whoami
```

## Run An Experiment

```bash
otrace run \
  --intent "Evaluate baseline on validation split" \
  --setup "Baseline config with validation data" \
  --expect-artifact outputs/metrics.json \
  --expect-log outputs/eval.log \
  -- python eval.py --config configs/baseline.yaml
```

If the project does not already write queryable outputs, create starter output files:

```bash
otrace scaffold outputs
```

## Public Commands

```text
otrace init
otrace login
otrace whoami
otrace scaffold outputs
otrace run
otrace import
otrace runs
otrace show
otrace artifacts
otrace download
otrace mcp
```

The published package is intentionally a client: it captures/uploads run evidence and queries/downloads hosted run data through the Trace API. The hosted backend and app implementation are not part of this package.

## Query Hosted Runs

```bash
otrace runs --query baseline
otrace show run_123 --json
otrace artifacts run_123
otrace download artifact_123 --output outputs/metrics.json
```

## MCP

Run the stdio MCP server:

```bash
otrace mcp
```

The public MCP tools expose hosted run listing, run detail lookup, artifact listing/download, and RunSpec validation.
