Metadata-Version: 2.4
Name: javis
Version: 0.2.0
Summary: Joint Autonomous Verified Intelligence System — harness-governed coding agent; intelligence in the harness, not the model
Author: Okello Solomon Roy Jasper
License-Expression: Apache-2.0
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Provides-Extra: llm
Requires-Dist: litellm>=1.0; extra == "llm"
Requires-Dist: tenacity; extra == "llm"
Provides-Extra: lsp
Requires-Dist: python-lsp-server; extra == "lsp"
Requires-Dist: pyflakes; extra == "lsp"
Provides-Extra: treesitter
Requires-Dist: tree-sitter-language-pack>=0.20; extra == "treesitter"
Provides-Extra: tui
Requires-Dist: rich>=13; extra == "tui"
Requires-Dist: prompt_toolkit>=3; extra == "tui"
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: pytest-cov>=4; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Requires-Dist: mypy>=1.8; extra == "dev"
Dynamic: license-file

# JAVIS — Joint Autonomous Verified Intelligence System

A harness-governed coding agent. The name is the thesis: intelligence is **joint** —
the model is an untrusted prover, the harness a sound proof checker, and neither is the
agent alone — and every claim is **verified**: the gates refuse to advance on anything
the tests, parser, or resolver can't confirm. **Put the execution intelligence in the
harness, not the model.** See [`docs/harness-contract.md`](docs/harness-contract.md).

Created by **Okello Solomon Roy Jasper**.

## Quickstart

```bash
git clone https://github.com/Code-weaver1/javis.git && cd javis
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[llm,tui]"

export OPENROUTER_API_KEY=sk-or-...   # any OpenRouter key — free-tier models are enough
javis --check                         # preflight: validates your model ladder against the live catalog
javis --tui --repo /path/to/your/project --task "fix the failing test"
```

No API key yet? Watch the harness narrate a three-step gated task behind a scripted model —
no network, no account:

```bash
python scripts/tui_narration_demo.py --delay 0.4
```

Prefer a guided setup (pick a provider, model, and key interactively)? `javis --setup`.

## Status: v1 — a trustworthy correctness engine

The `plan → propose → adjudicate → admit` loop with an **enforced gate set** —
**0** (plan-shape), **1** (resolve — rejects hallucinated calls), **2/2b** (read-before-write /
read-verbatim), **3** (parse), **6** (test), **7** (oracle-integrity — the test oracle is read-only) —
plus a **tiered router** (escalate to a strong tier on failure), a **difficulty-graded fixture
suite**, `--sandbox` runs, and tier-labeled trajectory logging. Self-planning is off by default
(Phase 0 showed it hurts; opt in with `--plan`).

**Honest scope:** the harness guarantees **correctness** — it never ships broken or regressing
code, and the oracle can't be gamed — but it does **not** by itself lift a weak model's *completion
rate* on reasoning-hard tasks (that's the router + distillation). See `docs/harness-contract.md` §7.
Growth still ahead: lint/type gates (4/5), coherence + `arch-spec` (8), distillation *training* (P5).

**Reliability layer** (adapted from [Hermes](https://github.com/NousResearch/hermes-agent)): tool-loop
guardrails (halt-and-escalate on thrash), tool-call JSON repair for weak models, a structured API
error taxonomy driving router escalation, and a rate-limit cooldown guard so a 429'd model is skipped
rather than hammered.

**Cost & caching (provider-agnostic).** No provider-specific caching code. The loop keeps a byte-stable
prompt prefix (system + task) across turns, so providers that auto-cache prefixes (OpenAI, DeepSeek,
Gemini, most via OpenRouter) apply the discount for free; the one provider that needs explicit
`cache_control` markers (Anthropic) is handled by litellm when you opt in with `--cache` (off by
default), never by branching in JAVIS. Context
compression trims the non-cacheable tail. Net cost levers, all agnostic: stable prefix → auto-cache,
compression, and escalating to the expensive tier only on failure.

**Extending JAVIS** (provider-agnostic, opt-in — see [`docs/extensibility.md`](docs/extensibility.md)):
project context (`JAVIS.md`), declarative policy (`.javis-policy.json`), lifecycle hooks
(`.javis/hooks.json`), reusable commands (`.javis/commands/`), and read-only subagents the main
agent can delegate to (`.javis/agents/`). Autonomous sandboxing recipe in
[`docs/autonomous-sandbox.md`](docs/autonomous-sandbox.md).

## Layout

```
javis/
  loop.py        plan -> propose -> adjudicate -> admit
  plan.py        plan stage + plan-shape gate (gate 0)
  context.py     context window + read-set / read-content (gates 2, 2b)
  model.py       Model protocol; ScriptedModel (tests/control) + LiteLLMModel (OpenRouter)
  router.py      tiered escalation (cheap -> strong on failure / API error)
  guardrails.py  loop detection — halt a thrashing run so the router escalates
  sanitize.py    repair malformed tool-call JSON from weak models
  errors.py      API error taxonomy (rate_limit / billing / not_found / ...)
  ratelimit.py   x-ratelimit header parse + file-based cooldown guard
  budget.py      run budget
  trajectory.py  day-0 tier-labeled distillation capture
  experiment.py  the de-risk matrix runner (models x conditions x fixtures)
  distill.py     export gate-passed trajectories as tier-labeled SFT data (P5)
  failure_memory.py  mine recurring failures -> guardrail-hint candidates
  catalog.py     pick tool-capable / cheap OpenRouter models
  hooks.py       lifecycle hooks (PreTool/PostTool/Stop scripts)
  commands.py    markdown task templates (--command / /name)
  subagents.py   read-only specialized agents (delegate + PARALLEL dispatch); built-in reviewer
  repomap.py     symbol-level repo map (files + their defs/classes)
  planmode.py    human-approved plan mode (REPL /plan)
  tools/git.py   git awareness (status/diff/log) + commit-on-success
  tools/         fs (read/edit), code (grep/resolve), tests (the pytest oracle)
  gates/         resolve (1), readwrite (2/2b), parse (3), verify (6), oracle (7), policy, base
  cli.py         REPL + --headless + --sandbox + --strong-model + --cache + --command + --agent
                 + --commit + --review + --lint + --types + --map; REPL /plan
fixtures/        difficulty-graded suite L1-L6 (see fixtures/SUITE.md) + suite.json
tests/           JAVIS's own suite (the harness verifies itself)
docs/            harness-contract.md
```

## Maturity

JAVIS has a **stable core** and a wider **experimental surface**. Both are covered by the test suite,
but the core is what the correctness guarantees rest on and what every run exercises; the experimental
modules are iterated less often, change faster, and are not on the correctness path.

- **Stable core** — the loop and gates (`loop.py`, `gates/`, `tools/`), the model/provider layer
  (`model.py`, `router.py`, `errors.py`, `ratelimit.py`), context + planning (`context.py`, `plan.py`,
  `compress.py`), `guardrails.py`, `narrator.py`, the LSP type gate (`lsp.py`), and the TUI/CLI.
- **Experimental / research** — the orchestration bake-off (`orchestrate.py`), the distillation
  pipeline (`distill.py`, `experiment.py`, `failure_memory.py`), the benchmark runners
  (`swebench*.py`, `polyglot.py`, `eval_ab.py`), and the plugin marketplace (`marketplace.py`,
  `mcp_install.py`). Useful and tested, but expect rougher edges and faster change.

## Run

```bash
# JAVIS's own tests (no network, no litellm needed)
python -m pytest

# Drive a real model against a fixture (needs litellm + OPENROUTER_API_KEY)
pip install -e ".[llm]"
export OPENROUTER_API_KEY=...
javis --headless --repo fixtures/bugfix-01 --task "make the test suite pass" \
      --model openrouter/meta-llama/llama-3.1-8b-instruct --trajectory run.jsonl

# Run fully local — no cloud, no API bill (Ollama/LM Studio/vLLM). See docs/local-llm.md
javis --repo . --task "fix the failing test" --local --model ollama/qwen2.5-coder:7b
```

Local LLMs (incl. models with no native tool-calling) are first-class — see
[`docs/local-llm.md`](docs/local-llm.md).

```bash
# First-run setup wizard (pick provider/model, local or a key). See docs/setup.md
pip install -e ".[tui]"
javis --setup

# Live terminal UI — splash, welcome panel, working status, slash commands. See docs/tui.md
javis --tui --repo . --task "fix the failing test"
```

The agent can run shell commands behind a permission prompt, and renders multi-step plans as a live
checklist — see [`docs/shell-and-tasks.md`](docs/shell-and-tasks.md).

JAVIS speaks **MCP** — drop in the standard `.mcp.json` and it inherits the whole Model Context Protocol
tool ecosystem (`javis --mcp`), gated by permission. See [`docs/mcp.md`](docs/mcp.md).

**Plugins** bundle commands + agents + hooks + MCP servers; JAVIS installs them from a git URL or local
dir, including **Claude-Code-format** plugins — translated to run on *any* model (incl. local). A
curated **built-in marketplace** ships in the package (`javis --plugin-install code-review`). See
[`docs/plugins.md`](docs/plugins.md).

**Measure capability** — `javis-eval` is a lite, local, SWE-bench-style scorecard: real bug-fix
fixtures, reproduce → solve → score *independently* with the test oracle. Headline numbers are
`resolved/total` and **false-green** (claimed success the tests don't support — a trustworthy harness
scores zero, and the CLI exits non-zero if any appear). See [`docs/eval.md`](docs/eval.md).

```bash
javis-eval --strong-model openrouter/anthropic/claude-sonnet-4   # cheap base, escalate on measured failure
```

For a comparable number, **`javis-swebench`** points the same reproduce → solve → score loop at the
**SWE-bench format** (real GitHub issues; checkout at `base_commit`, apply `test_patch`, score
`FAIL_TO_PASS`/`PASS_TO_PASS`). See [`docs/swebench.md`](docs/swebench.md).

### De-risk experiment knobs
- `--no-gates` — control: disable the harness (still scored by the final suite) to measure the harness's contribution.
- `--plan` — opt back into the self-planning stage (OFF by default; Phase 0 showed self-planning hurts completion).
- `--sandbox` — run on a throwaway copy of `--repo`, leaving the original untouched (try the agent on a fixture without mutating it).

## License

[Apache-2.0](LICENSE) © 2026 Okello Solomon Roy Jasper.
