Metadata-Version: 2.4
Name: oddrun
Version: 0.1.0
Summary: Investigates why the same Python program behaves differently across environments.
Author: OddRun Contributors
License-Expression: MIT
Project-URL: Homepage, https://github.com/oddrun/oddrun
Project-URL: Documentation, https://github.com/oddrun/oddrun#readme
Project-URL: Repository, https://github.com/oddrun/oddrun
Project-URL: Issues, https://github.com/oddrun/oddrun/issues
Keywords: debugging,environment,reproducibility,diff,snapshot,developer-tools
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
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: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Debuggers
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: build>=1.0.0; extra == "dev"
Dynamic: license-file

# OddRun

> When the same code doesn't behave the same.

OddRun is a Python developer tool that investigates why the same program behaves differently across environments.

Traditional environment tools answer:
> *"What is different between these environments?"*

OddRun answers:
> *"Which difference experimentally explains the observed failure?"*

---

## Core Product Model

| Subcommand | Question | Input Artifact |
| :--- | :--- | :--- |
| `oddrun capture` | **What's different?** Captures environment state | `EnvironmentSnapshot` JSON |
| `oddrun compare` | **What changed?** Compares two environment snapshots | Two `EnvironmentSnapshot` JSONs |
| `oddrun record` | **What actually happened here?** Executes command 1x on target | `ExecutionRecord` JSON |
| `oddrun why` | **Which difference explains the target behavior?** | `ExecutionRecord` JSON + `<command>` |

---

## Quickstart

### Installation

```bash
pip install oddrun
```

### The Distributed Workflow (`record` → `why`)

#### 1. On Target Environment (e.g. CI / Remote Server where code fails)
Execute the failing command once to record the environment state and observed failure signature:

```bash
oddrun record -o target-run.json -- pytest tests/test_date.py
```
*(Generates `target-run.json` containing safe environment metadata and the observed failure `BehaviorSignature`)*

#### 2. On Developer Machine (Baseline environment where code passes)
Diagnose which environmental difference reproduces the target failure:

```bash
oddrun why target-run.json -- pytest tests/test_date.py
```

OddRun will:
1. Verify baseline stability (3/3 identical passing runs in current environment).
2. Rank environmental differences by safety tier (`TZ`, `LANG`, `LC_*`, application variables).
3. Execute controlled perturbations (1x exploratory + 2x confirmation).
4. Match structural behavior signatures (`exit_code`, `exception_type`, normalized diagnostic output).
5. Report **Experimentally Supported Causal Factors** with remediation recommendations.

---

## Direct Environment Comparison (`capture` → `compare`)

```bash
# Capture local environment snapshot
oddrun capture -o local.json

# Compare local environment against target snapshot
oddrun compare local.json target-run.json
```

---

## Python API Usage

```python
from oddrun import (
    capture_environment,
    compare_snapshots,
    record_execution,
    diagnose_behavior,
    load_record,
)

# 1. Record execution
record = record_execution(["pytest", "tests/test_date.py"])
print(f"Recorded outcome: {record.execution_result.behavior_signature.is_success}")

# 2. Diagnose behavior against target record
report = diagnose_behavior("target-run.json", ["pytest", "tests/test_date.py"])
for factor in report.causal_factors:
    print(f"Causal Factor: {factor.candidate.key} ({factor.evidence_level.value})")
```

---

## Security & Privacy

OddRun is strictly **local-first**:
- Zero telemetry or analytics.
- Zero network calls or cloud dependencies; operates 100% offline.
- **Automatic Secret Redaction**: Sensitive environment keys (`API_KEY`, `SECRET`, `PASSWORD`, `TOKEN`, `CREDENTIAL`, `AUTH`, etc.) are automatically replaced with `"<present>"` before saving snapshots or execution records to disk.

---

## License

[MIT License](LICENSE)
