Metadata-Version: 2.5
Name: codemble
Version: 0.22.0
Summary: A learning game that turns the code AI wrote for you into a galaxy you light up by understanding it.
Project-URL: Homepage, https://udhawan97.github.io/Codemble/
Project-URL: Repository, https://github.com/udhawan97/Codemble
Author-email: Umang Dhawan <umangdhawan97@gmail.com>
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Education
Classifier: Topic :: Software Development :: Documentation
Requires-Python: >=3.11
Requires-Dist: anyio>=4.1
Requires-Dist: fastapi>=0.115
Requires-Dist: tree-sitter-c-sharp<0.24,>=0.23
Requires-Dist: tree-sitter-go<0.24,>=0.23
Requires-Dist: tree-sitter-java<0.24,>=0.23
Requires-Dist: tree-sitter-javascript<0.26,>=0.25
Requires-Dist: tree-sitter-php<0.25,>=0.24
Requires-Dist: tree-sitter-ruby<0.24,>=0.23
Requires-Dist: tree-sitter-rust<0.24,>=0.23
Requires-Dist: tree-sitter-typescript<0.24,>=0.23.2
Requires-Dist: tree-sitter<0.26,>=0.25
Requires-Dist: uvicorn>=0.30
Provides-Extra: dev
Requires-Dist: httpx>=0.27; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff<0.17,>=0.16; extra == 'dev'
Description-Content-Type: text/markdown

<p align="center">
  <a href="https://udhawan97.github.io/Codemble/">
    <img src="https://github.com/udhawan97/Codemble/raw/v0.22.0/docs-site/public/brand/mark-animated.svg" alt="Codemble — an open lapis ensō whose amber star systems light up" width="144">
  </a>
</p>

<h1 align="center">Codemble</h1>

<p align="center"><strong>Explore the code AI left behind.</strong></p>

<p align="center">
  Codemble reads a project on your machine and turns its real structure into a
  galaxy you can explore or a diagram you can follow. Study any file, see what
  a change reaches, follow one feature from Home to its application surface,
  and light only what you prove you understand.
</p>

<p align="center">
  <a href="https://github.com/udhawan97/Codemble/releases/tag/v0.22.0"><img src="https://img.shields.io/badge/stable-v0.22.0-2b4d96?style=flat-square" alt="Stable release v0.22.0"></a>
  <a href="https://github.com/udhawan97/Codemble/actions/workflows/ci.yml"><img src="https://github.com/udhawan97/Codemble/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI status"></a>
  <img src="https://img.shields.io/badge/Python-3.11+-2b4d96?style=flat-square" alt="Python 3.11 or newer">
  <img src="https://img.shields.io/badge/maps-9_languages-3f6ac0?style=flat-square" alt="Maps nine languages">
  <img src="https://img.shields.io/badge/license-Apache_2.0-070b1c?style=flat-square" alt="Apache 2.0 license">
</p>

<p align="center">
  <a href="#start-here">Start here</a> ·
  <a href="#see-the-learning-loop">See the loop</a> ·
  <a href="#what-codemble-can-prove">Trust boundary</a> ·
  <a href="https://udhawan97.github.io/Codemble/">Website</a> ·
  <a href="https://udhawan97.github.io/Codemble/introduction/">Docs</a>
</p>

<p align="center">
  <img src="https://github.com/udhawan97/Codemble/raw/v0.22.0/docs-site/public/shots/galaxy.png" alt="Codemble v0.22.0 showing 217 colourful star systems across nine languages in a luminous spiral galaxy, with named modules, parser-proven routes, 37 charted systems, and Home resolved to codemble.cli without claiming it is understood." width="1000">
</p>

<p align="center"><sub>
  Codemble v0.22.0 · choose free exploration or a guided First Flight ·
  land on a world for Easy or Expert evidence ·
  visiting charts a route; passing checks lights a system amber
</sub></p>

> [!IMPORTANT]
> **The screen above and the packaged app are both v0.22.0.** The PyPI release
> maps Python, JavaScript, TypeScript, Go, Java, Rust, C#, Ruby, PHP, and mixed
> projects. At launch, choose free exploration or a guided First Flight; land
> on any parser-owned world to switch between Easy and Expert evidence, inspect
> its inbound and outbound connections, then read source or prove understanding.
> The pinned command and direct downloads below resolve to the same verified
> release.

## Start here

### Run v0.22.0 — recommended

Install [uv](https://docs.astral.sh/uv/) once, then open Codemble whenever you
need it:

| | Step | Command |
| :---: | --- | --- |
| <img src="https://github.com/udhawan97/Codemble/raw/v0.22.0/docs-site/public/brand/icons/install.svg" width="22" height="22" alt=""> | **Install uv** — a clean Python app runner | `brew install uv` |
| <img src="https://github.com/udhawan97/Codemble/raw/v0.22.0/docs-site/public/brand/icons/run.svg" width="22" height="22" alt=""> | **Open this release** — pick a project in the browser | `uvx --from codemble==0.22.0 codemble` |

No Homebrew? Use uv's [official installer](https://docs.astral.sh/uv/getting-started/installation/),
or install permanently with `pipx install codemble==0.22.0` and run `codemble`.
Pass a folder to skip the project picker:
`uvx --from codemble==0.22.0 codemble ./my-project`.
Use the shorter `uvx codemble` when you intentionally want whatever release is
newest on PyPI.

<p align="center">
  <a href="https://pypi.org/project/codemble/0.22.0/#files">
    <img src="https://github.com/udhawan97/Codemble/raw/v0.22.0/docs-site/public/brand/download-codemble.svg" alt="Download Codemble — wheel, source archive, SHA256 digests, and release notes" width="760">
  </a>
</p>

<p align="center">
  <a href="https://github.com/udhawan97/Codemble/releases/download/v0.22.0/codemble-0.22.0-py3-none-any.whl"><img src="https://github.com/udhawan97/Codemble/raw/v0.22.0/docs-site/public/brand/icons/download.svg" alt="" width="18"> Wheel</a> ·
  <a href="https://github.com/udhawan97/Codemble/releases/download/v0.22.0/codemble-0.22.0.tar.gz"><img src="https://github.com/udhawan97/Codemble/raw/v0.22.0/docs-site/public/brand/icons/package.svg" alt="" width="18"> Source archive</a> ·
  <a href="https://github.com/udhawan97/Codemble/releases/download/v0.22.0/SHA256SUMS.txt"><img src="https://github.com/udhawan97/Codemble/raw/v0.22.0/docs-site/public/brand/icons/shield.svg" alt="" width="18"> SHA256SUMS</a> ·
  <a href="https://pypi.org/project/codemble/0.22.0/#files">PyPI files</a> ·
  <a href="https://github.com/udhawan97/Codemble/releases/tag/v0.22.0"><img src="https://github.com/udhawan97/Codemble/raw/v0.22.0/docs-site/public/brand/icons/release.svg" alt="" width="18"> Release notes</a>
</p>

### Build the same v0.22.0 app from source

Use this route when you want an editable checkout:

```bash
git clone --branch v0.22.0 --depth 1 https://github.com/udhawan97/Codemble.git
cd Codemble
python -m venv .venv
source .venv/bin/activate       # Windows: .venv\Scripts\activate
pip install -e .
codemble
```

Read the
[full build guide](https://udhawan97.github.io/Codemble/build-from-source/) for
the verification commands.

## What Codemble does

| | Plain-English answer |
| :---: | --- |
| <img src="https://github.com/udhawan97/Codemble/raw/v0.22.0/docs-site/public/brand/icons/compass.svg" width="24" height="24" alt=""> | **Choose your launch.** Explore freely in a fully visible, colourful galaxy, or take a guided First Flight from Home. Learning guidance may quiet unvisited context; free exploration keeps it alive. |
| <img src="https://github.com/udhawan97/Codemble/raw/v0.22.0/docs-site/public/brand/icons/map.svg" width="24" height="24" alt=""> | **Read a real solar system.** Each module becomes a system whose module anchor is its Sun. Named functions and classes orbit through parser-owned call placement, with language-shaped colour, terrain, bands, and motion. |
| <img src="https://github.com/udhawan97/Codemble/raw/v0.22.0/docs-site/public/brand/icons/compass.svg" width="24" height="24" alt=""> | **Follow the constellation.** A nearby-systems console names certain and possible inbound and outbound imports, keeps their certainty visible, and lets you continue directly into a connected solar system. |
| <img src="https://github.com/udhawan97/Codemble/raw/v0.22.0/docs-site/public/brand/icons/impact.svg" width="24" height="24" alt=""> | **Know what a change touches.** Impact traces what depends on a structure and what it depends on, with real file locations and certainty labels. |
| <img src="https://github.com/udhawan97/Codemble/raw/v0.22.0/docs-site/public/brand/icons/check.svg" width="24" height="24" alt=""> | **Prove what you understand.** Graph-derived checks—not a narrator—are the only way to light a system amber. |
| <img src="https://github.com/udhawan97/Codemble/raw/v0.22.0/docs-site/public/brand/icons/shield.svg" width="24" height="24" alt=""> | **Keep the project local.** Parsing, maps, source, Impact, checks, and progress stay on your machine. |
| <img src="https://github.com/udhawan97/Codemble/raw/v0.22.0/docs-site/public/brand/icons/languages.svg" width="24" height="24" alt=""> | **Read mixed projects.** Python, JavaScript, TypeScript, Go, Java, Rust, C#, Ruby, and PHP share one graph and one honesty contract. |

Codemble reads supported source. It does **not** run your app, package scripts,
compilers, or tests.

## See the learning loop

| 01 · Explore | 02 · Map |
| --- | --- |
| <img src="https://github.com/udhawan97/Codemble/raw/v0.22.0/docs-site/public/shots/galaxy.png" alt="Current Codemble galaxy with a seeded spiral starfield, visible named modules, and selective import routes." width="600"> | <img src="https://github.com/udhawan97/Codemble/raw/v0.22.0/docs-site/public/shots/map-architecture.png" alt="Current Codemble canvas Architecture map with Home, connected modules, and complete bottom rows for modules without a proven import route." width="600"> |
| Choose free exploration or First Flight; guided stops can land directly into Study and checks. | Follow real imports from Home; unreachable modules are counted, not erased. |

| 03 · Inspect | 04 · Prove |
| --- | --- |
| <img src="https://github.com/udhawan97/Codemble/raw/v0.22.0/docs-site/public/shots/study-panel.png" alt="Current Codemble landing panel with the selected world, Easy or Expert explanation control, and parser-owned connections." width="600"> | <img src="https://github.com/udhawan97/Codemble/raw/v0.22.0/docs-site/public/shots/home-proved.png" alt="Current Codemble Home system after its graph-derived checks were passed, with all four parser-proven structures glowing amber." width="600"> |
| Land on a structure, change its explanation register in place, and follow its real connections. | Pass checks drawn from the graph; only then does the system turn amber. |

### One graph, two useful views

| View | What it shows | When it helps |
| --- | --- | --- |
| **Galaxy** | Modules as colourful star systems and imports as routes | Learn the shape of the whole project |
| **Solar system** | The module anchor as its Sun; named structures as language-styled worlds in call orbits that distinguish certain calls, call roots, and no-path placement | Understand one module and continue through parser-owned neighbouring imports |
| **Map · Architecture** | Modules grouped by folder and layered by proven imports from Home | See how parts fit together |
| **Map · Workflow** | Certain calls from the selected entrypoint, depth by depth | See what runs first |
| **Star chart** | Project overview, proven import cycles, progress, and a local Markdown export | Carry parser-owned facts into a handoff |
| **Study** | One feature journey, real source, integrated Impact and Connections, Lens notes, and optional narration | Understand how one structure reaches the application |

The default all-language Map is a complete viewport-rendered canvas; an explicit
language focus keeps every item in that named projection. Both remain usable on
a machine that cannot render the WebGL galaxy without creating one DOM element
per module.
Easy mode shows an overview and guides one cited journey step at a
time. Expert mode keeps that exact step selected and adds its parser rule and
observation evidence. Impact, Connections, and bounded test candidates describe
the selected feature as a whole, not the current route step. Neither mode
changes the underlying evidence, route certainty, or scoring.

## What Codemble can prove

Codemble is built for readers who may not yet spot a confident mistake, so its
limits are part of the interface:

- Nodes, routes, language concepts, Home candidates, and application/test roles
  come from parsers with exact source evidence.
- Unproven relationships are labelled **possible** and drawn differently on
  both the galaxy and the map. A feature journey stops at the proof break before
  showing a target-relevant possible frontier; colour never upgrades certainty.
- Impact and check answers come from the graph and need no API key.
- Unsupported or broken source is counted and named instead of silently hidden.
- Charting records where you went. Only a passed check records understanding.
- Changing a file re-dims only that file's proof; the rest of your progress stays.

Read the [correctness contract](https://udhawan97.github.io/Codemble/correctness/).
A wrong node, edge, citation, Lens note, or check answer is a highest-severity
bug—[report it](https://github.com/udhawan97/Codemble/issues/new/choose).

## Local-first, with an explicit AI boundary

| Stays on your machine | Leaves only when Study opens with a configured narrator |
| --- | --- |
| Project discovery and parsing | A bounded Study excerpt sent to your configured narrator |
| Graph, maps, feature journeys, source, structural summary, Impact, Lens, and checks | A request triggered when you open Study |
| Progress and narration cache in `~/.codemble/` | No background requests |
| Narration too, when you choose local Ollama | No accounts, telemetry, or Codemble cloud |

No model? Everything except optional prose narration remains available. To add
cloud narration, set `ANTHROPIC_API_KEY` or `OPENAI_API_KEY`. To keep narration
local as well:

```bash
ollama pull gemma4:12b
export CODEMBLE_PROVIDER=ollama
export CODEMBLE_OLLAMA_MODEL=gemma4:12b
```

<details>
<summary><strong>Project and rendering limits</strong></summary>

- **Supported languages:** `.py`, `.js`, `.jsx`, `.mjs`, `.cjs`, `.ts`,
  `.tsx`, `.mts`, `.cts`, `.go`, `.java`, `.rs`, `.cs`, `.rb`, and `.php`.
- **Scale:** above roughly 5,000 supported files, choose a subdirectory in the
  picker or pass `--path ./project/src`.
- **Ambiguous Home:** choose a parser-ranked candidate in the app or pass
  `--entrypoint NODE_ID`.
- **Broken source:** safe partial evidence stays visible; Codemble never invents
  the missing structure.
- **Rendering:** the galaxy needs WebGL; the flat Map does not.

</details>

<details>
<summary><strong>Develop and verify</strong></summary>

```bash
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest && ruff check .

(cd web && npm install && npm run check)
(cd docs-site && npm install && npm run check && npm run build)
```

The [architecture](https://udhawan97.github.io/Codemble/architecture/),
[parser evidence and scale record](https://udhawan97.github.io/Codemble/parser-scale/),
[contributing guide](https://github.com/udhawan97/Codemble/blob/main/CONTRIBUTING.md),
[design system](https://github.com/udhawan97/Codemble/blob/main/docs-site/design.md),
and [agent operating guide](https://github.com/udhawan97/Codemble/blob/main/CLAUDE.md)
keep the load-bearing decisions explicit.

</details>

## Help test the loop

The most useful contribution is a ten-minute first run on a real AI-built
project:

1. Follow the [privacy-safe tester guide](https://github.com/udhawan97/Codemble/blob/main/TESTING.md).
2. Light one system without maintainer help.
3. Report the first confusing moment in your own words—never paste private code,
   project names, credentials, or API keys.

[🧭 Open an early-tester report](https://github.com/udhawan97/Codemble/issues/new/choose)

## Roadmap

| Horizon | Work |
| --- | --- |
| **Now** | Collect unaided learner evidence and correctness reports on v0.22.0 |
| **Next** | Design the privacy boundary for the planned read-only galaxy link |
| **Later** | Read-only sharing, new quest types, and a coordinated public launch |

Milestones move only when their acceptance evidence exists. See the
[public roadmap](https://udhawan97.github.io/Codemble/roadmap/).

## License and acknowledgements

Codemble is released under the [Apache License 2.0](https://github.com/udhawan97/Codemble/blob/main/LICENSE). It is built with
[tree-sitter](https://github.com/tree-sitter/tree-sitter),
[FastAPI](https://github.com/fastapi/fastapi),
[React](https://github.com/facebook/react), and
[3d-force-graph](https://github.com/vasturiano/3d-force-graph). The flat-map
approach draws inspiration from [dagre](https://github.com/dagrejs/dagre),
[Eclipse ELK](https://github.com/kieler/elkjs), and
[archify](https://github.com/tt-a1i/archify); the community constellations were
inspired by [Graphify](https://github.com/Graphify-Labs/graphify).
The [parser evidence and scale record](https://udhawan97.github.io/Codemble/parser-scale/)
credits the exact pinned open-source revisions behind the current cache and
benchmark design; Codemble copied no source or assets from them.

---

<p align="center"><sub>
  Built for the moment after “AI made it work” and before “I know how it works.”
</sub></p>
