Metadata-Version: 2.4
Name: oxide-agent
Version: 0.1.1
Summary: OXIDE v2: a structural context engine for agents
License-Expression: MIT
License-File: LICENSE
Requires-Dist: cryptography<49 ; platform_machine == 'x86_64' and sys_platform == 'darwin'
Requires-Dist: cryptography>=50 ; platform_machine != 'x86_64' or sys_platform != 'darwin'
Requires-Dist: fastmcp==4.1.1
Requires-Dist: ladybug==0.21.0
Requires-Dist: networkx>=3.4,<4
Requires-Dist: pathspec>=0.12
Requires-Dist: tree-sitter>=0.25,<0.27
Requires-Dist: tree-sitter-c==0.24.2
Requires-Dist: tree-sitter-cpp==0.23.4
Requires-Dist: tree-sitter-go==0.25.0
Requires-Dist: tree-sitter-java==0.23.5
Requires-Dist: tree-sitter-javascript==0.23.1
Requires-Dist: tree-sitter-python==0.25.0
Requires-Dist: tree-sitter-rust==0.24.2
Requires-Dist: tree-sitter-typescript==0.23.2
Requires-Dist: ast-grep-py==0.51.0 ; extra == 'structural'
Requires-Python: >=3.12, <3.15
Project-URL: Repository, https://github.com/Kiy-K/oxide
Project-URL: Documentation, https://github.com/Kiy-K/oxide/blob/main/docs/public-api.md
Provides-Extra: structural
Description-Content-Type: text/markdown

# OXIDE

A structural context engine for coding agents.

OXIDE captures a repository, derives a typed graph of its files, modules, symbols, and
relations, persists that graph in LadybugDB, and answers "what code matters for this
task?" with a bounded, source-backed context bundle. Retrieval is vectorless: BM25 over
code-aware terms plus structural seeds from typed hints, then TreeRouter and
deterministic selection and packing. No embeddings, model runners, or network access on
the query path.

Status: pre-release, on `main`. Python, TypeScript/TSX, JavaScript/JSX, Go, Rust,
Java, C and C++ have parser slices ([TypeScript](docs/typescript.md), [JavaScript](docs/javascript.md),
[Go](docs/go.md), [Rust](docs/rust.md), [Java](docs/java.md), [C](docs/c.md), [C++](docs/cpp.md)); other files are kept as
unsupported file evidence. The public Python API is the product boundary
([docs/public-api.md](docs/public-api.md)). The legacy v1 implementation and its README
are pinned at commit
[`ac985b28`](https://github.com/Kiy-K/oxide/tree/ac985b28fcff7663aedadf2db5b40aa2dc325580);
the original documentation remains available in
[the pinned v1 README](https://github.com/Kiy-K/oxide/blob/ac985b28fcff7663aedadf2db5b40aa2dc325580/README.md).

## Install

OXIDE needs CPython 3.12-3.14. Development uses [mise](https://mise.jdx.dev) and
[uv](https://docs.astral.sh/uv/):

```bash
git clone https://github.com/Kiy-K/oxide && cd oxide
mise run bootstrap        # uv sync --locked + `oxide prepare`
```

Without mise, run `uv sync --locked`, then `uv run oxide prepare`. `oxide prepare` is
the only network access OXIDE makes. It downloads the pinned LadybugDB FTS extension for
your platform (Linux x86_64, macOS 15+ x86_64/arm64, Windows x86_64;
[docs/platforms.md](docs/platforms.md)) and checks its SHA-256. Without that extension,
the lexical channel reports `unavailable` and structural seeds and routing still work.

Outside the checkout, install the `oxide-agent` distribution (`pip install oxide-agent`
once it is published, or build it with `uv build` and `pip install dist/oxide_agent-*.whl`),
then run `oxide prepare`. That needs only Python and the native wheels. It does not need Rust,
Node.js, or a compiler. On Windows, LadybugDB also needs the OpenSSL 3 x64 DLLs in the
system directory. It opens only ASCII paths there, so with a non-ASCII user name, set
`OXIDE_DATA_DIR` and `OXIDE_FTS_EXTENSION` ([docs/platforms.md](docs/platforms.md)).

## Use

```bash
uv run oxide index  path/to/repo                      # built | unchanged
uv run oxide search path/to/repo "where are failed requests retried" --limit 20
uv run oxide context path/to/repo "where are failed requests retried" --budget 1024 \
    --symbol RetryPolicy --file src/http/client.py
```

Every command takes `--json` (the typed result) and `--data-dir`. `context` prints
the payload on stdout and `used/budget units` on stderr. Errors print
`error[<code>]: <message>` and exit 2.

```python
import oxide

with oxide.open_repository("path/to/repo") as repo:   # owns the store until closed
    repo.index()
    hits = repo.search("where are failed requests retried")
    bundle = repo.build_context("where are failed requests retried", budget=1024)
    print(bundle.payload)                             # used <= budget
```

### MCP

`oxide mcp` serves one read-only tool, `oxide_search`, over stdio (FastMCP). Its
`mode` is `search` (ranked locations, the default) or `context` (a budgeted source
bundle); `oxide_context` was folded into it on 2026-10-18. It never indexes: run
`oxide index` first, and again whenever you want fresher results, even while the
server runs.

```bash
uv run oxide mcp --repo path/to/repo                      # stdio, for a local agent
uv run oxide mcp --repo path/to/repo --http --port 8765   # stateless HTTP, loopback only
```

For example, in Claude Code: `claude mcp add oxide -- uv run --directory /path/to/oxide
oxide mcp --repo /path/to/repo`. With `--repo` (repeatable) calls may only name those
repositories, and with exactly one they may omit `repository`.

The store lives under `--data-dir`, else `$OXIDE_DATA_DIR`, else
`$XDG_DATA_HOME/oxide/py` (`~/.local/share/oxide/py`). It is never captured, even
when it sits inside the repository.

## Limits

- One owner per store, across processes. A `Repository` is not thread-safe.
- Indexing is a full rebuild per change, and capture holds the captured bytes in
  memory (at most 1 GiB in scope, 1 MiB per file).
- Verified on Linux x86_64, macOS 15+ (x86_64, arm64) and Windows x86_64 by the
  Platforms workflow. Windows needs the OpenSSL 3 DLLs and ASCII store paths; see
  [docs/platforms.md](docs/platforms.md).

[docs/public-api.md](docs/public-api.md) has the full list, with errors, bounds and
recovery behavior.

## Develop

```bash
mise run verify           # ruff, mypy --strict, pytest (CI runs exactly this)
uv run python scripts/bench.py path/to/corpus   # latency and peak RSS, JSON report
```

Architecture: [docs/spec/SPEC.md](docs/spec/SPEC.md), [docs/decisions.md](docs/decisions.md)
and the decisions in [docs/adr/](docs/adr/), in particular
[ADR-0011](docs/adr/0011-python-engine-vectorless.md) (Python engine, vectorless
retrieval). Contributor workflow: [docs/agents/workflow.md](docs/agents/workflow.md).
Documentation and historical evidence: [docs index](docs/README.md).

## License

[MIT](LICENSE)
