Metadata-Version: 2.5
Name: flameox
Version: 0.1.14
Summary: Runtime evidence that helps agents trace, profile, and burn down hotspots in application and native code, GPU kernels, and inference stacks.
Project-URL: Homepage, https://github.com/morluto/flameox
Project-URL: Repository, https://github.com/morluto/flameox
Project-URL: Issues, https://github.com/morluto/flameox/issues
License-Expression: MIT
License-File: LICENSE
Requires-Python: >=3.12
Requires-Dist: anyio<5,>=4.9
Requires-Dist: concurrent-log-handler<0.10,>=0.9.28
Requires-Dist: defusedxml<0.8,>=0.7.1
Requires-Dist: duckdb<1.6,>=1.5.4
Requires-Dist: httpx<0.29,>=0.28
Requires-Dist: ijson<4,>=3.4
Requires-Dist: mcp-types==2.0.0
Requires-Dist: mcp==2.0.0
Requires-Dist: numpy<3,>=2.2
Requires-Dist: packaging<27,>=24
Requires-Dist: platformdirs<5,>=4.3
Requires-Dist: portalocker<4,>=3.2
Requires-Dist: psutil<8,>=7.0
Requires-Dist: pyarrow<26,>=20
Requires-Dist: pydantic<2.14,>=2.13.4
Requires-Dist: pyperf<2.11,>=2.10
Requires-Dist: python-json-logger<4,>=3.3
Requires-Dist: pytz>=2024.2
Requires-Dist: questionary<3,>=2.1
Requires-Dist: rfc8785==0.1.4
Requires-Dist: scipy<2,>=1.15
Requires-Dist: statsmodels<1,>=0.14
Requires-Dist: tomli-w<2,>=1.2
Requires-Dist: tomlkit<1,>=0.13
Requires-Dist: typer<1,>=0.16
Provides-Extra: all
Requires-Dist: aiperf<0.13,>=0.12; extra == 'all'
Requires-Dist: coverage<8,>=7.14; extra == 'all'
Requires-Dist: memray>=1.17; extra == 'all'
Requires-Dist: nvidia-ml-py==13.610.43; extra == 'all'
Requires-Dist: opentelemetry-proto<1.45,>=1.44; extra == 'all'
Requires-Dist: perfetto<0.58,>=0.57; extra == 'all'
Requires-Dist: protobuf<7,>=5; extra == 'all'
Requires-Dist: py-spy<0.5,>=0.4.2; extra == 'all'
Requires-Dist: pyperf<2.11,>=2.10; extra == 'all'
Requires-Dist: pytest-reportlog<2,>=1; extra == 'all'
Requires-Dist: pytest-xdist>=3.6; extra == 'all'
Requires-Dist: pytest>=8.3; extra == 'all'
Requires-Dist: torch>=2.7; extra == 'all'
Provides-Extra: cpu
Requires-Dist: py-spy<0.5,>=0.4.2; extra == 'cpu'
Provides-Extra: dev
Requires-Dist: deptry>=0.23; extra == 'dev'
Requires-Dist: hypothesis>=6.130; extra == 'dev'
Requires-Dist: import-linter>=2.2; extra == 'dev'
Requires-Dist: mypy>=1.15; extra == 'dev'
Requires-Dist: pip-audit>=2.9; extra == 'dev'
Requires-Dist: pyarrow-stubs>=20.0.0.20260625; extra == 'dev'
Requires-Dist: pytest-cov>=6.1; extra == 'dev'
Requires-Dist: pytest-randomly>=3.16; extra == 'dev'
Requires-Dist: pytest-reportlog<2,>=1; extra == 'dev'
Requires-Dist: pytest-rerunfailures>=15; extra == 'dev'
Requires-Dist: pytest-xdist>=3.6; extra == 'dev'
Requires-Dist: pytest>=8.3; extra == 'dev'
Requires-Dist: ruff>=0.11; extra == 'dev'
Requires-Dist: scipy-stubs<1.19,>=1.18.0.1; extra == 'dev'
Requires-Dist: twine>=6.1; extra == 'dev'
Requires-Dist: vulture>=2.14; extra == 'dev'
Provides-Extra: execution
Requires-Dist: coverage<8,>=7.14; extra == 'execution'
Provides-Extra: hardware
Requires-Dist: nvidia-ml-py==13.610.43; extra == 'hardware'
Provides-Extra: inference
Requires-Dist: aiperf<0.13,>=0.12; extra == 'inference'
Provides-Extra: memory
Requires-Dist: memray>=1.17; extra == 'memory'
Provides-Extra: python
Requires-Dist: pyperf<2.11,>=2.10; extra == 'python'
Provides-Extra: test
Requires-Dist: pytest-reportlog<2,>=1; extra == 'test'
Requires-Dist: pytest-xdist>=3.6; extra == 'test'
Requires-Dist: pytest>=8.3; extra == 'test'
Provides-Extra: torch
Requires-Dist: torch>=2.7; extra == 'torch'
Provides-Extra: trace
Requires-Dist: opentelemetry-proto<1.45,>=1.44; extra == 'trace'
Requires-Dist: perfetto<0.58,>=0.57; extra == 'trace'
Requires-Dist: protobuf<7,>=5; extra == 'trace'
Description-Content-Type: text/markdown

<h1 align="center">flameox</h1>

<p align="center"><strong>Local runtime evidence for coding agents investigating performance, memory, execution, concurrency, and reliability.</strong></p>

<p align="center">
  <img
    src="docs/assets/flameox-mascot-flamegraph.png"
    width="420"
    alt="flameox mascot: an ox with a flame graph between its horns"
  >
</p>

<p align="center">
  <img src="https://img.shields.io/badge/Python-3.12%2B-3776AB?style=flat&logo=python&logoColor=white" alt="Python 3.12 or newer">
  <img src="https://img.shields.io/badge/Data-Stays_Local-F97316?style=flat" alt="Data stays local">
  <img src="https://img.shields.io/badge/Interfaces-CLI_%2B_MCP-7C3AED?style=flat" alt="CLI and MCP interfaces">
</p>

<!-- mcp-name: io.github.morluto/flameox -->

Flameox coordinates maintained profilers, benchmark tools, and trace processors;
preserves their native artifacts and provenance; and exposes bounded evidence to
an agent. The agent forms the hypothesis. Flameox makes the measurements and
experimental record inspectable.

It is not a profiler, hosted observability service, arbitrary shell or SQL
gateway, source-code editor, or automatic bug finder.

## Quick start

Connect a supported MCP client through the guided setup:

```console
npx flameox@latest setup
```

Restart the client, open the project you intend to inspect, and ask it to:

> Initialize Flameox in this project and list the available profiling capabilities.

Setup installs a versioned local runtime and changes only approved client
configuration. Project initialization is separate and creates `.diagnostics/`
only after the client calls the initialization workflow for its fixed project
root.

For source development:

```console
uv sync --extra dev
uv run flameox init .
uv run flameox status
```

Python 3.12 or newer and the committed `uv.lock` are required.

## Investigation path

```text
symptom → capture or import → bounded evidence → hypothesis
        → discriminating experiment → supported, refuted, or inconclusive finding
```

Typical evidence sources include pyperf, py-spy, pytest-reportlog, coverage.py,
Memray, Perfetto, torch.profiler, Nsight Systems, Nsight Compute, ROCprofiler,
Compute Sanitizer, NVBench, and typed inference-provider exports. Availability
depends on the host, permissions, installed extras, and selected adapter. Flameox
reports missing evidence instead of silently substituting a weaker source.

A profile is exploratory. A performance or correctness conclusion requires a
representative workload, declared metric and estimand, compatible run identity,
preserved samples, and an appropriate semantic oracle.

## Named workloads

Commands live in `flameox.toml` as argument arrays. Parameters are declared
scalars; there is no shell expansion.

```toml
schema_version = 1

[workloads.scan]
argv = ["python", "bench.py", "--implementation", "{implementation}"]
cwd = "."
timeout_seconds = 60

[workloads.scan.parameters]
implementation = ["baseline", "candidate"]

[workloads.scan.oracle]
strength = "cross_treatment_equivalence"
argv = ["python", "validate.py", "--implementation", "{implementation}"]

[experiments.scan_comparison]
workload = "scan"
design = "randomized_complete_blocks"
blocks = 10
treatment_factor = "implementation"
combination_policy = "cartesian"
primary_metric = "pyperf.workload"
polarity = "lower_is_better"
estimand = "median_paired_log_ratio"
practical_threshold = 0.05
confidence_level = 0.95
random_seed = 1984

[experiments.scan_comparison.factors]
implementation = ["baseline", "candidate"]
```

The MCP `configure_workload` tool validates and writes the canonical definition
without executing it. A manually authored valid definition is active
immediately; there is no approval copy or secondary workload registry.

```console
uv run flameox workload show scan --json
uv run flameox capture plan pyperf --workload scan \
  --parameters '{"implementation":"baseline"}' --json
uv run flameox capture run pyperf --workload scan \
  --parameters '{"implementation":"baseline"}' --json
```

Planning resolves every executable once. The resulting binding contains the
exact invocation path, canonical target, trust decision, and file identity.
Execution revalidates that binding instead of searching `PATH` again. Plans are
short-lived, single-use capabilities whose complete intent is retained in the
workspace SQLite control plane.

## Experiments and analysis

```console
uv run flameox investigations create \
  '{"question":"Does the candidate remove reverse-scan overhead?"}' --json
uv run flameox hypotheses record @hypothesis.json --json
uv run flameox experiment plan scan_comparison \
  --investigation <investigation-id> --adapter pyperf --json
uv run flameox experiment run scan_comparison \
  --investigation <investigation-id> --adapter pyperf --json
```

Experiments retain randomized treatment order, attempted trials, failures,
cancellations, validation receipts, and exclusions. Analyses resolve all input
through one pinned corpus snapshot:

```console
uv run flameox analyze hotspots <run-or-artifact>
uv run flameox analyze scaling <experiment-id>
uv run flameox analyze compare @comparison-request.json
uv run flameox analyze memory <run-or-artifact>
uv run flameox analyze execution <run-or-artifact>
uv run flameox analyze pytorch <run-or-artifact>
uv run flameox analyze failures
```

Read-only analysis does not create a durable claim. Use `analyze record`,
`analyze record-comparison`, or `findings record` when the result should become
part of the investigation history.

## Data and safety boundaries

`.diagnostics/` contains:

- `control-plane.sqlite3` for plans, operations, runs, revisions, idempotency,
  and relationships;
- content-addressed native artifacts;
- immutable Parquet generations and corpus commits;
- a rebuildable `catalog.duckdb` analytical cache.

Large evidence does not live in SQLite. Deleting `catalog.duckdb` does not
delete evidence; `flameox catalog rebuild` recreates it from committed
generations.

The CLI and MCP server expose bounded task-shaped operations, not shell strings,
raw SQL, or arbitrary artifact bytes. Workloads may access the network unless
active containment denies it. The control process performs network I/O only for
explicit setup, upgrade, approved provider acquisition, or explicitly enabled
symbol services—not during ordinary capture or analysis.

The trusted-local capture path records that descendant containment is not
enforced. Projects that require managed containment can select it explicitly;
planning refuses when the requested guarantee is unavailable.

## CLI and MCP discovery

```console
uv run flameox --help
uv run flameox mcp serve --project-root .
uv run flameox mcp inspect --project-root . --json
```

`mcp inspect` is the authoritative inventory of tool schemas, annotations, and
resource templates for the installed version. See [CLI and MCP
boundaries](docs/interfaces.md) for workflow and trust semantics.

## Integrity and retention

```console
uv run flameox validate
uv run flameox validate --full
uv run flameox catalog validate
uv run flameox catalog rebuild
uv run flameox recover
uv run flameox gc
uv run flameox gc --apply
```

Validation never repairs evidence. Garbage collection is a dry run unless
`--apply` is supplied, and applied candidates first move to recoverable trash.
Permanent purge requires a separate explicit command naming an expired trash
manifest.

## Documentation

- [Architecture](docs/architecture.md) — authoritative module and process boundaries
- [Storage and evidence](docs/storage-and-evidence.md) — authority, snapshots, and publication
- [Investigations](docs/investigations.md) — experiments, analysis, and claim quality
- [Adapters](docs/adapters.md) — producer ownership and compatibility
- [Runtime safety](docs/runtime-safety.md) — execution, filesystem, cancellation, and retention
- [CLI and MCP](docs/interfaces.md) — public workflow and trust boundaries
- [Testing](docs/testing.md) — suite ownership and CI lanes
- [Contributing](CONTRIBUTING.md) — development and pull-request workflow

## Development

```console
uv sync --extra dev
uv run ruff check src tests tools
uv run mypy src tests tools
uv run pytest -q
```

See [the testing guide](docs/testing.md) for marker and provider commands.
Flameox is available under the
[MIT License](LICENSE).
