oxide-agent 0.1.1__tar.gz

oxide_agent-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kiy-K
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

oxide_agent-0.1.1/PKG-INFO

@@ -0,0 +1,144 @@
+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)

oxide_agent-0.1.1/README.md

@@ -0,0 +1,116 @@
+# 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)

oxide_agent-0.1.1/pyproject.toml

@@ -0,0 +1,109 @@
+[project]
+name = "oxide-agent"
+version = "0.1.1"
+description = "OXIDE v2: a structural context engine for agents"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.12,<3.15"
+dependencies = [
+    "cryptography<49; sys_platform == 'darwin' and platform_machine == 'x86_64'",
+    "cryptography>=50; sys_platform != 'darwin' or platform_machine != 'x86_64'",
+    "fastmcp==4.1.1",
+    "ladybug==0.21.0",
+    "networkx>=3.4,<4",
+    "pathspec>=0.12",
+    "tree-sitter>=0.25,<0.27",
+    "tree-sitter-c==0.24.2",
+    "tree-sitter-cpp==0.23.4",
+    "tree-sitter-go==0.25.0",
+    "tree-sitter-java==0.23.5",
+    "tree-sitter-javascript==0.23.1",
+    "tree-sitter-python==0.25.0",
+    "tree-sitter-rust==0.24.2",
+    "tree-sitter-typescript==0.23.2",
+]
+
+[project.urls]
+Repository = "https://github.com/Kiy-K/oxide"
+Documentation = "https://github.com/Kiy-K/oxide/blob/main/docs/public-api.md"
+
+[project.scripts]
+oxide = "oxide.cli:main"
+
+[project.optional-dependencies]
+structural = ["ast-grep-py==0.51.0"]
+
+[tool.uv.build-backend]
+module-name = "oxide"
+
+[tool.ruff]
+line-length = 100
+src = [
+    "src",
+    "tests",
+]
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "F",
+    "W",
+    "I",
+    "B",
+    "UP",
+    "SIM",
+    "RUF",
+]
+
+[tool.mypy]
+strict = true
+files = [
+    "src",
+    "tests/python",
+]
+mypy_path = [
+    "src",
+    "tests/python",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests/python"]
+addopts = "-ra --strict-markers"
+markers = ["real_fsync: storage flushes for real (durability tests); others skip fsync"]
+
+[tool.pyrefly]
+project-includes = [
+    "src",
+    "tests/python",
+]
+search-path = [
+    "src",
+    "tests/python",
+]
+preset = "legacy"
+check-unannotated-defs = true
+infer-return-types = "never"
+
+[tool.pyrefly.errors]
+implicit-any = "error"
+method-assign = "error"
+unannotated-return = "error"
+implicit-any-parameter = "error"
+no-any-return = "error"
+redundant-cast = "warn"
+
+[dependency-groups]
+dev = [
+    "ast-grep-py==0.51.0",
+    "mypy>=1.13",
+    "pyrefly>=1.4.0",
+    "pytest>=8.3",
+    "pytest-xdist>=3.8.0",
+    "ruff>=0.8",
+    "types-networkx>=3.6.1.20261024",
+]
+
+[build-system]
+requires = ["uv_build>=0.9,<0.13"]
+build-backend = "uv_build"

oxide_agent-0.1.1/pyproject.toml.orig

@@ -0,0 +1,100 @@
+# OXIDE v2: Python engine (ADR-0011). `mise run verify` is the one check.
+[project]
+# PyPI's "oxide" belongs to another project; the import package and CLI stay `oxide`.
+name = "oxide-agent"
+version = "0.1.1"
+description = "OXIDE v2: a structural context engine for agents"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+# ladybug 0.21.0 ships wheels for CPython 3.10-3.14 only.
+requires-python = ">=3.12,<3.15"
+dependencies = [
+    # Not imported: fastmcp needs it, and 49+ ships no Intel macOS wheels (docs/platforms.md).
+    "cryptography<49; sys_platform == 'darwin' and platform_machine == 'x86_64'",
+    "cryptography>=50; sys_platform != 'darwin' or platform_machine != 'x86_64'",
+    "fastmcp==4.1.1",
+    "ladybug==0.21.0",
+    "networkx>=3.4,<4",
+    "pathspec>=0.12",
+    "tree-sitter>=0.25,<0.27",
+    "tree-sitter-c==0.24.2",
+    "tree-sitter-cpp==0.23.4",
+    "tree-sitter-go==0.25.0",
+    "tree-sitter-java==0.23.5",
+    "tree-sitter-javascript==0.23.1",
+    "tree-sitter-python==0.25.0",
+    "tree-sitter-rust==0.24.2",
+    "tree-sitter-typescript==0.23.2",
+]
+
+[project.urls]
+Repository = "https://github.com/Kiy-K/oxide"
+Documentation = "https://github.com/Kiy-K/oxide/blob/main/docs/public-api.md"
+
+[project.scripts]
+oxide = "oxide.cli:main"
+
+[tool.pyrefly.errors]
+implicit-any = "error"
+method-assign = "error"
+unannotated-return = "error"
+implicit-any-parameter = "error"
+no-any-return = "error"
+redundant-cast = "warn"
+
+[project.optional-dependencies]
+# Explicit structural search (Repository.structural_search). Optional: it adds 46 MB to a
+# 94 MB install (docs/phase-6/astgrep-feasibility/ at 013e791).
+# Pinned exactly: pre-1.0, own grammars.
+structural = [
+    "ast-grep-py==0.51.0",
+]
+
+[dependency-groups]
+dev = [
+    "ast-grep-py==0.51.0",
+    "mypy>=1.13",
+    "pyrefly>=1.4.0",
+    "pytest>=8.3",
+    "pytest-xdist>=3.8.0",
+    "ruff>=0.8",
+    "types-networkx>=3.6.1.20261024",
+]
+
+[build-system]
+requires = ["uv_build>=0.9,<0.13"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "oxide"
+
+[tool.ruff]
+line-length = 100
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "B", "UP", "SIM", "RUF"]
+
+[tool.mypy]
+strict = true
+files = ["src", "tests/python"]
+mypy_path = ["src", "tests/python"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests/python"]
+addopts = "-ra --strict-markers"
+markers = ["real_fsync: storage flushes for real (durability tests); others skip fsync"]
+
+[tool.pyrefly]
+project-includes = [
+    "src",
+    "tests/python",
+]
+search-path = [
+    "src",
+    "tests/python",
+]
+preset = "legacy"
+check-unannotated-defs = true
+infer-return-types = "never"

oxide_agent-0.1.1/src/oxide/__init__.py

@@ -0,0 +1,57 @@
+"""OXIDE v2: a structural context engine for agents (docs/spec/SPEC.md, ADR-0011)."""
+
+from oxide.api import Repository, index_repository, open_repository
+from oxide.models import (
+    ChannelStatus,
+    ContextBundle,
+    ContextItem,
+    Entity,
+    EntryPoint,
+    FileInfo,
+    HintIssue,
+    Impact,
+    ImpactHop,
+    IndexReport,
+    ItemEntity,
+    JudgeStatus,
+    Omission,
+    OxideError,
+    Relation,
+    RouteSummary,
+    SearchResult,
+    Seed,
+    Skip,
+    Snapshot,
+    SourceRef,
+    StructuralMatch,
+    StructuralResult,
+)
+
+__all__ = [
+    "ChannelStatus",
+    "ContextBundle",
+    "ContextItem",
+    "Entity",
+    "EntryPoint",
+    "FileInfo",
+    "HintIssue",
+    "Impact",
+    "ImpactHop",
+    "IndexReport",
+    "ItemEntity",
+    "JudgeStatus",
+    "Omission",
+    "OxideError",
+    "Relation",
+    "Repository",
+    "RouteSummary",
+    "SearchResult",
+    "Seed",
+    "Skip",
+    "Snapshot",
+    "SourceRef",
+    "StructuralMatch",
+    "StructuralResult",
+    "index_repository",
+    "open_repository",
+]

oxide_agent-0.1.1/src/oxide/__main__.py

@@ -0,0 +1,3 @@
+from oxide.cli import main
+
+raise SystemExit(main())