apexgraph 0.1.0__tar.gz

apexgraph-0.1.0/.gitattributes

@@ -0,0 +1,3 @@
+# Normalize line endings: text files are LF in the repo, native in the working tree.
+* text=auto
+*.py text eol=lf

apexgraph-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,35 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Lint (ruff)
+        run: uv run ruff check .
+
+      - name: Format check (black)
+        run: uv run black --check .
+
+      - name: Tests (pytest)
+        run: uv run pytest -q

apexgraph-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,49 @@
+name: Publish to PyPI
+
+# Publishes to PyPI when a GitHub Release is published, using Trusted Publishing
+# (OIDC) — no API token is stored anywhere. The PyPI project (distribution name
+# "apexgraph") must have a matching trusted publisher configured (repo:
+# alfonsomayoral/graphex, workflow: publish.yml, environment: pypi). See RELEASING.md.
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+      - name: Build sdist and wheel
+        run: uv build
+      - name: Validate metadata
+        run: uvx twine check dist/*
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/apexgraph
+    permissions:
+      id-token: write # required for Trusted Publishing (OIDC)
+    steps:
+      - name: Download build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

apexgraph-0.1.0/.gitignore

@@ -0,0 +1,34 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+*.egg
+
+# Virtual envs
+.venv/
+venv/
+env/
+
+# uv
+.uv/
+
+# Tooling caches
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+
+# Graphex sidecar cache + runtime artifacts
+.graphex/
+graphify-out/
+
+# OS / editor
+.DS_Store
+Thumbs.db
+.idea/
+.vscode/
+*.swp

apexgraph-0.1.0/CHANGELOG.md

@@ -0,0 +1,42 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-06-16
+
+### Added
+- Multi-format graph loader (graphify JSON, GraphML, Neo4j CSV) preserving
+  hyperedges, edge weight/confidence, communities and god nodes.
+- BM25 lexical retriever with a cached inverted index and identifier-aware
+  tokenizer (camelCase / snake_case / PascalCase, compounds preserved).
+- Personalized PageRank / random-walk-with-restart over weighted edges and
+  hyperedge cliques, plus query-independent global PageRank.
+- Scorer fusing BM25-seeded PPR with an importance/god-node prior.
+- Cost-aware MMR subgraph selection with a connectivity bonus and honest token
+  accounting (including injected source code); optional exact DP-knapsack mode.
+- On-disk cache (`.graphex/`) for global PageRank and the BM25 index, invalidated
+  by content fingerprint.
+- Static indexer for Python (`ast`), TypeScript/JavaScript (tree-sitter with a
+  regex fallback) and Go (regex), with incremental re-indexing by file hash.
+- Markdown / JSON / YAML formatter and source-code injector.
+- MCP stdio server exposing `graphex_query`, `graphex_explain`, `graphex_path`
+  and `graphex_stats`.
+- Click CLI: `query`, `index`, `serve`, `stats`, `explain`, `path`, `diff`,
+  `export`, `benchmark`, `audit`, `init` — with autodiscovery, rich `--explain`,
+  and UTF-8 output on Windows.
+- Context export for Claude / ChatGPT / CLAUDE.md, graph diffing, `.graphexignore`
+  filtering, a JSONL query audit log, and interactive HTML visualisation.
+- Optional dense-embedding backend (OpenAI / Anthropic) behind the `[dense]` extra.
+- Benchmark reporting recall@budget alongside token savings.
+
+### Security
+- Code injection (`--inject-code`) is contained to the project root: a crafted
+  `source_file` in an untrusted graph can no longer read arbitrary host files via
+  absolute paths or `..` traversal.
+- The interactive visualisation loads vis-network from a pinned, immutable CDN
+  URL with a Subresource Integrity (SRI) hash, so a compromised CDN cannot inject
+  script into a generated page.
+
+[0.1.0]: https://github.com/alfonsomayoral/graphex/releases/tag/v0.1.0

apexgraph-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,37 @@
+# Contributing to Graphex
+
+Thanks for your interest in improving Graphex.
+
+## Setup
+
+```bash
+git clone https://github.com/alfonsomayoral/graphex
+cd graphex
+uv sync
+```
+
+## Before you open a PR
+
+```bash
+uv run ruff check .     # lint (must pass)
+uv run black --check .  # format (must pass)
+uv run pytest           # tests (must pass)
+```
+
+## Architecture at a glance
+
+Each module has a single responsibility; the data contract lives in
+`graphex/models.py` (`KnowledgeGraph`, `Node`, `Edge`, `Hyperedge`). The scoring
+pipeline is `retrieval/bm25.py` → `retrieval/ppr.py` → `retrieval/fusion.py` →
+`scorer.py`; selection is `budget.py`; the user surface is `cli.py` and `mcp.py`.
+
+When you add a module, add a matching `tests/test_<module>.py`. Keep public
+functions typed and documented, and keep new dependencies out of the default
+install path — put optional features behind an extra in `pyproject.toml`.
+
+## Guidelines
+
+- Prefer reusing the helpers already in `models.py` and `retrieval/base.py`.
+- The budget invariant is sacred: `tokens_used` must never exceed the requested
+  budget. Any selection change needs a test that proves it.
+- Token-saving claims must be paired with a recall metric — see `benchmark.py`.

apexgraph-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alfonso Mayoral
+
+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.

apexgraph-0.1.0/PKG-INFO

@@ -0,0 +1,175 @@
+Metadata-Version: 2.4
+Name: apexgraph
+Version: 0.1.0
+Summary: Apex-relevance subgraph retrieval for AI agents. Feed your LLM the peak of your knowledge graph, sized to a token budget.
+Project-URL: Homepage, https://github.com/alfonsomayoral/graphex
+Project-URL: Repository, https://github.com/alfonsomayoral/graphex
+Project-URL: Issues, https://github.com/alfonsomayoral/graphex/issues
+Author-email: Alfonso Mayoral <alfonsomayoral29@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: ai-tools,bm25,cli,graphify,knowledge-graph,llm,mcp,pagerank,rag,token-budget
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Documentation
+Requires-Python: >=3.12
+Requires-Dist: click>=8.1
+Requires-Dist: networkx>=3.2
+Requires-Dist: pathspec>=0.12
+Requires-Dist: rich>=13.7
+Requires-Dist: tiktoken>=0.7
+Provides-Extra: dense
+Requires-Dist: anthropic>=0.34; extra == 'dense'
+Requires-Dist: openai>=1.40; extra == 'dense'
+Provides-Extra: ts
+Requires-Dist: tree-sitter-typescript>=0.23; extra == 'ts'
+Requires-Dist: tree-sitter>=0.22; extra == 'ts'
+Provides-Extra: viz
+Requires-Dist: watchdog>=4.0; extra == 'viz'
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+# Graphex
+
+**Apex-relevance subgraph retrieval for AI agents.**
+
+Feed your LLM the *peak* of your knowledge graph — sized to a token budget.
+
+[![CI](https://github.com/alfonsomayoral/graphex/actions/workflows/ci.yml/badge.svg)](https://github.com/alfonsomayoral/graphex/actions/workflows/ci.yml)
+![Python](https://img.shields.io/badge/python-3.12%2B-blue)
+![License](https://img.shields.io/badge/license-MIT-green)
+
+</div>
+
+---
+
+Knowledge graphs grow large. When an agent needs context about one corner of a
+codebase, dumping the whole graph into the prompt wastes tokens and money — and
+buries the relevant nodes in noise. **Graphex scores every node against your
+query and returns the most relevant, connected subgraph that fits within a token
+budget**, ready to paste into a prompt or serve over MCP.
+
+```bash
+graphex index .                            # build a graph from your code (no LLM)
+graphex "how does auth work" --budget 4000 # retrieve the apex subgraph
+graphex serve                              # expose it to agents over MCP
+```
+
+Graphex reads the graphs produced by **graphify** and uses the rich signals
+graphify emits — edge weights, confidence, hyperedges, communities, and god
+nodes — that simpler tools throw away.
+
+## Install
+
+```bash
+uv tool install apexgraph            # or: pipx install apexgraph
+# optional extras:
+uv tool install "apexgraph[ts]"      # better TypeScript indexing (tree-sitter)
+uv tool install "apexgraph[dense]"   # OpenAI/Anthropic embedding backend
+```
+
+The PyPI distribution is `apexgraph`; the command and import name are `graphex`.
+Requires Python 3.12+.
+
+## How it works
+
+A five-stage pipeline, each stage a single-responsibility module:
+
+```
+  load ─▶ score ─▶ select ─▶ inject ─▶ render
+   │        │         │         │         │
+ multi-   BM25 →    cost-aware  source-   markdown /
+ format   PPR +     MMR under   code      json / yaml
+ loader   prior     budget      bodies
+                        ▲
+   index ───────────────┘   build a graph straight from code (no graphify)
+```
+
+**Relevance is one principled number, not a hand-tuned mix.** BM25 finds the
+nodes the query is literally about; those seed a **Personalized PageRank** walk
+that spreads relevance across the weighted graph (edge `weight × confidence`,
+plus hyperedge cliques); a light importance/god-node prior nudges genuinely
+central entities up. The query-independent half — global PageRank, the BM25
+inverted index — is precomputed once and cached, invalidated by content hash, so
+a query is just a lookup plus one walk.
+
+**Selection is a budgeted knapsack, solved as one.** Picking the highest-value
+set of nodes under a token ceiling is the 0/1 knapsack problem. Graphex selects
+by *marginal value per token* and shapes the result with two terms — an MMR
+penalty so it doesn't say the same thing twice, and a connectivity bonus so the
+result is a coherent connected subgraph, not a bag of redundant islands. An exact
+DP-knapsack mode is available for benchmarking the value ceiling.
+
+**Token accounting is honest.** A node's cost is the size of its *final rendered
+form*, including any injected source code — so `tokens_used` never lies and the
+output never overflows the budget you asked for.
+
+## Usage
+
+```bash
+# Index a project into a graphify-compatible graph.json (Python / TS / Go)
+graphex index ./src -o graph.json
+graphex index ./src --incremental          # re-index only changed files
+
+# Query (any unrecognised first arg routes here)
+graphex "session token validation" -b 2000
+graphex "auth flow" --explain               # per-node BM25 / PPR / prior breakdown
+graphex "auth flow" --inject-code           # include real function bodies, still in budget
+graphex "auth flow" --viz                   # interactive force-directed HTML
+
+# Inspect (node ids come from your indexed graph; these match examples/)
+graphex stats -g examples/sample_graph.json
+graphex explain auth_service_login -g examples/sample_graph.json
+graphex path auth_service auth_service_login -g examples/sample_graph.json
+
+# Export a context block to paste into a system prompt / CLAUDE.md
+graphex export "auth flow" -f claudemd -o CONTEXT.md
+
+# Measure quality honestly (recall@budget, not just tokens saved)
+graphex benchmark -q "auth flow" -q "db pooling" -b 1000 -b 4000
+
+# Compare two graph versions and see the change impact
+graphex diff old.json new.json --budget 2000
+```
+
+See [`examples/`](examples/) for a full walkthrough on a sample project.
+
+## MCP server
+
+Graphex speaks the Model Context Protocol over stdio (stdlib only, no SDK):
+
+```bash
+graphex serve --graph graph.json
+```
+
+It exposes four tools: `graphex_query`, `graphex_explain`, `graphex_path`,
+`graphex_stats`. Register it with Claude Code:
+
+```bash
+claude mcp add graphex -- graphex serve --graph /abs/path/to/graph.json
+```
+
+## Honest benchmarking
+
+"Tokens saved" is a vanity metric — a tool that returns nothing saves 100%.
+Graphex reports **recall@budget** alongside it: how much of the relevant set the
+budgeted subgraph actually captures. High savings with low recall means
+under-retrieval, and the benchmark makes that trade-off visible.
+
+## Development
+
+```bash
+uv sync
+uv run pytest          # test suite
+uv run ruff check .    # lint
+uv run black .         # format
+```
+
+## License
+
+MIT © Alfonso Mayoral

apexgraph-0.1.0/README.md

@@ -0,0 +1,141 @@
+<div align="center">
+
+# Graphex
+
+**Apex-relevance subgraph retrieval for AI agents.**
+
+Feed your LLM the *peak* of your knowledge graph — sized to a token budget.
+
+[![CI](https://github.com/alfonsomayoral/graphex/actions/workflows/ci.yml/badge.svg)](https://github.com/alfonsomayoral/graphex/actions/workflows/ci.yml)
+![Python](https://img.shields.io/badge/python-3.12%2B-blue)
+![License](https://img.shields.io/badge/license-MIT-green)
+
+</div>
+
+---
+
+Knowledge graphs grow large. When an agent needs context about one corner of a
+codebase, dumping the whole graph into the prompt wastes tokens and money — and
+buries the relevant nodes in noise. **Graphex scores every node against your
+query and returns the most relevant, connected subgraph that fits within a token
+budget**, ready to paste into a prompt or serve over MCP.
+
+```bash
+graphex index .                            # build a graph from your code (no LLM)
+graphex "how does auth work" --budget 4000 # retrieve the apex subgraph
+graphex serve                              # expose it to agents over MCP
+```
+
+Graphex reads the graphs produced by **graphify** and uses the rich signals
+graphify emits — edge weights, confidence, hyperedges, communities, and god
+nodes — that simpler tools throw away.
+
+## Install
+
+```bash
+uv tool install apexgraph            # or: pipx install apexgraph
+# optional extras:
+uv tool install "apexgraph[ts]"      # better TypeScript indexing (tree-sitter)
+uv tool install "apexgraph[dense]"   # OpenAI/Anthropic embedding backend
+```
+
+The PyPI distribution is `apexgraph`; the command and import name are `graphex`.
+Requires Python 3.12+.
+
+## How it works
+
+A five-stage pipeline, each stage a single-responsibility module:
+
+```
+  load ─▶ score ─▶ select ─▶ inject ─▶ render
+   │        │         │         │         │
+ multi-   BM25 →    cost-aware  source-   markdown /
+ format   PPR +     MMR under   code      json / yaml
+ loader   prior     budget      bodies
+                        ▲
+   index ───────────────┘   build a graph straight from code (no graphify)
+```
+
+**Relevance is one principled number, not a hand-tuned mix.** BM25 finds the
+nodes the query is literally about; those seed a **Personalized PageRank** walk
+that spreads relevance across the weighted graph (edge `weight × confidence`,
+plus hyperedge cliques); a light importance/god-node prior nudges genuinely
+central entities up. The query-independent half — global PageRank, the BM25
+inverted index — is precomputed once and cached, invalidated by content hash, so
+a query is just a lookup plus one walk.
+
+**Selection is a budgeted knapsack, solved as one.** Picking the highest-value
+set of nodes under a token ceiling is the 0/1 knapsack problem. Graphex selects
+by *marginal value per token* and shapes the result with two terms — an MMR
+penalty so it doesn't say the same thing twice, and a connectivity bonus so the
+result is a coherent connected subgraph, not a bag of redundant islands. An exact
+DP-knapsack mode is available for benchmarking the value ceiling.
+
+**Token accounting is honest.** A node's cost is the size of its *final rendered
+form*, including any injected source code — so `tokens_used` never lies and the
+output never overflows the budget you asked for.
+
+## Usage
+
+```bash
+# Index a project into a graphify-compatible graph.json (Python / TS / Go)
+graphex index ./src -o graph.json
+graphex index ./src --incremental          # re-index only changed files
+
+# Query (any unrecognised first arg routes here)
+graphex "session token validation" -b 2000
+graphex "auth flow" --explain               # per-node BM25 / PPR / prior breakdown
+graphex "auth flow" --inject-code           # include real function bodies, still in budget
+graphex "auth flow" --viz                   # interactive force-directed HTML
+
+# Inspect (node ids come from your indexed graph; these match examples/)
+graphex stats -g examples/sample_graph.json
+graphex explain auth_service_login -g examples/sample_graph.json
+graphex path auth_service auth_service_login -g examples/sample_graph.json
+
+# Export a context block to paste into a system prompt / CLAUDE.md
+graphex export "auth flow" -f claudemd -o CONTEXT.md
+
+# Measure quality honestly (recall@budget, not just tokens saved)
+graphex benchmark -q "auth flow" -q "db pooling" -b 1000 -b 4000
+
+# Compare two graph versions and see the change impact
+graphex diff old.json new.json --budget 2000
+```
+
+See [`examples/`](examples/) for a full walkthrough on a sample project.
+
+## MCP server
+
+Graphex speaks the Model Context Protocol over stdio (stdlib only, no SDK):
+
+```bash
+graphex serve --graph graph.json
+```
+
+It exposes four tools: `graphex_query`, `graphex_explain`, `graphex_path`,
+`graphex_stats`. Register it with Claude Code:
+
+```bash
+claude mcp add graphex -- graphex serve --graph /abs/path/to/graph.json
+```
+
+## Honest benchmarking
+
+"Tokens saved" is a vanity metric — a tool that returns nothing saves 100%.
+Graphex reports **recall@budget** alongside it: how much of the relevant set the
+budgeted subgraph actually captures. High savings with low recall means
+under-retrieval, and the benchmark makes that trade-off visible.
+
+## Development
+
+```bash
+uv sync
+uv run pytest          # test suite
+uv run ruff check .    # lint
+uv run black .         # format
+```
+
+## License
+
+MIT © Alfonso Mayoral

apexgraph-0.1.0/RELEASING.md

@@ -0,0 +1,47 @@
+# Releasing Graphex to PyPI
+
+Graphex publishes via **Trusted Publishing** (OIDC) from GitHub Actions — no API
+token is ever stored. The release workflow lives in
+[`.github/workflows/publish.yml`](.github/workflows/publish.yml) and runs when a
+GitHub Release is published. The PyPI distribution name is **`apexgraph`** (the
+command and import name remain `graphex`).
+
+## One-time setup (per maintainer)
+
+1. **Create a PyPI account** at <https://pypi.org/account/register/> and enable
+   two-factor authentication (required).
+2. **Add a pending trusted publisher** at
+   <https://pypi.org/manage/account/publishing/> with:
+   - PyPI Project Name: `apexgraph`
+   - Owner: `alfonsomayoral`
+   - Repository name: `graphex`
+   - Workflow name: `publish.yml`
+   - Environment name: `pypi`
+
+   This claims the project name and links it to this repo's workflow. (Optionally
+   do the same on <https://test.pypi.org> first for a dry run.)
+
+## Cutting a release
+
+1. Bump `version` in `pyproject.toml` and move the `CHANGELOG.md` entries from
+   `[Unreleased]` under the new version heading. Commit and push.
+2. Tag and create the GitHub Release:
+   ```bash
+   git tag v0.1.0
+   git push origin v0.1.0
+   gh release create v0.1.0 --title "v0.1.0" --notes-file <(sed -n '/## \[0.1.0\]/,/## \[/p' CHANGELOG.md)
+   ```
+   (Or create the release from the GitHub UI.)
+3. Publishing the release triggers `publish.yml`: it builds the sdist + wheel,
+   runs `twine check`, and uploads to PyPI via OIDC. Watch it with
+   `gh run watch`.
+
+## Verify
+
+```bash
+uv tool install apexgraph
+graphex --version
+```
+
+A version, once published, cannot be replaced — only yanked. Validate locally
+first: `uv build && uvx twine check dist/*`.