Code graph and memory for your coding agents, in one Rust program. For Claude Code, Codex, Cursor and any MCP client.
Rust agent-memoryai-agentsclaude-codecode-analysiscode-graphcode-intelligencecode-searchcodexcoding-agentscontext-engineeringcursordeveloper-toolsgraphragknowledge-graphlocal-firstmcpmcp-servermodel-context-protocolrusttree-sitter
#!/usr/bin/env python3
"""Graphicle's hosted demo: ask a large repository a question, or point at a pixel of a screenshot.
A thin, read-only web server that runs the `graphicle` binary for each request, `graphicle ask --pack` and
`graphicle pixel`, with fixed arguments and never a shell. Graphicle's own local server (`graphicle serve`,
`graphicle open`) is never exposed: it has write APIs.
Safety and cost:
- a rate limit per client address, kept in memory;
- at most `max_concurrent` model requests at once;
- a daily dollar cap: the spend log's total for the day (UTC) from `graphicle usage`, over every data folder;
the profiles' own `max_cost_per_day` in the models file stays the hard stop;
- at the cap, or with no model key, the curated questions' stored answers are shown, with their recorded cost;
- nothing a visitor sends is logged or kept: a question goes to the binary only, a screenshot is a temporary
file deleted after the call, and the request log has no addresses, questions or answers. The spend log keeps
only its own fields: when, which command and model, the project, tokens, cost and status.
Configuration: the JSON file in DEMO_CONFIG (see demo.example.json). The model key comes from the environment
variable the models file names (MODEL_API_KEY for the Meta Model API), never from the configuration.
"""
import base64
import json
import os
import re
import subprocess
import sys
import tempfile
import threading
import time
from collections import deque
from datetime import datetime, timezone
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
from urllib.parse import urlparse
HERE = os.path.dirname(os.path.abspath(__file__))
MAX_BODY = 12 << 20
MAX_IMAGE = 8 << 20
MAX_QUESTION = 600
STATIC_TYPES = {".html": "text/html; charset=utf-8", ".js": "text/javascript; charset=utf-8",
".css": "text/css; charset=utf-8", ".svg": "image/svg+xml", ".png": "image/png"}
KNOWN_PATHS = {"/", "/healthz", "/api/config", "/api/ask", "/api/pixel", "/app.js", "/style.css"}
SECURITY_HEADERS = {
"Content-Security-Policy": "default-src 'self'; img-src 'self' data: blob:; style-src 'self'; "
"script-src 'self'; connect-src 'self'; frame-ancestors 'none'; base-uri 'none'",
"X-Content-Type-Options": "nosniff",
"Referrer-Policy": "no-referrer",
"X-Frame-Options": "DENY",
"Cache-Control": "no-store",
}
def load_config(path):
with open(path) as f:
return load_config_dict(json.load(f))
def load_config_dict(config):
config = dict(config)
config.setdefault("listen", "0.0.0.0")
config.setdefault("port", 8080)
config.setdefault("binary", "graphicle")
config.setdefault("daily_cap_usd", 10.0)
config.setdefault("max_concurrent", 2)
config.setdefault("per_minute", 3)
config.setdefault("per_day", 30)
config.setdefault("trust_proxy", False)
config.setdefault("timeout_seconds", 300)
config.setdefault("key_env", "MODEL_API_KEY")
config.setdefault("state_dir", tempfile.mkdtemp(prefix="graphicle-demo-"))
for repo in config["repos"]:
for field in ("id", "github", "commit", "data_dir", "project"):
if not repo.get(field):
raise SystemExit(f"repos[].{field} is required")
return config
class Limiter:
"""At most `per_minute` and `per_day` requests for each key (a client address)."""
def __init__(self, per_minute, per_day):
self.per_minute, self.per_day = per_minute, per_day
self.seen = {}
self.lock = threading.Lock()
def allow(self, key, now=None):
now = time.time() if now is None else now
with self.lock:
times = self.seen.setdefault(key, deque())
while times and now - times[0] > 86400:
times.popleft()
last_minute = sum(1 for t in times if now - t < 60)
if last_minute >= self.per_minute:
return False, 60
if len(times) >= self.per_day:
return False, int(86400 - (now - times[0])) + 1
times.append(now)
if len(self.seen) > 100_000: # forget the oldest keys first
for stale in [k for k, v in self.seen.items() if not v or now - v[-1] > 86400]:
del self.seen[stale]
return True, 0
def github_link(repo, path, line=None, end=None):
url = f"https://github.com/{repo['github']}/blob/{repo['commit']}/{path}"
if line:
url += f"#L{line}" + (f"-L{end}" if end and end != line else "")
return url
def image_type(data):
if data.startswith(b"\x89PNG\r\n\x1a\n"):
return ".png"
if data.startswith(b"\xff\xd8"):
return ".jpg"
if data.startswith(b"RIFF") and data[8:12] == b"WEBP":
return ".webp"
if data.startswith(b"GIF87a") or data.startswith(b"GIF89a"):
return ".gif"
return None
def normalized(question):
return re.sub(r"\s+", " ", question.strip().lower())
class Demo:
def __init__(self, config):
self.config = config
self.repos = {r["id"]: r for r in config["repos"]}
self.limiter = Limiter(config["per_minute"], config["per_day"])
self.running = threading.BoundedSemaphore(config["max_concurrent"])
self.spend_cache = (0.0, None)
self.spend_lock = threading.Lock()
curated = config.get("curated")
self.curated = []
if curated and os.path.exists(curated):
with open(curated) as f:
self.curated = json.load(f)
self.last_failure = None
self.paused_until = 0.0
self.home = os.path.join(config["state_dir"], "home")
self.scratch = os.path.join(config["state_dir"], "scratch")
os.makedirs(self.home, mode=0o700, exist_ok=True)
os.makedirs(self.scratch, mode=0o700, exist_ok=True)
# ---- the binary
def env(self):
env = {"PATH": os.environ.get("PATH", "/usr/bin:/bin"), "HOME": self.home, "LANG": "C.UTF-8",
"GRAPHICLE_FRESHNESS": "off", "GRAPHICLE_NO_UPDATE_NOTIFIER": "1",
"GRAPHICLE_NO_BROWSER": "1"}
for name in [self.config["key_env"]] + self.config.get("pass_env", []):
if os.environ.get(name):
env[name] = os.environ[name]
return env
def graphicle(self, repo, args, timeout=None):
argv = [self.config["binary"], "--data-dir", repo["data_dir"]]
if self.config.get("models"):
argv += ["--config", self.config["models"]]
done = subprocess.run(argv + args, capture_output=True, text=True, env=self.env(),
timeout=timeout or self.config["timeout_seconds"], stdin=subprocess.DEVNULL)
if done.returncode != 0:
last = [line for line in done.stderr.strip().splitlines() if line.strip()][-1:] or ["failed"]
self.last_failure = last[0][:500] # for the operator's tests; never logged or sent
raise CallFailed(last[0])
return json.loads(done.stdout)
def live(self):
return (bool(self.config.get("live", True)) and bool(os.environ.get(self.config["key_env"]))
and time.time() >= self.paused_until)
def spent_today(self):
"""The day's spend (UTC) in US dollars over every data folder, from the spend logs."""
with self.spend_lock:
amount, when = self.spend_cache
if when and time.time() - when < 15:
return amount
day = datetime.now(timezone.utc).strftime("%Y-%m-%d")
total = 0.0
for data_dir in sorted({r["data_dir"] for r in self.repos.values()}):
try:
report = self.graphicle({"data_dir": data_dir}, ["usage", "--since", day, "--json"], 60)
total += float(report.get("total", {}).get("cost_usd") or 0.0)
except (CallFailed, subprocess.TimeoutExpired, ValueError):
total = float("inf") # an unreadable log stops live calls
self.spend_cache = (total, time.time())
return total
def budget_left(self):
return self.spent_today() < float(self.config["daily_cap_usd"])
# ---- answers
def stored(self, repo_id, question):
for entry in self.curated:
if entry.get("repo") == repo_id and normalized(entry.get("question", "")) == normalized(question):
return dict(entry, stored=True)
return None
def ask(self, repo, question):
args = ["ask", "--pack", "--project", repo["project"], "--layout", "cache", "--json"]
if self.config.get("ask_profile"):
args += ["--model", self.config["ask_profile"]]
if self.config.get("ask_budget"):
args += ["--budget", str(int(self.config["ask_budget"]))]
report = self.graphicle(repo, args + ["--", question])
citations = [dict(c, url=github_link(repo, c["path"], c.get("line"), c.get("end_line")))
for c in report.get("citations", []) if c.get("valid")]
usage = report.get("usage") or {}
input_tokens = usage.get("input_tokens") or 0
return {"answer": report.get("answer", ""), "citations": citations,
"invalid_citations": report.get("invalid_citations", 0),
"model": report.get("model"), "usage": usage,
"cached_share": round((usage.get("cached_tokens") or 0) / input_tokens, 3) if input_tokens else None,
"pack": pack_makeup(report.get("pack") or {})}
def pixel(self, repo, image, x, y):
suffix = image_type(image)
handle, path = tempfile.mkstemp(suffix=suffix, dir=self.scratch)
try:
with os.fdopen(handle, "wb") as f:
f.write(image)
report = self.graphicle(repo, ["pixel", path, "--at", f"{x},{y}", "--project", repo["project"],
"--json"])
finally:
os.unlink(path)
report.pop("screenshot", None) # it names the temporary file
for c in report.get("candidates", []):
c["url"] = github_link(repo, c["path"], c.get("line"))
for caller in c.get("callers", []):
caller["url"] = github_link(repo, caller["path"], caller.get("line"))
return report
def pack_makeup(pack):
"""What the pack held, in a visitor's words: its layout, files and tokens, the repository part that is the
same for every question (and so cached) and the question part, the budget and the time to pack."""
rows = {}
if pack.get("layout"):
rows["layout"] = pack["layout"]
if isinstance(pack.get("included"), list):
rows["files in the pack"] = len(pack["included"])
tokens, prefix = pack.get("tokens"), pack.get("prefix_tokens")
if isinstance(tokens, int):
rows["tokens in the pack"] = tokens
if isinstance(prefix, int) and prefix > 0:
rows["repository part (the same for every question)"] = prefix
if isinstance(tokens, int):
rows["question part"] = tokens - prefix
if isinstance(pack.get("budget"), int):
rows["budget"] = pack["budget"]
if isinstance(pack.get("seconds"), (int, float)):
rows["packed in"] = f"{pack['seconds']:.1f} s"
return rows
class CallFailed(Exception):
pass
CREDIT_WORDS = ("insufficient", "quota", "credit", "billing", "payment", "402")
def out_of_credits(message):
"""A provider's refusal that says the account cannot pay for more calls."""
lower = message.lower()
return any(word in lower for word in CREDIT_WORDS)
def public_error(message):
"""A binary's error as a visitor may read it: the cap's refusal in plain words, else a generic line."""
if "Refused before sending" in message or "max_cost_per_day" in message:
return "The demo's budget for today is used up."
if "max_cost_per_call" in message:
return "This request would cost more than the demo allows for one call."
return "The request failed. Please try again later."
def make_handler(demo):
class Handler(BaseHTTPRequestHandler):
server_version = "graphicle-demo"
sys_version = ""
def log_message(self, *args): # no addresses, no paths with user text
pass
def log(self, status, started):
path = urlparse(self.path).path
shown = path if path in KNOWN_PATHS else "(other)" # a typed path is visitor text
print(f"{datetime.now(timezone.utc).strftime('%H:%M:%SZ')} {self.command} {shown} {status} "
f"{time.time() - started:.1f}s", flush=True)
def client(self):
if demo.config["trust_proxy"] and self.headers.get("X-Forwarded-For"):
return self.headers["X-Forwarded-For"].split(",")[0].strip()
return self.client_address[0]
def send(self, status, body, content_type="application/json; charset=utf-8", extra=None):
data = body if isinstance(body, bytes) else json.dumps(body).encode()
self.send_response(status)
self.send_header("Content-Type", content_type)
self.send_header("Content-Length", str(len(data)))
for k, v in {**SECURITY_HEADERS, **(extra or {})}.items():
self.send_header(k, v)
self.end_headers()
self.wfile.write(data)
def do_GET(self):
started = time.time()
path = urlparse(self.path).path
status = 200
if path == "/healthz":
self.send(200, {"ok": True})
elif path == "/api/config":
self.send(200, {
"repos": [{"id": r["id"], "github": r["github"], "commit": r["commit"],
"pixel": bool(r.get("pixel"))} for r in demo.repos.values()],
"live": demo.live(), "daily_cap_usd": demo.config["daily_cap_usd"],
"spent_today_usd": round(min(demo.spent_today(), 1e9), 4),
"curated": [{"repo": c["repo"], "question": c["question"], "mode": c.get("mode")}
for c in demo.curated]})
else:
name = "index.html" if path == "/" else path.lstrip("/")
full = os.path.normpath(os.path.join(HERE, "static", name))
if not full.startswith(os.path.join(HERE, "static") + os.sep) or not os.path.isfile(full):
status = 404
self.send(404, {"error": "not found"})
else:
with open(full, "rb") as f:
self.send(200, f.read(), STATIC_TYPES.get(os.path.splitext(full)[1], "text/plain"))
self.log(status, started)
def do_POST(self):
started = time.time()
status, body = self.post()
self.send(status, body, extra={"Retry-After": str(body.get("retry_after"))}
if body.get("retry_after") else None)
self.log(status, started)
def post(self):
path = urlparse(self.path).path
if path not in ("/api/ask", "/api/pixel"):
return 404, {"error": "not found"}
length = int(self.headers.get("Content-Length") or 0)
if length <= 0 or length > MAX_BODY:
return 413, {"error": "The request is too large."}
try:
request = json.loads(self.rfile.read(length))
except ValueError:
return 400, {"error": "The request is not JSON."}
repo = demo.repos.get(request.get("repo"))
if not repo:
return 400, {"error": "Unknown repository."}
if path == "/api/ask":
question = str(request.get("question") or "").strip()
if not 3 <= len(question) <= MAX_QUESTION:
return 400, {"error": f"Ask a question of 3 to {MAX_QUESTION} characters."}
stored = demo.stored(repo["id"], question)
if not demo.live() or not demo.budget_left():
if stored:
return 200, stored
return 503, {"error": "Live answers are paused (no budget left today). The curated "
"questions below have recorded answers.", "paused": True}
else:
if not repo.get("pixel"):
return 400, {"error": "Pixel to code is set up for the vscode repository only."}
try:
x, y = int(request.get("x")), int(request.get("y"))
data = str(request.get("image") or "")
image = base64.b64decode(data.split(",", 1)[-1], validate=True)
except (TypeError, ValueError):
return 400, {"error": "Send a PNG, JPEG, GIF or WebP screenshot and the point."}
if not image_type(image) or len(image) > MAX_IMAGE or x < 0 or y < 0:
return 400, {"error": "Send a PNG, JPEG, GIF or WebP screenshot of at most 8 MB."}
if not demo.live() or not demo.budget_left():
return 503, {"error": "Live calls are paused (no budget left today).", "paused": True}
allowed, retry = demo.limiter.allow(self.client())
if not allowed:
return 429, {"error": "Too many requests from your address; try again later.",
"retry_after": retry}
if not demo.running.acquire(timeout=30):
return 503, {"error": "The demo is busy; try again in a minute.", "retry_after": 60}
try:
if path == "/api/ask":
return 200, demo.ask(repo, question)
return 200, demo.pixel(repo, image, x, y)
except CallFailed as failure:
if out_of_credits(str(failure)):
demo.paused_until = time.time() + 600 # stored answers only for ten minutes
if path == "/api/ask":
stored = demo.stored(repo["id"], question)
if stored:
return 200, stored
return 502, {"error": public_error(str(failure)), "paused": not demo.live()}
except subprocess.TimeoutExpired:
return 504, {"error": "The request took too long."}
finally:
demo.running.release()
with demo.spend_lock:
demo.spend_cache = (0.0, None)
return Handler
def main():
config = load_config(os.environ.get("DEMO_CONFIG", os.path.join(HERE, "demo.json")))
demo = Demo(config)
server = ThreadingHTTPServer((config["listen"], int(config["port"])), make_handler(demo))
server.daemon_threads = True
print(f"graphicle demo on {config['listen']}:{config['port']}, live={demo.live()}, "
f"{len(demo.repos)} repositories, {len(demo.curated)} curated answers", flush=True)
server.serve_forever()
if __name__ == "__main__":
sys.exit(main())