agentforge-graph 0.3.2__tar.gz → 0.4.0__tar.gz

{agentforge_graph-0.3.2 → agentforge_graph-0.4.0}/.claude/CLAUDE.md

@@ -35,10 +35,17 @@
   `agentforge add module` does **not** work here (it shells out to
   `pip`, absent in uv venvs) — declare modules in `pyproject.toml`
   and `uv sync` instead.
-- **Two config files, on purpose.** `agentforge.yaml` is framework
-  config (strict validator — no unknown keys). `ckg.yaml` is this
-  agent's own engine config (store/ingest/chunking/embed/retrieve/
-  serve), read by the `agentforge_graph` package.
+- **One config file: `agentforge.yaml`.** Framework keys at the top
+  level; this agent's engine config (store/ingest/chunking/embed/
+  retrieve/serve/…) under the framework's `app:` passthrough
+  (agentforge-py ≥0.3). The engine reads `app:` with **plain pyyaml,
+  no `agentforge` import** (ADR-0001) — `config.resolve_config()`
+  discovers `agentforge.yaml` (with `app:`) or a standalone `ckg.yaml`,
+  and `_read_block` reads from `app.<key>` or top-level. A standalone
+  `ckg.yaml` is still supported (framework-free use). *(History: we
+  used a separate `ckg.yaml` because 0.2.4's strict validator rejected
+  app keys — fixed upstream in 0.3.x via `app:`; see
+  `docs/framework/upgrade-0.2.4-to-0.3.x.md`.)*
 - **Framework learnings go in `docs/framework/`** — local-only,
   git-ignored. Log any framework bug/hack/workaround/missing-feature
   there as you hit it (baseline: agentforge-py 0.2.4).

agentforge_graph-0.4.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,41 @@
+---
+name: Bug report
+about: Something the engine, CLI, or MCP server got wrong
+title: "[bug] "
+labels: bug
+---
+
+## What happened
+
+A clear description of the bug, and what you expected instead.
+
+## Reproduce
+
+Steps / the smallest repo or snippet that triggers it:
+
+```bash
+ckg index .
+ckg ...        # the command that misbehaves
+```
+
+If it's an extraction/resolution issue, a **minimal source file** that reproduces
+it helps a lot.
+
+## Environment
+
+- agentforge-graph version: `ckg --version` (or `pip show agentforge-graph`)
+- Python version:
+- OS:
+- Store backend (if not default): `kuzu`/`neo4j`/`pgvector`/`surrealdb`/…
+- Language(s) involved (if extraction): Python / TS / Go / …
+- Provider (if embed/enrich): `bedrock`/`openai`/`anthropic`/`fake`/…
+
+## Logs / output
+
+```
+paste the relevant output, error, or stack trace
+```
+
+## Notes
+
+Anything else — was it incremental vs full index, a specific framework pack, etc.

agentforge_graph-0.4.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Security vulnerability
+    url: https://github.com/Scaffoldic/agentforge-graph/security/advisories/new
+    about: Please report security issues privately — see SECURITY.md, not a public issue.
+  - name: Question / usage help
+    url: https://github.com/Scaffoldic/agentforge-graph/discussions
+    about: Ask how to use the engine, MCP tools, or a provider/backend.

agentforge_graph-0.4.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,27 @@
+---
+name: Feature request
+about: Propose a capability, a language/framework pack, or a backend
+title: "[feat] "
+labels: enhancement
+---
+
+## The problem / use case
+
+What are you trying to do that the engine doesn't support today? Who's it for —
+a human, or a coding agent consuming the graph?
+
+## Proposed solution
+
+What you'd like to see. If it's a new **language pack**, **framework pack**,
+**storage backend**, or **model provider**, note the target (e.g. "Rails routes",
+"SurrealDB", "Gemini embeddings") — these ride documented extension points (see
+[`CONTRIBUTING.md`](../../CONTRIBUTING.md) §5).
+
+## Alternatives considered
+
+Other approaches, or how you work around it now.
+
+## Scope
+
+- [ ] I'd be willing to help implement this
+- [ ] This needs a design discussion first

agentforge_graph-0.4.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,22 @@
+<!-- Thanks for contributing! Keep PRs to one feature/fix = one branch = one PR. -->
+
+## What & why
+
+What this changes and the motivation. Link the issue / feature spec / ADR if any
+(e.g. `Closes #123`, `feat-0NN`, `ENH-0NN`).
+
+## How
+
+A short note on the approach — and, if it touches an extension point (a language
+/ framework pack, storage backend, model provider, MCP tool, enricher), how it
+rides the existing rails.
+
+## Checklist
+
+- [ ] `uv run ruff format --check . && uv run ruff check . && uv run mypy src` clean
+- [ ] `uv run pytest` green (≥90% coverage)
+- [ ] New behavior has tests (golden + end-to-end where it applies; new backends
+      pass the conformance suite)
+- [ ] Docs updated (README / a `docs/guides/` page / CHANGELOG `[Unreleased]`)
+- [ ] No new `agentforge` import inside the deterministic engine (ADR-0001)
+- [ ] Conventional-commit title (`feat:` / `fix:` / `docs:` / `chore:` / …)

{agentforge_graph-0.3.2 → agentforge_graph-0.4.0}/.github/workflows/ci.yml

@@ -55,7 +55,7 @@ jobs:
   # no secrets), so Neo4j/pgvector are verified in CI — not just locally. Separate
   # job so a DB hiccup can't fail the core gate; both must pass to merge.
   server-backends:
-    name: server backends (neo4j + pgvector conformance)
+    name: server backends (neo4j + pgvector + surrealdb conformance)
     runs-on: ubuntu-latest
     services:
       neo4j:
@@ -81,14 +81,26 @@ jobs:
         uses: astral-sh/setup-uv@v6
         with:
           enable-cache: true
-      - name: Sync dependencies (+ neo4j + pgvector extras)
-        run: uv sync --extra dev --extra engine --extra neo4j --extra pgvector
+      - name: Sync dependencies (+ neo4j + pgvector + surrealdb extras)
+        run: uv sync --extra dev --extra engine --extra neo4j --extra pgvector --extra surrealdb
+      # SurrealDB needs its `start` command + args, which a `services:` container
+      # can't express — so run it directly and wait for the /health endpoint.
+      - name: Start SurrealDB
+        run: |
+          docker run -d --name surreal -p 8000:8000 \
+            surrealdb/surrealdb:latest start --user root --pass root memory
+          for i in $(seq 1 30); do
+            curl -sf http://localhost:8000/health && break
+            sleep 1
+          done
       - name: Server-backend conformance
         env:
           CKG_NEO4J_URI: bolt://localhost:7687
           CKG_NEO4J_PASSWORD: ckgckgckg
           CKG_PGVECTOR_DSN: postgresql://postgres:ckg@localhost:5432/ckg
+          CKG_SURREALDB_URL: ws://localhost:8000/rpc
         run: >-
           uv run pytest --no-cov
           tests/store/test_neo4j_conformance.py
           tests/store/test_pgvector_conformance.py
+          tests/store/test_surreal_conformance.py

{agentforge_graph-0.3.2 → agentforge_graph-0.4.0}/CHANGELOG.md

@@ -8,6 +8,122 @@ on a schema mismatch is **rebuild** (ADR-0006).
 
 ## [Unreleased]
 
+## [0.4.0] — 2026-06-20
+
+### Changed
+
+- **Consolidated engine config into `agentforge.yaml` (`app:` section).**
+  agentforge-py 0.3.x added a sanctioned `app:` passthrough to its strict config
+  file — the fix for the workaround that forced a separate `ckg.yaml`. The engine
+  now reads its config from `app:` (or a top-level standalone `ckg.yaml`, still
+  supported) using **plain pyyaml, no `agentforge` import** (ADR-0001), and
+  **auto-discovers** the file in the repo (previously only `--config` was read).
+  One config file. `config.resolve_config()` + `app:`-aware `_read_block`.
+- **HTTP MCP auth now rides the framework's `from_http(middleware=)` seam**
+  (agentforge-mcp 0.3.x), replacing the `CkgHttpRunner` that reimplemented ~60
+  lines of HTTP-serve internals to add a bearer gate. `BearerAuthMiddleware`
+  unchanged; verified live (401 / pass-through). (ENH-005.)
+- **Upgraded the AgentForge framework pin to `>=0.3,<0.4`** (from the validated
+  0.2.x line). Re-validated: the full gate (666 tests / 95%, ruff + mypy) and an
+  MCP server-construction smoke pass on `agentforge-py` 0.3.1 — the `Tool` /
+  `BudgetPolicy` / `MCPServer` surfaces are unchanged.
+
+### Added
+
+- **Bedrock-native reranker + measurement campaign (ENH-013).** A torch-free
+  `BedrockRerankScorer` (AWS Bedrock Rerank API — Cohere Rerank 3.5 / Amazon
+  Rerank) behind the existing `CrossScorer` seam, selected via
+  `rerank_model: bedrock:cohere.rerank-v3-5:0` — reuses the AWS creds the embedder
+  already uses, no `rerank`/torch extra. A two-corpus campaign (harness
+  `scripts/rerank_eval.py`, [results](docs/validation/rerank/results.md)) found
+  the cross-encoder is an **ordering** win (MRR +10–16% at blend weight 0.3) over
+  an already-recall-saturated base, costing ~540 ms/query — so rerank **stays
+  opt-in**, with the Bedrock config @ `w=0.3` documented as the recommended
+  precision setting. New `retrieve.rerank_region` config. A **rigorous follow-up
+  benchmark** (`scripts/rerank_benchmark.py`, objective docstring→code labels,
+  388 queries / 4 OSS repos) confirms base retrieval MRR 0.95 / recall@1 0.92 and
+  a statistically-significant rerank lift (ΔMRR +0.019, p<0.001) — surfaced in the
+  README's "Retrieval quality (measured)" section.
+
+- **Four new framework packs — Go / C# / PHP / Ruby routes (ENH-012).** Framework
+  awareness now spans **11 packs** across six languages. Each rides a small new
+  `_<lang>_ast` helper and is conservative (ADR-0004); detection uses import
+  markers since these languages' deps live outside the scanned manifests.
+  - **Gin** (Go) — `r.GET("/x", handler)` method calls → `Route` + `HANDLED_BY`
+    to the Go function (mirrors Express).
+  - **ASP.NET** (C#) — `[HttpGet("/x")]` attributes on controllers → `Route` +
+    `HANDLED_BY` to `Class#method`; `[Route]` base path + `[controller]` token
+    (mirrors Spring).
+  - **Laravel** (PHP) — `Route::get('/x', [C::class, 'm'])` / `'C@m'` / invokable.
+  - **Rails** (Ruby) — `routes.rb` explicit `get '/x' => 'c#a'` / `to:` / `root`.
+
+  Laravel and Rails name their handler in another file, so a new **generic
+  cross-file route-handler grounding** pass-2 step (`frameworks/cross_file.py`)
+  resolves the controller reference to the real `Class#method` symbol anywhere in
+  the repo (unique-match), emitting `HANDLED_BY` — globally idempotent, surfaced
+  as `IndexReport.route_handlers_grounded`. ORM models (EF Core / Eloquent /
+  ActiveRecord), the ASP.NET minimal API, and the Rails resourceful DSL are
+  follow-ups.
+
+- **Cross-file framework resolution — route prefixes + DI grounding (ENH-011).**
+  A globally-idempotent pass-2 (`frameworks/cross_file.py`) stitches the
+  compose-points real apps split across files, reading only the persisted graph
+  (`IMPORTS` edges + node attrs), unique-match-only (ADR-0004):
+  - `app.include_router(payments.router, prefix="/api")` composes `/api` onto the
+    included router's routes. The base `path` is preserved; the composed URL is a
+    new `path_pattern` attr (`RouteInfo.path_pattern`, shown by `ckg routes` and
+    returned by the `ckg_routes` MCP tool). New `RouteMount` node kind.
+  - `Depends(get_db)` grounds the provider *name* to the `get_db` function symbol
+    in its module via a new `PROVIDED_BY` edge (+ `Service.provider_symbol`).
+
+  Ships for **FastAPI**; Flask / Express / Django reuse the same framework-
+  agnostic pass-2 (per-pack pass-1 capture pending). New `RouteMount` /
+  `PROVIDED_BY` kinds are additive and migration-free (the stores key edges/nodes
+  by a `kind` string column). `IndexReport.route_prefixes_composed` /
+  `di_providers_grounded`; `incremental == full` preserved. New runbook:
+  `docs/guides/04-cross-file-framework-resolution.md`.
+
+- **`CITATION.cff`** — GitHub "Cite this repository" metadata.
+
+- **Consumer feature guides + a runnable example.** New `docs/guides/` for the
+  headline features — framework extraction (routes/models/services), architecture
+  decisions, temporal/history, enrichment, and an index→query walkthrough — plus
+  `examples/fastapi-shop/`, a tiny FastAPI+SQLAlchemy app you can index in one
+  command to see routes/models/services (output verified against the CLI).
+
+- **Project metadata + community health.** `[project.urls]` (Homepage,
+  Repository, Changelog, Issues, Documentation) so the PyPI page links out;
+  `SECURITY.md`, `CODE_OF_CONDUCT.md`, GitHub issue + PR templates; README doc
+  links made absolute so they resolve on the PyPI project page.
+
+- **SurrealDB storage backend — graph + vectors in one (ENH-010).** A first-party
+  `surrealdb` driver for *both* `store.graph.driver` and `store.vectors.driver`,
+  so one multi-model server is a complete backend (`pip install
+  agentforge-graph[surrealdb]`). It passes the same `GraphStoreConformance` /
+  `VectorStoreConformance` suites as Kuzu/Neo4j/LanceDB/pgvector — verified
+  against a live SurrealDB in the `server-backends` CI job. Nodes/edges are
+  document tables on the shared open schema (hash-keyed records, the symbol id in
+  a `key` field); vector search is brute-force cosine in `[0, 1]`. This makes the
+  "day-one, plug in a different DB" promise provable end-to-end against an
+  independent third backend.
+
+## [0.3.3] - 2026-06-19
+
+Leaner base install + the refreshed README on PyPI.
+
+### Changed
+
+- **Dropped the unused `fastembed` dependency** from the base install (and the
+  heavy `onnxruntime` wheel it pulled). It was a leftover from the original
+  feat-005 plan to default to local embeddings; the shipped embedders are
+  `bedrock` / `openai` / `fake`, none of which import it. Removing it keeps the
+  promise true: the base install carries only what the engine actually uses, and
+  every model/DB provider is opt-in. (No local-embeddings driver existed, so
+  nothing is lost; a `fastembed` driver behind a `[local]` extra can be added as
+  a deliberate feature later.)
+- README refreshed (out-of-the-box overview, quick start, demo) now renders on
+  the PyPI project page.
+
 ## [0.3.2] - 2026-06-19
 
 Packaging fix — base-install completeness (caught on a TestPyPI dry run).
@@ -412,9 +528,11 @@ questions over the tools, unattended.
   on a real repo (fixed BUG-008, a default-config `ckg query` break); and parse
   coverage holds at scale (`django`, 2922 files, ~100%, no crash).
 
-[Unreleased]: https://github.com/Scaffoldic/agentforge-grpah/compare/v0.3.2...HEAD
-[0.3.2]: https://github.com/Scaffoldic/agentforge-grpah/compare/v0.3.1...v0.3.2
-[0.3.1]: https://github.com/Scaffoldic/agentforge-grpah/compare/v0.3.0...v0.3.1
-[0.3.0]: https://github.com/Scaffoldic/agentforge-grpah/compare/v0.2.0...v0.3.0
-[0.2.0]: https://github.com/Scaffoldic/agentforge-grpah/compare/v0.1.0...v0.2.0
-[0.1.0]: https://github.com/Scaffoldic/agentforge-grpah/releases/tag/v0.1.0
+[Unreleased]: https://github.com/Scaffoldic/agentforge-graph/compare/v0.4.0...HEAD
+[0.4.0]: https://github.com/Scaffoldic/agentforge-graph/compare/v0.3.3...v0.4.0
+[0.3.3]: https://github.com/Scaffoldic/agentforge-graph/compare/v0.3.2...v0.3.3
+[0.3.2]: https://github.com/Scaffoldic/agentforge-graph/compare/v0.3.1...v0.3.2
+[0.3.1]: https://github.com/Scaffoldic/agentforge-graph/compare/v0.3.0...v0.3.1
+[0.3.0]: https://github.com/Scaffoldic/agentforge-graph/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/Scaffoldic/agentforge-graph/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/Scaffoldic/agentforge-graph/releases/tag/v0.1.0

agentforge_graph-0.4.0/CITATION.cff

@@ -0,0 +1,26 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it as below."
+title: agentforge-graph
+abstract: >-
+  A Code Knowledge Graph (CKG) engine and agent toolset: it turns a repository
+  into a typed, provenance-tracked graph — symbols, calls, imports, API routes,
+  ORM models, dependency injection, architecture decisions, git history, and LLM
+  summaries — and serves that knowledge to coding agents over MCP or as an
+  AgentForge toolset.
+type: software
+authors:
+  - family-names: Joshi
+    given-names: Khemchand
+    email: engg.kjoshi@gmail.com
+repository-code: "https://github.com/Scaffoldic/agentforge-graph"
+url: "https://pypi.org/project/agentforge-graph/"
+license: Apache-2.0
+keywords:
+  - code-knowledge-graph
+  - knowledge-graph
+  - code-search
+  - static-analysis
+  - tree-sitter
+  - mcp
+  - ai-agents
+  - retrieval-augmented-generation

agentforge_graph-0.4.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,62 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes
+- Focusing on what is best for the overall community
+
+Examples of unacceptable behavior:
+
+- The use of sexualized language or imagery, and sexual attention or advances
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information without explicit permission
+- Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards and
+will take appropriate and fair corrective action in response to any behavior
+they deem inappropriate, threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+**engg.kjoshi@gmail.com**. All complaints will be reviewed and investigated
+promptly and fairly. Community leaders are obligated to respect the privacy and
+security of the reporter of any incident.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+<https://www.contributor-covenant.org/version/2/1/code_of_conduct.html>.
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see the FAQ at
+<https://www.contributor-covenant.org/faq>.

{agentforge_graph-0.3.2 → agentforge_graph-0.4.0}/CONTRIBUTING.md

@@ -11,7 +11,7 @@ first for the system map; this doc is the *how to work on it*.
 Tooling is **`uv`, not pip**.
 
 ```bash
-uv sync --extra engine --extra bedrock     # engine + native wheels + boto3
+uv sync --extra dev --extra bedrock        # engine ships in base; dev = test/lint toolchain
 cp .env.example .env                        # optional: AWS creds for live model tests
 ```
 
@@ -77,10 +77,22 @@ the framework, you're in the wrong layer.
 
 ### Add a framework pack (routes/ORM/DI)
 1. `src/agentforge_graph/frameworks/packs/<name>/`: a `FrameworkPack` with
-   `detect()` (dep manifest + import markers) and `extract()` emitting framework
-   nodes/edges. Mirror `packs/fastapi/`.
-2. Register in `frameworks/registry.py`. Facts are **merged into the
-   `FileSubgraph`** so they ride incremental indexing automatically.
+   `dep_names`/`import_markers` (detection) and `extract()` emitting framework
+   nodes/edges. Pick the closest reference pack: **routes** → `fastapi`/`flask`
+   (Python), `express` (JS/TS), `spring`/`nestjs` (decorator style); **ORM** →
+   `sqlalchemy`/`django`.
+2. **Reuse the shared rails** — don't re-parse from scratch:
+   `packs/_python_ast.py` (Python AST helpers: `iter_class_assignments`,
+   `enclosing_class`, `member_descriptor`, …), `packs/_js_ast.py` (JS/TS), and
+   `frameworks/orm.py` (`ModelIndex` + `relations_to_edges` for `RELATES_TO`).
+3. A pack spanning sibling languages (e.g. JS *and* TS) overrides the
+   `FrameworkPack.slugs` property and builds ids with the file's own slug.
+4. Cross-file stitching (FK/relationship targets, route prefixes) goes in the
+   pass-2 `resolve()` hook — see `sqlalchemy`/`django`. It's globally idempotent.
+5. Register in `frameworks/registry.py`. Pass-1 facts are **merged into the
+   `FileSubgraph`** so they ride incremental indexing automatically; add a golden
+   pack test + an end-to-end test asserting the edge lands on the real symbol node
+   (mirror `tests/frameworks/test_<name>_{pack,integration}.py`).
 
 ### Add a storage backend (Neo4j, SurrealDB, pgvector, …)
 1. Implement `GraphStore` and/or `VectorStore` (`core/contracts.py`).
@@ -95,7 +107,7 @@ core change needed. **First-party built-ins already ship** for embeddings
 (`bedrock`, `openai`, `fake`) and enrichment (`bedrock`, `anthropic`, `scripted`);
 `embed.base_url` makes the `openai` driver work against any OpenAI-compatible
 local server. See the full guide:
-[`docs/guides/model-providers.md`](docs/guides/model-providers.md).
+[`docs/guides/08-model-providers.md`](docs/guides/08-model-providers.md).
 
 To add a **new** one out-of-tree:
 1. Implement `Embedder` (`embed/base.py`) and/or `PatternJudge` / `Summarizer`

{agentforge_graph-0.3.2 → agentforge_graph-0.4.0}/NOTICE

@@ -2,7 +2,7 @@ agentforge-graph
 Copyright 2026 The agentforge-graph Authors
 
 This product includes software developed at the agentforge-graph project
-(https://github.com/Scaffoldic/agentforge-grpah).
+(https://github.com/Scaffoldic/agentforge-graph).
 
 Built on AgentForge (https://github.com/Scaffoldic/agentforge-py),
 Copyright 2026 The AgentForge Authors, licensed under Apache-2.0.