javis 0.2.0__py3-none-any.whl

javis/__init__.py

@@ -0,0 +1,7 @@
+"""JAVIS — a harness-governed coding agent.
+
+Phase 0 thesis: the intelligence is in the harness, not the model. The model is an
+untrusted prover; the harness is a sound proof checker. See docs/harness-contract.md.
+"""
+
+__version__ = "0.0.0"

javis/_banner.py

@@ -0,0 +1,69 @@
+"""Generated by scripts/gen_banner.py from the JAVIS logo. Do not edit by hand.
+HERO/LOGO are rich markup (crimson scorpion / white shield); *_PLAIN strip the tags."""
+
+HERO = r'''
+                      [#f5f5f5]▒▓▓▒▒[/] [#e10600]▓█████▓[/]       [#e10600]▓█████▒[/] [#f5f5f5]▒▓▓▓▒[/]
+                   [#f5f5f5]▓██▓[/] [#e10600]▒██████▓[/] [#e10600]▒▓[/]       [#e10600]▓▒[/] [#e10600]▓██████▓[/] [#f5f5f5]▓██▓[/]
+                  [#f5f5f5]█▓[/] [#e10600]▒▓███████▓███▒[/] [#e10600]██[/] [#e10600]▓█[/] [#e10600]▒███▓████████[/]  [#f5f5f5]▓█▒[/]
+                  [#f5f5f5]▓█[/]  [#e10600]▓▓▓████▓██▓[/]   [#e10600]█████[/]   [#e10600]▒██▓█████▓█▓[/] [#f5f5f5]█▓[/]
+                   [#f5f5f5]▓█[/] [#e10600]████▓[/]    [#e10600]▒██▒███████▒██▒[/]    [#e10600]▓████[/] [#f5f5f5]▓▓[/]
+                    [#f5f5f5]▓▓[/] [#e10600]█████[/] [#e10600]▒████▓████████▓███▓[/] [#e10600]█████[/] [#f5f5f5]▓▓[/]
+                     [#f5f5f5]▒▒[/] [#e10600]████▓████▓█████████▓████▓▓███[/]  [#f5f5f5]▒[/]
+                         [#e10600]██▒████▒[/] [#e10600]▓████████[/] [#e10600]▒▓███▒██[/]
+                            [#e10600]▒[/]   [#e10600]▒[/]  [#e10600]▓█████▓[/]      [#e10600]▒[/]
+                             [#e10600]▒██▓[/]  [#e10600]█▓▓▓▒██[/]
+                             [#e10600]▓███▓[/]  [#e10600]█████▓[/]
+                              [#e10600]▓██▓[/]   [#e10600]▓██▓███[/]
+                             [#f5f5f5]▒[/][#e10600]▒████[/]    [#e10600]▓████▒[/]  [#f5f5f5]▒[/]
+                             [#f5f5f5]▒▓[/]  [#e10600]▓█▓█▓[/] [#e10600]▓███▓[/]  [#f5f5f5]▓▒[/]
+                               [#f5f5f5]▓▓[/] [#e10600]▓███▒███▓[/] [#f5f5f5]▓▓[/]
+                                [#f5f5f5]▒█▓[/] [#e10600]▓█▓█▓[/] [#f5f5f5]▒█▓[/]
+                                  [#f5f5f5]▓█▓[/]   [#f5f5f5]▒█▓[/]
+                                   [#f5f5f5]▒██▓██▒[/]
+                                     [#f5f5f5]▒█▒[/]
+'''
+
+HERO_PLAIN = r'''
+                      ▒▓▓▒▒ ▓█████▓       ▓█████▒ ▒▓▓▓▒
+                   ▓██▓ ▒██████▓ ▒▓       ▓▒ ▓██████▓ ▓██▓
+                  █▓ ▒▓███████▓███▒ ██ ▓█ ▒███▓████████  ▓█▒
+                  ▓█  ▓▓▓████▓██▓   █████   ▒██▓█████▓█▓ █▓
+                   ▓█ ████▓    ▒██▒███████▒██▒    ▓████ ▓▓
+                    ▓▓ █████ ▒████▓████████▓███▓ █████ ▓▓
+                     ▒▒ ████▓████▓█████████▓████▓▓███  ▒
+                         ██▒████▒ ▓████████ ▒▓███▒██
+                            ▒   ▒  ▓█████▓      ▒
+                             ▒██▓  █▓▓▓▒██
+                             ▓███▓  █████▓
+                              ▓██▓   ▓██▓███
+                             ▒▒████    ▓████▒  ▒
+                             ▒▓  ▓█▓█▓ ▓███▓  ▓▒
+                               ▓▓ ▓███▒███▓ ▓▓
+                                ▒█▓ ▓█▓█▓ ▒█▓
+                                  ▓█▓   ▒█▓
+                                   ▒██▓██▒
+                                     ▒█▒
+'''
+
+LOGO = r'''
+           [#e10600]▓▒[/]   [#e10600]▓[/]
+      [#f5f5f5]▒▓[/][#e10600]▓███▓▒▓▒████[/][#f5f5f5]▒▓[/]
+       [#f5f5f5]▓[/][#e10600]██▓██████▓██▒[/][#f5f5f5]▒[/]
+         [#e10600]▓▓█▓███▓█▓▒[/]
+           [#e10600]█▓██▓[/]
+           [#e10600]▓█▓▓█▒[/]
+            [#f5f5f5]▓[/][#e10600]▓▓[/][#f5f5f5]▓▒[/]
+             [#f5f5f5]▒▓[/]
+'''
+
+LOGO_PLAIN = r'''
+           ▓▒   ▓
+      ▒▓▓███▓▒▓▒████▒▓
+       ▓██▓██████▓██▒▒
+         ▓▓█▓███▓█▓▒
+           █▓██▓
+           ▓█▓▓█▒
+            ▓▓▓▓▒
+             ▒▓
+'''
+

javis/budget.py

@@ -0,0 +1,17 @@
+"""Run budget — so a thrashing weak model can't burn unbounded tokens (non-negotiable #7)."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass
+class Budget:
+    max_steps: int = 40
+    used: int = 0
+
+    def tick(self) -> None:
+        self.used += 1
+
+    def exhausted(self) -> bool:
+        return self.used >= self.max_steps

javis/builtin_marketplace/code-review/agents/reviewer.md

@@ -0,0 +1,9 @@
+---
+description: Focused code reviewer — finds defensible defects in a diff or file and grades severity.
+model: opus
+---
+You are a precise code reviewer. Given a diff or a file, surface only defects you can defend from the
+code itself: logic errors, unhandled edge cases, security issues, and broken invariants. For each one
+give `file:line`, the reason it is wrong, and the smallest fix. Rank findings by severity and finish
+with a verdict — APPROVE, APPROVE-WITH-NITS, or REQUEST-CHANGES. Never pad the list to seem thorough;
+a short, correct review beats a long, speculative one.

javis/builtin_marketplace/code-review/commands/review.md

@@ -0,0 +1,16 @@
+---
+description: Review the staged diff (or a given path) for correctness, security, and regressions.
+---
+Review the code changes for **correctness, security, and regressions** — be specific and cite `file:line`.
+
+Target: $ARGUMENTS
+(If that is empty, review the staged diff: `git diff --cached`.)
+
+Do this:
+1. If a path was given, read it; otherwise inspect the staged diff.
+2. Find concrete defects, ordered by severity — logic errors, unhandled edge cases, security issues
+   (injection, path traversal, leaked secrets), and broken invariants or missing tests.
+3. For each finding give: the location, why it is wrong, and the smallest fix.
+4. End with a one-line verdict: APPROVE, APPROVE-WITH-NITS, or REQUEST-CHANGES.
+
+Report only what you can defend from the code. Do not invent issues to look thorough.

javis/builtin_marketplace/code-review/plugin.json

@@ -0,0 +1,4 @@
+{
+  "name": "code-review",
+  "description": "Diff-aware code review — a strong-tier reviewer agent and a /review command."
+}

javis/builtin_marketplace/commit/commands/commit.md

@@ -0,0 +1,13 @@
+---
+description: Draft a Conventional-Commits message from the staged diff.
+---
+Write a commit message for the currently staged changes.
+
+1. Read the staged diff: `git diff --cached`. If nothing is staged, say so and stop.
+2. Summarise the *intent* of the change, not a file-by-file list.
+3. Format as Conventional Commits: `type(scope): subject` (subject ≤72 chars), a blank line, then
+   1–3 short body bullets if the change warrants explanation. Types: feat, fix, refactor, docs, test,
+   chore, perf.
+4. Output only the commit message, ready to paste — no preamble, no fences.
+
+Extra context from the user (optional): $ARGUMENTS

javis/builtin_marketplace/commit/plugin.json

@@ -0,0 +1,4 @@
+{
+  "name": "commit",
+  "description": "Draft a Conventional-Commits message from the staged diff."
+}

javis/builtin_marketplace/explain/agents/explainer.md

@@ -0,0 +1,7 @@
+---
+description: Explains code clearly and accurately, grounded in the actual source.
+tier: cheap
+---
+You explain code for someone who is about to modify it. Read the target first, then cover its purpose,
+the main control flow, edge cases, and risks — each grounded in a `file:line` you actually read. Be
+concise and concrete. If something cannot be determined from the code, say so rather than guessing.

javis/builtin_marketplace/explain/commands/explain.md

@@ -0,0 +1,15 @@
+---
+description: Explain a file or symbol — intent, control flow, edge cases, and risks.
+---
+Explain the target so a new contributor could safely change it.
+
+Target: $ARGUMENTS
+(A path, or a symbol name to locate first.)
+
+Cover, briefly:
+1. **Purpose** — what it is for and where it is used.
+2. **Flow** — the key path through the code, step by step.
+3. **Edge cases & failure modes** — inputs or states that need care.
+4. **Risks** — anything surprising, fragile, or easy to break.
+
+Quote `file:line` for each claim. Read the code before explaining it; do not guess.

javis/builtin_marketplace/explain/plugin.json

@@ -0,0 +1,4 @@
+{
+  "name": "explain",
+  "description": "Explain a file or symbol — intent, control flow, edge cases, and risks."
+}

javis/builtin_marketplace/test-author/agents/test-author.md

@@ -0,0 +1,8 @@
+---
+description: Writes focused, regression-catching tests that match the project's conventions.
+model: sonnet
+---
+You write tests that catch real regressions. Read the target to infer its contract, mirror the
+project's existing test framework and style, and cover the happy path, the key edge cases, and a
+failure case. Keep every test deterministic and independent — no network, no sleeps; use temp dirs and
+fixtures. Prefer a few sharp tests over many shallow ones, and name the file each test should live in.

javis/builtin_marketplace/test-author/commands/test.md

@@ -0,0 +1,12 @@
+---
+description: Generate focused, runnable tests for a target file or function.
+---
+Write tests for: $ARGUMENTS
+
+1. Read the target and infer its contract — inputs, outputs, error paths, and invariants.
+2. Match the project's existing test framework and conventions (look at the nearest tests first).
+3. Cover the happy path, the important edge cases, and at least one failure/error case.
+4. Make every test deterministic and independent — no network, no sleeps; use fixtures and temp dirs.
+5. Output runnable test code, and name the file it should live in.
+
+Prefer a few sharp tests that would actually catch a regression over many shallow ones.

javis/builtin_marketplace/test-author/plugin.json

@@ -0,0 +1,4 @@
+{
+  "name": "test-author",
+  "description": "Generate focused, regression-catching tests aligned with JAVIS's test gate."
+}

javis/caching.py

@@ -0,0 +1,39 @@
+"""Optional prompt-cache markers (provider-agnostic via litellm).
+
+When enabled, marks the stable prefix (the system message) with a `cache_control` breakpoint.
+litellm applies it for providers that support explicit prompt caching (Anthropic, Bedrock,
+DeepSeek, …) and ignores it elsewhere — JAVIS never branches on provider. Off by default;
+opt in (`--cache`) only when your tier's provider benefits. Non-mutating: returns a new list.
+"""
+
+from __future__ import annotations
+
+_BREAKPOINT = {"type": "ephemeral"}
+
+
+def _as_cached_blocks(content):
+    if isinstance(content, str):
+        return [{"type": "text", "text": content, "cache_control": _BREAKPOINT}]
+    if isinstance(content, list):
+        blocks = [dict(b) if isinstance(b, dict) else b for b in content]
+        for block in reversed(blocks):
+            if isinstance(block, dict) and block.get("type") == "text":
+                block["cache_control"] = _BREAKPOINT
+                break
+        return blocks
+    return content
+
+
+def apply_cache_control(messages: list[dict]) -> list[dict]:
+    """Return messages with a cache_control breakpoint on the first system message."""
+    out: list[dict] = []
+    marked = False
+    for msg in messages:
+        if not marked and msg.get("role") == "system":
+            new = dict(msg)
+            new["content"] = _as_cached_blocks(msg.get("content"))
+            out.append(new)
+            marked = True
+        else:
+            out.append(msg)
+    return out

javis/catalog.py

@@ -0,0 +1,68 @@
+"""OpenRouter model catalog — pick tool-capable / cheap models instead of guessing slugs.
+
+The OpenRouter models API lists every model with its `supported_parameters` and pricing. We
+fetch it best-effort (cached to a file) and expose pure filters, so we stop guessing slugs (we
+hit 'no endpoints found' / 'no tool use' live). OpenRouter-specific by design — it's our routing
+layer, not provider lock-in.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+import time
+import urllib.request
+
+CATALOG_URL = "https://openrouter.ai/api/v1/models"
+_CACHE = os.path.join(tempfile.gettempdir(), "javis_models.json")
+_TTL = 86400  # 1 day
+
+
+def fetch_catalog(force: bool = False) -> list[dict]:
+    """Return the OpenRouter model list (cached for a day). Best-effort; needs network."""
+    if not force and os.path.isfile(_CACHE) and (time.time() - os.path.getmtime(_CACHE)) < _TTL:
+        try:
+            with open(_CACHE) as f:
+                return json.load(f)
+        except (OSError, json.JSONDecodeError):
+            pass
+    req = urllib.request.Request(CATALOG_URL, headers={"User-Agent": "javis"})
+    with urllib.request.urlopen(req, timeout=20) as resp:
+        data = json.load(resp)["data"]
+    try:
+        with open(_CACHE, "w") as f:
+            json.dump(data, f)
+    except OSError:
+        pass
+    return data
+
+
+def _price(model: dict) -> float:
+    return float((model.get("pricing") or {}).get("prompt") or 0.0)
+
+
+def tool_capable(models: list[dict]) -> list[dict]:
+    return [m for m in models if "tools" in (m.get("supported_parameters") or [])]
+
+
+def is_tool_capable(model_id: str, models: list[dict]) -> bool:
+    mid = model_id.removeprefix("openrouter/")
+    return any(
+        m.get("id") == mid and "tools" in (m.get("supported_parameters") or []) for m in models
+    )
+
+
+def cheapest_tool_capable(models: list[dict], n: int = 15) -> list[tuple[float, str]]:
+    return sorted((_price(m), m["id"]) for m in tool_capable(models))[:n]
+
+
+def main() -> None:
+    models = fetch_catalog()
+    print(f"{len(tool_capable(models))} tool-capable of {len(models)} models\n")
+    for price, mid in cheapest_tool_capable(models, 20):
+        print(f"  ${price * 1e6:7.3f}/Mtok  openrouter/{mid}")
+
+
+if __name__ == "__main__":
+    main()