Metadata-Version: 2.4
Name: jungle-brain
Version: 0.1.0
Summary: Jungle context engine: bounded-context agent loop, context packs, MCP server and local HTTP API for project memory
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: fastapi<1,>=0.115
Requires-Dist: uvicorn[standard]<1,>=0.34
Requires-Dist: pydantic<3,>=2.10
Requires-Dist: python-dotenv<2,>=1.0
Requires-Dist: tiktoken<1,>=0.9
Requires-Dist: mcp<2,>=1.28
Requires-Dist: filelock<4,>=3.16
Requires-Dist: regex>=2024.11
Requires-Dist: tree-sitter<0.26,>=0.23
Requires-Dist: tree-sitter-language-pack<2,>=1.10
Requires-Dist: httpx<1,>=0.28
Provides-Extra: api
Requires-Dist: anthropic<3,>=0.69; extra == "api"
Provides-Extra: openai
Requires-Dist: openai<3,>=2.0; extra == "openai"
Provides-Extra: embeddings
Requires-Dist: sentence-transformers<6,>=3.4; extra == "embeddings"
Requires-Dist: lancedb<1,>=0.20; extra == "embeddings"
Requires-Dist: pyarrow<25,>=18; extra == "embeddings"
Provides-Extra: db-shaping
Requires-Dist: psycopg[binary]<4,>=3.1; extra == "db-shaping"
Provides-Extra: fastembed
Requires-Dist: sentence-transformers==5.6.0; extra == "fastembed"
Requires-Dist: fastembed==0.8.0; extra == "fastembed"
Requires-Dist: lancedb<1,>=0.20; extra == "fastembed"
Requires-Dist: pyarrow<25,>=18; extra == "fastembed"
Provides-Extra: granite-mlx
Requires-Dist: mlx-lm==0.31.3; (platform_system == "Darwin" and platform_machine == "arm64") and extra == "granite-mlx"
Requires-Dist: mlx==0.32.2; (platform_system == "Darwin" and platform_machine == "arm64") and extra == "granite-mlx"
Requires-Dist: transformers==5.0.0; (platform_system == "Darwin" and platform_machine == "arm64") and extra == "granite-mlx"
Provides-Extra: gcs
Requires-Dist: google-cloud-storage<4,>=3.1; extra == "gcs"
Provides-Extra: all
Requires-Dist: jungle-brain[api,embeddings,gcs,openai]; extra == "all"
Provides-Extra: dev
Requires-Dist: jungle-brain[all]; extra == "dev"
Requires-Dist: pytest<10,>=8.3; extra == "dev"

# Jungle

Local-first context OS for codebases. Jungle turns a repository into compact,
searchable project memory and drives a **working-set-compiled agent loop**: each
turn the model sees a small, freshly assembled context (outlines + expanded
symbols + pinned edit targets) instead of an ever-growing transcript.

Everything runs on your machine — indexing, local embeddings, retrieval, and
memory. The production index does not call an LLM. No repository content
leaves the box unless you explicitly wire in a paid API driver.

## Why

Measured against a plain `claude -p` agent on real open-source repos
(see [docs/BENCHMARKS_REPORT.md](docs/BENCHMARKS_REPORT.md)):

- **2.4–4.3× fewer tokens** per task suite; 9.5× on batching-friendly single tasks
- **Flat ~1–3K-token working set** regardless of repo size or session length
  (176K peak for the regular agent on `rich` vs 2.9K for Jungle)
- **0 hallucinated edits** across all benchmark runs — the edit gate only accepts
  edits to text the model has actually been shown (gate == render, structurally)
- **25K-file repos index** in minutes (batched encode/upsert; crash-resumable)
- **90+ languages** indexed and outlined via a tree-sitter harness; mixed-language
  repos work per-file

## Layout

| Path | What it is |
| --- | --- |
| `backend/` | FastAPI + MCP server: ingestion, structural index, retrieval, context packs |
| `jungle/` | Python SDK facade — `Brain` (`index / pack / discover / session / solve`) |
| `jungle_agent/` | The bounded loop: outline compiler, engine, edit gate, drivers, REPL |
| `frontend/` | Electron + React desktop client |
| `sdk/` | TypeScript client bindings |
| `benchmarks/` | Offline oracles + live A/B harnesses |
| `scripts/` | Session hooks (intent memory, checkpoints) + install helpers |
| `docs/` | Reports, evaluations, SDK contract, setup guides |

## Quickstart

For standalone, model-free code search, install the base package and search:

```bash
python -m pip install .
jungle-search 'handle_request' --project /path/to/repo
jungle-search config --project /path/to/repo  # print single-tool MCP setup
```

Indexing and working-tree freshness are automatic. This exposes Jungle's own
search tool without installing hooks or replacing native grep.
See [Jungle Search](docs/SEARCH.md) for CLI options, MCP setup, and search scope.

For the full context engine and agent loop:

```bash
python3.11 -m venv .venv
source .venv/bin/activate
pip install -e . -r backend/requirements.txt
```

Index a repo and solve a task through the SDK:

```python
from jungle import Brain

brain = Brain("/path/to/repo")
brain.index()  # local embeddings + structural/lexical facts; no LLM summaries

# Batteries included — full bounded loop with the Anthropic API driver:
result = brain.solve("Add a DELETE /projects/{id} endpoint", driver="api")
print(result["metering"])                          # turns, peak context, driver usage

# Or inversion of control — your model, Jungle compiles the working set:
session = brain.session("Fix the retry logic in uploader.py")
prompt = session.render()                          # flat ~2-4K-token working set
action = your_model(prompt)                        # you own the model call
session.apply(action)                              # fetch/expand/edit/… gated + applied
```

Interactive terminal on the subscription (no metered API):

```bash
python -m jungle_agent.repl --repo /path/to/repo
```

Run the backend + desktop client, install the MCP server, or set up
cross-agent session hooks: see [docs/SETUP.md](docs/SETUP.md),
[docs/INSTALL_MCP.md](docs/INSTALL_MCP.md), and
[docs/cross-agent-setup.md](docs/cross-agent-setup.md).

Use Jungle as the external memory and loop controller in the native apps you
already use:

```bash
jungle on /path/to/repo               # detects hosts, embeds locally, enrolls

cd /path/to/repo
claude                                # CLI, or open the project in its desktop app
# or: codex                           # CLI and Codex desktop share the plugin
# jungle on --mode control            # strict loop-control tier (opt-in)
```

Host detection covers both command-line installations and macOS desktop app
bundles. An app-only Codex install is supported through the executable bundled
inside `Codex.app`; no separate `codex` command on `PATH` is required. Claude
desktop is reported too, but full project hooks require its Claude Code plugin
runtime. `jungle native status /path/to/repo` shows the detected surfaces,
installer source, and honest capability profile.

From a source checkout, installation plus enrollment is also one command:

```bash
./scripts/install-jungle /path/to/repo
```

Once enrolled, global plugins remain silent in every other repository. If the
plugin is already loaded, Jungle attaches before the next prompt in the same
Claude/Codex conversation; otherwise one fresh session loads it and starts
automatically. Say “turn Jungle on for this project” to the installed skill, or
use `/jungle` in Claude, for the same deterministic command. Disable without
deleting the index or plugins with `jungle off /path/to/repo`.

Check and install updates with the same CLI:

```bash
jungle update --check     # explicit current/outdated answer
jungle update             # safe fast-forward/package upgrade + plugin refresh
```

`jungle status` and `jungle doctor` include the cached update state. Enrolled
Claude/Codex sessions refresh that cache in the background; Claude's Jungle
statusline displays `↑ jungle update` when action is needed. Source updates
refuse dirty or non-fast-forward checkouts instead of overwriting local work.
Packaged installs resolve one exact `jungle-brain` release, verify the installed
version, then refresh the native plugins used by both CLI and app surfaces.

`jungle index` and `jungle on` build the same production tier: source/chunk
embeddings plus structural and lexical facts, with `summarize=False`. If the
embeddings extra is missing, the CLI says so and safely falls back to the
embed-free structural index. `--fast`/`--no-summarize` remain compatibility
aliases for this LLM-free default.

The older per-file LLM summary path is retained only as an explicit
compatibility experiment; it is not required for semantic readiness:

```bash
jungle index --semantic-provider claude --summary-model haiku
# add --reindex when replacing an existing semantic/Ollama analysis
# or during enrollment:
jungle on /path/to/repo --full --semantic-provider claude --summary-model haiku
```

That explicit legacy form launches tool-less, stateless `claude -p` calls with a strict
`FileAnalysis` schema. Project settings, MCP servers, skills, API-key auth, and
repository instructions are excluded; source is treated as untrusted data.

The Claude and Codex plugins share one runtime, evidence ledger, verification
gate, and Stop decision. Claude exposes the full native control surface; Codex
enforces the covered Bash/apply-patch/MCP path but retains documented native
escape paths, so full Codex authority requires Codex-through-Engine. MCP remains the local
transport/backplane; the model is not asked to manage memory with voluntary MCP
calls. See [docs/runtime-controller.md](docs/runtime-controller.md).

## How the loop stays small

`jungle_agent` renders files as **outlines** — signatures and docstring heads with
bodies collapsed to stubs — and expands a symbol only when the model asks. Every
text field is an exact slice of the source (never reconstructed), so edits are
byte-exact, and the edit gate rejects any edit to text that was never rendered.
Eviction collapses cold bodies back to stubs; edit targets stay pinned. Context
is bounded by construction — there is nothing to compact.

The same machinery is exposed through the SDK: `brain.session()` for harness
owners, `brain.solve()` for end-to-end runs with metering.

## Development

```bash
.venv/bin/python -m pytest backend/tests jungle_agent/tests jungle -q   # ~915 tests
.venv/bin/ruff check backend jungle jungle_agent
cd frontend && npm test
```

Key documents: [docs/SDK_CONTRACT.md](docs/SDK_CONTRACT.md) ·
[docs/SDK_QUICKSTART.md](docs/SDK_QUICKSTART.md) ·
[docs/BENCHMARKS_REPORT.md](docs/BENCHMARKS_REPORT.md) ·
[docs/REVIEW_REPORT.md](docs/REVIEW_REPORT.md) (foundation audit) ·
[docs/STRATEGY.md](docs/STRATEGY.md)

Migrating a local checkout from the old `project-brain/` layout:
[docs/MIGRATION.md](docs/MIGRATION.md).

---

Private repository — all rights reserved.
