ambitgraph 0.0.1__tar.gz → 0.2.0__tar.gz

ambitgraph-0.2.0/LICENSE

@@ -0,0 +1,25 @@
+AmbitGraph — Proprietary Software License
+Copyright (c) 2026 AmbitGraph. All rights reserved.
+
+This software and its source code (the "Software") are proprietary and
+confidential. The Software is licensed, not sold.
+
+1. GRANT. No license or right to use, copy, modify, merge, publish,
+   distribute, sublicense, or sell copies of the Software is granted except
+   under a separate written agreement with the copyright holder. Absent such
+   an agreement, no rights are conferred by the availability of this package.
+
+2. RESTRICTIONS. You may not reverse engineer, decompile, or disassemble the
+   Software, nor remove or alter any proprietary notice, except to the extent
+   such restriction is prohibited by applicable law.
+
+3. NO WARRANTY. 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.
+
+4. LIMITATION OF LIABILITY. 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.
+
+For licensing inquiries, contact the copyright holder.

ambitgraph-0.2.0/MANIFEST.in

@@ -0,0 +1,25 @@
+# The source distribution (.tar.gz on PyPI) ships the packages, the README,
+# pyproject and the LICENSE only. Everything below is development-only.
+
+prune tests
+prune tools
+prune docs
+prune build
+prune dist
+
+# Internal-only packages -- also excluded from the wheel via the packages list.
+prune ambit_contracts
+prune ambit_telegraph
+
+# Development evidence directories (screenshots, transcripts, review notes).
+# Both spellings: the dated evidence-* folders and the single evidence/ folder they moved into.
+prune evidence-*
+prune evidence
+
+# Internal process documents.
+exclude AGENTS.md
+exclude CHANGELOG.md
+exclude DATA-FLOW.md
+
+global-exclude *.pyc
+global-exclude __pycache__/*

ambitgraph-0.2.0/PKG-INFO

@@ -0,0 +1,83 @@
+Metadata-Version: 2.4
+Name: ambitgraph
+Version: 0.2.0
+Summary: Read-only codebase scan: reusable units, families, roles, ownership candidates, duplication.
+Author: AmbitGraph
+License: Proprietary
+Keywords: codebase,scan,audit,duplication,refactoring,reuse
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyyaml>=6
+Provides-Extra: ui
+Requires-Dist: playwright>=1.40; extra == "ui"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: mcp<2,>=1.2; extra == "dev"
+Requires-Dist: jsonschema>=4; extra == "dev"
+Provides-Extra: gate
+Requires-Dist: mcp<2,>=1.2; extra == "gate"
+Dynamic: license-file
+
+# AmbitGraph
+
+**You don't understand your own product!**
+
+**You can't keep up with the amount of code!**
+
+One command, and you do. Deterministic. No tokens.
+
+AmbitGraph draws your whole repo as a visual interactive map & library and gives them to you. It needs Python on your machine, never in your project. Free, offline, no account, no API key.
+
+Python 3.11 or newer.
+
+## Install and run
+
+```
+pip install ambitgraph
+python -m ambitgraph map <folder>
+```
+
+`ambit map <folder>` does the same when your Python scripts folder is on your PATH.
+
+The command gives your terminal back and the map keeps serving. Stop it with `python -m ambitgraph map <folder> --stop`.
+
+Your codebase is displayed in your browser as local webpages.
+
+It does not make any changes to your codebase.
+
+## A GRAPH
+
+Modules, Classes, Imports, Calls, DB Tables, anything in your code mapped on its connections.
+
+## An Indexed and Searchable LIBRARY
+
+Understand what you have, what it does, and what it means.
+
+Understand your own codebase in a way you never have. Simple, visual, and if you want more you can ask your agent what the hell it just did. A vibe coder can finally see how their code works. A senior can see at a glance when something has got too complicated.
+
+## Your machine
+
+The map is served to your own machine, stays on your machine. It and your code belong to you
+
+## No AI
+
+No AI is required. The map is plain reading of your code.
+
+No model runs, no tokens burn, no key exists. If you want more than the map, your own assistant can work on top of it, on your own subscription, with whatever model you already pay for. Optional, always, and the map is finished without it.
+
+## In this version
+
+Search finds functions and tables by name. The Library groups every file the
+scan read into families. The Graph draws one file and everything one hop from
+it, and every row in the Library opens it.
+
+Search does not find routes or file names. Drawn connections do not carry
+their meaning beside them. There are no written explanation pages.

ambitgraph-0.2.0/README.md

@@ -0,0 +1,55 @@
+# AmbitGraph
+
+**You don't understand your own product!**
+
+**You can't keep up with the amount of code!**
+
+One command, and you do. Deterministic. No tokens.
+
+AmbitGraph draws your whole repo as a visual interactive map & library and gives them to you. It needs Python on your machine, never in your project. Free, offline, no account, no API key.
+
+Python 3.11 or newer.
+
+## Install and run
+
+```
+pip install ambitgraph
+python -m ambitgraph map <folder>
+```
+
+`ambit map <folder>` does the same when your Python scripts folder is on your PATH.
+
+The command gives your terminal back and the map keeps serving. Stop it with `python -m ambitgraph map <folder> --stop`.
+
+Your codebase is displayed in your browser as local webpages.
+
+It does not make any changes to your codebase.
+
+## A GRAPH
+
+Modules, Classes, Imports, Calls, DB Tables, anything in your code mapped on its connections.
+
+## An Indexed and Searchable LIBRARY
+
+Understand what you have, what it does, and what it means.
+
+Understand your own codebase in a way you never have. Simple, visual, and if you want more you can ask your agent what the hell it just did. A vibe coder can finally see how their code works. A senior can see at a glance when something has got too complicated.
+
+## Your machine
+
+The map is served to your own machine, stays on your machine. It and your code belong to you
+
+## No AI
+
+No AI is required. The map is plain reading of your code.
+
+No model runs, no tokens burn, no key exists. If you want more than the map, your own assistant can work on top of it, on your own subscription, with whatever model you already pay for. Optional, always, and the map is finished without it.
+
+## In this version
+
+Search finds functions and tables by name. The Library groups every file the
+scan read into families. The Graph draws one file and everything one hop from
+it, and every row in the Library opens it.
+
+Search does not find routes or file names. Drawn connections do not carry
+their meaning beside them. There are no written explanation pages.

ambitgraph-0.2.0/ambit_map/__init__.py

@@ -0,0 +1,7 @@
+"""The AmbitGraph product package — the shipped two-tab map (Graph + Library).
+
+Consumes the engine's artifact files (results/symbols.json, results/edges.json)
+and drives the engine only as a subprocess (ambit scan). Imports NO company
+code — not ambitgraph, not ambit_telegraph, not ambit_contracts — and the wall
+is mechanical: tests/test_import_boundaries.py. The engine reaches this package
+only through a sanctioned lazy seam in cli.py (lands with a later wave)."""

ambitgraph-0.2.0/ambit_map/__main__.py

@@ -0,0 +1,6 @@
+"""`python -m ambit_map <repo>` -- the package's command-line entry point."""
+import sys
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

ambitgraph-0.2.0/ambit_map/ambit-map-enrich.md

@@ -0,0 +1,54 @@
+# Prose judgment — the optional assistant pass
+
+AmbitGraph's map is complete without any AI. Everything the Library and the Graph show is
+measured: symbols and edges come from the engine's deterministic scan of your files, with
+no model and no network.
+
+What a scan cannot tell you is what a unit is **for** — the sentence a human would write.
+That is *judgment*, not measurement, and this product never invents it. If you want it, you
+run it yourself, with your own assistant, on your own machine, and the map keeps the two
+vocabularies visibly apart: a judged note always renders inside the collapsed
+"Judged by your assistant" block and always carries the `judged` chip. No judged number is
+ever added to a measured number.
+
+## What you need
+
+- A completed scan. Its output directory is written as `<run-dir>` below — it is the
+  directory `ambit map` printed when it finished, the one holding `results/`,
+  `inventory.json` and `pending/`.
+- An assistant that can run a workflow script and write a JSON file. Today's supported
+  path is Claude Code; any capable assistant can satisfy the same contract, because your
+  artifacts are plain JSON on your disk.
+
+## The loop
+
+One harvest advances **one stage only**. The stages run in order: `extract`, then
+`cluster`, then `roles` — and `vocab` or `ownership` when your scan configures them.
+The draft map does not exist until the last stage has run.
+
+1. Open `<run-dir>/pending/` and pick the next `*.workflow.js` script.
+2. Run that script in an assistant session.
+3. Harvest what it wrote:
+
+       ambit harvest <stage> --scan "<run-dir>" --journal <transcriptDir>/journal.jsonl
+
+   `<stage>` is the script's own stage name. `<transcriptDir>/journal.jsonl` is the
+   journal your assistant session wrote; it is not a path this map can know ahead of time.
+   Quote `<run-dir>` — an unquoted path containing a space splits into two arguments.
+4. Re-run the exact `ambit scan` command that produced this run, pointed at this same
+   output directory, from your terminal. This page cannot resume a run; it can only start
+   a fresh one.
+5. Repeat 1-4 until `pending/` is empty and the draft map is written.
+
+Only then does reloading the Library show judged notes.
+
+## What you get, and what you do not
+
+You get, per unit the assistant could pin to a file this scan read: what it is, a role
+with a confidence, a parent, and a structural family name. You do not get any change to a
+measured number, and you do not get a claim about a file the scan never read — a judged
+note that cannot be joined to a real unit is listed separately, as unjoined, and counted
+separately.
+
+If the draft cannot be read at all, the map says so by name and shows nothing else from
+that plane. Fail-closed is the rule: a plane that did not load never renders as a zero.

ambitgraph-0.2.0/ambit_map/ambit-mapllm-contract.md

@@ -0,0 +1,246 @@
+# The mapllm ingestion contract — the shapes your assistant's files must carry
+
+ambit-map-enrich.md already states the law this document generalises: "Today's supported path
+is Claude Code; ANY capable assistant can satisfy the same contract, because your artifacts are
+plain JSON on your disk." That clause is the whole idea — this document turns it into an actual
+schema, so an assistant that is not Claude Code (or a hand-written script) can write a
+conforming file directly and be read exactly the same way.
+
+The law stated plainly, again, because it never changes: everything in this document produces
+*judgment*, not measurement. Nothing here is read, parsed, or counted by the deterministic scan.
+The map keeps the two vocabularies visibly apart — a judged note always renders inside the
+collapsed "Judged by your assistant" block, always carries the `judged` chip, and no judged
+number is ever added to a measured number. A plane built from this contract DECORATES the map;
+it never becomes authoritative over anything the scan itself measured.
+
+## Two ways to produce these files
+
+1. **The workflow-script loop** (ambit-map-enrich.md's own loop): run the script `pending/
+   <stage>.workflow.js` in your assistant session, then reduce its journal with `ambit harvest
+   <stage> --scan <run-dir> --journal <journal>`. The harvester folds one or many analysts'
+   records into the single `results/<stage>.json` file this document specifies below —
+   deduplicating, validating against the enumerations each stage declares, and degrading a
+   partial or malformed record rather than discarding the run's other work.
+2. **The direct-results door**: write `results/<stage>.json` yourself, in the exact shape this
+   document names for that stage, and skip the workflow-script loop entirely. mapllm's conductor
+   accepts a directly-written results file exactly as it accepts one `ambit harvest` produced —
+   the file on disk is the whole contract; nothing tracks how it got there.
+
+Either way, a stage advances only once its `results/<stage>.json` exists; re-running the same
+scan command against the same output directory picks up from there.
+
+## The stage results files
+
+Every stage below is optional except `extract`, `cluster`, and `roles` — `vocab` and `ownership`
+run only when the scan config declares a vocabulary or ownership areas; `suggest` runs only when
+the draft has ambiguous units queued for a human's ruling.
+
+### The `extract` stage — `results/<stage>.json`
+
+```json
+{
+  "units": [
+    {
+      "anchor": "helpers.py::shout",
+      "file": "helpers.py",
+      "hook": "shout",
+      "granularity": "component",
+      "role0": "structure_owner",
+      "hint": "a small formatting helper",
+      "ev": "imported and called by main.py",
+      "similar_to": []
+    }
+  ],
+  "uncovered": []
+}
+```
+
+`granularity` is one of `module` (whole-file scope), `component` (a cohesive unit inside a
+file), or `fragment` (a small piece that composes into larger units) — or the empty string when
+unknown. `role0` is one of `structure_owner` (this code DEFINES the shared structure), `filler`
+(this code USES a structure defined elsewhere), or `unclear`. `anchor` is `file::hook` — the
+stable pair every other stage's file joins on. `uncovered` names manifest paths no unit was
+reported for; it is informational, never a refusal.
+
+### The `cluster` stage — `results/<stage>.json`
+
+```json
+{
+  "families": [
+    {"name": "widgets", "members": ["helpers.py::shout", "main.py::run_report"]}
+  ]
+}
+```
+
+Every anchor from `extract.json` appears in exactly one family's `members`. A unit that fits no
+real family belongs in one named `singletons`, never omitted. An optional `warnings` array
+(strings) may accompany a run that had to degrade rather than discard part of the reduction.
+
+### The `roles` stage — `results/<stage>.json`
+
+```json
+{
+  "roles": {
+    "helpers.py::shout": {"role": "structure_owner", "parent": "", "confidence": "high",
+                              "family": "widgets"},
+    "main.py::run_report": {"role": "filler", "parent": "helpers.py::shout",
+                                "confidence": "high", "family": "widgets"}
+  }
+}
+```
+
+Keyed by anchor. `role` is `structure_owner` | `filler` | `unclear`. `parent` is the anchor a
+`filler` delegates to, written verbatim as anchor text (empty when there is none). `confidence`
+is `high` | `medium` | `low`.
+
+### The `vocab` and `ownership` stages — `results/<stage>.json`
+
+Written only when the scan config declares `vocabulary` (for `vocab.json`) or `areas` (for
+`ownership.json`) — each a name-to-definition mapping the config itself states.
+
+```json
+{
+  "assignments": {
+    "helpers.py::shout": {"family": "widget", "confidence": "high"}
+  },
+  "missing": [],
+  "invalid": []
+}
+```
+
+`vocab.json` uses the key `family`; `ownership.json` uses `area` in its place. The value is one
+of the config's own declared names, or `"none"` (vocab) / `"unknown"` (ownership) — any other
+value is rejected into `invalid`, never silently accepted. `missing` names anchors this file
+assigns nothing to.
+
+### The `suggest` stage — `results/<stage>.json`
+
+```json
+{
+  "suggestions": {
+    "helpers.py::shout": {"ruling": "keep", "rationale": "a tiny standalone helper, used once."}
+  },
+  "missing": [],
+  "invalid": []
+}
+```
+
+`ruling` is `keep` or `wrong` only — never `defer`; deciding later is the human reviewer's own
+authority, not a machine suggestion. A missing or empty `rationale` is rejected into `invalid`.
+
+## The draft's own version and producer record
+
+Once every required stage's results file exists, the scan assembles `map/draft_map.json` — the
+one artifact this whole contract exists to make honest. It carries two fields no prior draft
+ever had:
+
+```json
+{
+  "v": 1,
+  "producer": {
+    "recorded_at": "2026-08-30T00:00:00Z",
+    "config_hash": "sha1:0123456789ab",
+    "engine_fingerprint": "…64 hex chars…"
+  }
+}
+```
+
+`v` is the draft's schema version, checked on load — see "Fail-closed" below for exactly what
+counts as a match. `producer.tool`, when present, names in plain free text what produced the
+stage results this draft was assembled from. Nothing in this contract names a producer for you:
+a `results/<stage>.json` header carries no `producer.tool` unless something put one there — the
+workflow-script loop does not name itself automatically. Today that something is `ambit harvest`'s
+own `--producer` flag:
+
+    ambit harvest <stage> --scan "<run-dir>" --journal <journal> --producer "your assistant's name and version"
+
+`--producer` is optional and free text — name any assistant or tool, or omit it entirely. A
+direct-results-door author writing `results/<stage>.json` by hand carries the identical header
+shape without touching this flag at all: `{"producer": {"tool": "..."}}` sitting on the results
+file is all either path needs to produce. When the `extract` stage's own `results/<stage>.json`
+header never named a producer (the flag was omitted, or a legacy file predates this contract),
+`producer.tool` is **omitted entirely** from the draft, exactly as the example above shows — never
+written as a placeholder string, never guessed. A key that is present is always a real name
+someone gave; a key that is absent means no one gave one. Whitespace-only names (`"   "`) count as
+no name at all, on both the writing and the reading side, and are stripped before anything is
+stored — `ambit harvest --producer " "` prints one plain line saying so rather than silently
+writing a blank name. `producer.config_hash` is the scan's own configuration hash (the same
+value `results/symbols.json` and `results/edges.json` already carry); it binds this draft to the
+scan it was produced against, so a draft copied onto a differently-configured scan is caught
+rather than silently misjoined. `producer.engine_fingerprint` mirrors the draft's own top-level
+fingerprint field, absence-disclosed the identical way (an `engine_fingerprint_absent` flag
+stands in when no fingerprint could be computed).
+
+## Fail-closed, on every branch
+
+The reader that loads this draft never raises on anything it finds on disk, and never renders a
+guess:
+
+- No draft file at all — the normal, unremarkable state before judgment has run. Nothing is
+  shown, nothing is claimed.
+- A draft with no `"v"` key — every draft written before this contract existed. It loads exactly
+  as it always has; the absence of a version is never treated as a mismatch.
+- A draft whose `"v"` key is present but is anything other than the plain integer `1` — refused
+  by name, nothing from the draft is read further. This includes `"v": null` (declared but
+  unusable is not the same fact as absent), `"v": true` (a boolean is never accepted as an
+  integer, even where it happens to equal `1` by value), and `"v": 1.0` (a float is never accepted
+  in place of the declared integer schema version) — every one of these is a real, present value
+  that simply is not this reader's version `1`.
+- A draft whose `producer.config_hash` disagrees with the scan actually being served, when both
+  values are present — refused by name: the facts were produced against a different scan.
+- Anything else malformed (unparseable JSON, a top level that is not an object, a `units` field
+  that is not a list) — refused by name, the same as always.
+
+A refused draft never renders as an empty or zero judged plane — a plane that did not load never
+counts as a plane that loaded empty. Every other field this document does not name is tolerated
+additively: an unrecognised key is ignored, never a reason to refuse the whole file.
+
+## What the acceptance of a real repository taught
+
+The rules above are the shapes; running a real assistant against a real, unmodified public
+repository end to end found six ways a conforming file — or the run that produces it — can still
+mislead a reader even while it parses cleanly. Each is a rule for the assistant writing these
+files directly, not a change to the shapes themselves.
+
+- **`parent` is a verbatim anchor, or the empty string — never prose, and never an external
+  framework's name.** It is the exact `file::hook` text some other unit's own `anchor` field
+  carries, copied byte for byte, so a reader can follow it with a lookup, not a guess. It is
+  never a sentence describing the relationship ("extends the base template"), and never the name
+  of a class, component or framework this scan's own unit set does not contain: when a filler's
+  true parent lives OUTSIDE what this run analysed — a third-party base class, a library
+  component — the correct value is the empty string, the SAME value written when there is no
+  parent at all. The external case IS the empty-string case; it is never spelled out in its own
+  words instead.
+- **Evidence carries conclusions, never scratch reasoning or self-corrections.** The `ev` field,
+  and every free-text evidence field this contract accepts, states what you found — never the
+  thinking that got you there, and never a correction written into the record after the fact
+  ("actually, on reflection, it might instead..."). A reader who has to debug a train of thought
+  to recover the actual claim was handed reasoning, not evidence.
+- **Counts never go inside an anchor.** An anchor names WHICH unit a record is about — it is an
+  identity, never a place to carry a measurement. A number belongs in a field built to hold one,
+  or is left out; folding it into the anchor text itself (`"helpers.py::shout (12 calls)"`) turns
+  an identity into a claim, and the two must never be the same string.
+- **Never write "not in this file set," or any other claim about the file list's horizon.** A
+  large repository is read in chunks, and each analyst sees only the subset it was handed — a
+  sentence asserting what is or is not present ANYWHERE in the repository is a claim about ground
+  this one pass never covered. Worse, the harvester's own reduction keeps every evidence sentence
+  it receives VERBATIM: a horizon claim that was true of one chunk's own narrow view is carried
+  unchanged into the assembled draft, where it now reads as a claim about the WHOLE repository —
+  and is simply false there. State only what this pass itself observed inside the files it was
+  actually given.
+- **The number of stages a run produces is repository-dependent — never a fixed count to
+  expect.** `vocab` and `ownership` run only when the scan's own config declares them (see "The
+  stage results files" above); `suggest` runs only when at least one unit could not be accepted
+  in bulk (the next rule names every reason that can queue one). Watch until the conductor's own
+  exit; never assume in advance how many stages a given run will produce.
+- **The `suggest` queue is every unit the draft could not accept in bulk, and each entry's own
+  `why` field names every reason that queued it, comma-joined, in the engine's own words.** Four
+  independent checks fill the queue: `role == "unclear"` writes `"role unclear"`; otherwise a low
+  `confidence` writes `"low role confidence"`; no structural family assigned by the `cluster`
+  stage writes `"no structural family"`; low vocabulary confidence from the `vocab` stage writes
+  `"low vocabulary confidence"` — a unit can carry more than one of these at once, and none of
+  them is about duplicate code. Rule on the entry's OWN stated `why`, never a guess at what queued
+  it: for `"role unclear"`/`"low role confidence"` the question is "was my own prior uncertainty
+  justified" — but the other two reasons ask a genuinely different question, and the `why` string
+  is what tells you which one you are actually answering. Read it before ruling; do not assume it
+  is always the hedging question.