Metadata-Version: 2.5
Name: flameox
Version: 0.2.2
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: coverage<8,>=7.14
Requires-Dist: defusedxml<0.8,>=0.7.1
Requires-Dist: duckdb<1.6,>=1.5.4
Requires-Dist: ijson<4,>=3.4
Requires-Dist: mcp-types==2.0.0
Requires-Dist: mcp==2.0.0
Requires-Dist: packaging<27,>=24
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: pytz>=2024.2
Requires-Dist: rfc8785==0.1.4
Requires-Dist: typer<1,>=0.16
Provides-Extra: all
Requires-Dist: aiperf<0.13,>=0.12; extra == 'all'
Requires-Dist: memray>=1.17; 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: 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: 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>=8.3; extra == 'dev'
Requires-Dist: ruff>=0.11; extra == 'dev'
Requires-Dist: vulture>=2.14; extra == 'dev'
Provides-Extra: inference
Requires-Dist: aiperf<0.13,>=0.12; extra == 'inference'
Provides-Extra: memory
Requires-Dist: memray>=1.17; extra == 'memory'
Provides-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>Bounded local runtime evidence for coding agents.</strong></p>

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

Flameox coordinates profilers, benchmark tools, trace processors, and direct
local targets. It gives an agent a short path from an explicit native artifact
or live command to bounded evidence, while keeping preservation optional.

Version 0.2 is a clean break. There is no workspace to initialize, no
`flameox.toml`, no SQLite control plane, no durable job to poll, and no parent
directory discovery. Existing artifacts remain usable by passing their exact
paths and formats to `analyze`; old `.diagnostics` state is not migrated.

## Quick start

```console
uv sync --extra dev --extra memory --extra trace --extra cpu
uv run flameox capabilities discover --intent "CPU hotspots"
uv run flameox analyze artifact.preview /absolute/path/to/artifact.json
uv run flameox capture --provider direct -- python benchmark.py
```

The MCP server fixes its project root at startup. Manual launches default to
the startup working directory:

```console
uv run flameox mcp serve --project-root "$PWD"
```

`flameox setup` prints the equivalent stdio client configuration. Explicit
`--provider` selections add the matching Python extras to a persistent uv tool
environment without removing its existing provider extras. System and vendor
tools are diagnosed with external install guidance. Setup never initializes the
project or creates `.flameox`.

## Authority model

```text
explicit artifact paths / typed direct target
                    │
                    ▼
         bounded process-lifespan runtime
             │                │
             ▼                ▼
       inline evidence   session scratch/cache
                              │
                       explicit preservation
                              │
                              ▼
                    <project>/.flameox
```

Analysis and unpreserved capture make no durable Flameox writes. Capture
artifacts stay in bounded session scratch until preservation or server
shutdown. The first `preserve_evidence` call creates `.flameox`, stores native
bytes and a canonical evidence bundle by SHA-256, and adds `.flameox/` to the
repository-local `.git/info/exclude` when applicable.

The agent owns hypotheses and narrative findings in its own notes. Flameox owns
only observed inputs, effective requests, execution provenance, typed evidence,
coverage, truncation, limitations, and optional immutable preservation.

## MCP interface

The server exposes exactly six tools:

- `discover_capabilities`
- `inspect_capabilities`
- `analyze`
- `capture_and_analyze`
- `preserve_evidence`
- `query_evidence`

It exposes one resource template, `flameox://evidence/{evidence_id}`, for the
digest-bound, redacted projection of the canonical immutable manifest. Full
argv, environment values, working directories, and host paths remain available
only through explicit local manifest inspection. Native artifact bytes are
deliberately not available as MCP resources.

Direct capture accepts an argv array, a project-contained cwd, bounded
environment overrides, provider and analysis arguments, and limits. Shell
strings are never accepted. Work remains owned by the live MCP request, so SDK
progress and cancellation apply directly; there are no detached or
restart-surviving tasks.

Managed external collectors such as py-spy execute from Flameox's uv tool
environment. In-process collectors such as coverage.py and Memray are verified
in, and run with, the workload's declared Python interpreter. Flameox does not
substitute one Python runtime for the other.

## Evidence quality

An investigation still follows:

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

A profile supports exploration, not causality. Confirmatory claims require a
representative target, declared metric and estimand, compatible identities,
preserved samples, a practical threshold, and an appropriate semantic oracle.

See [architecture](docs/architecture.md), [storage and evidence](docs/storage-and-evidence.md),
[interfaces](docs/interfaces.md), [runtime safety](docs/runtime-safety.md), and
[investigations](docs/investigations.md) for the contracts.

## Development

Flameox requires Python 3.12 or newer and uses the committed `uv.lock`.

```console
uv run ruff check src tests tools
uv run ruff format --check src tests tools
uv run mypy src tests tools
uv run lint-imports
uv run pytest -q
```

The project is licensed under the MIT License.
