Skip to content

CLAUDE.md

Latest commit

 

History

History
110 lines (84 loc) · 5.06 KB

CLAUDE.md

File metadata and controls

110 lines (84 loc) · 5.06 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Current state: blueprint / design phase

The repo has design docs in docs/ and a Python package scaffold in shield/. There is no runnable application yet — the scaffold defines the module structure and interfaces but contains no integration code. Do not invent build/lint/test commands beyond what is in pyproject.toml; the test suite does not exist yet. When you add the first runnable code, also add the corresponding test tooling and update this file with the real commands.

Default constraint until the compliance section of docs/ARCHITECTURE.md is satisfied: synthetic data only. This is an independent build — it must not be wired to any real proprietary pharmacy system.

What Shield is

Shield is a pharmacy terminal automation engine that runs on a separate Ubuntu desktop (the Z840) and drives a pharmacy laptop running RxConnect via hardware only:

  • Pixels in — HDMI output of the pharmacy laptop is captured by a dedicated HDMI capture SBC (TBD) and read by the Z840 engine.
  • Keystrokes out — the Z840 sends typed HID commands over LAN to a Radxa Cubie A5E, which appears as a USB keyboard/mouse to the laptop.
  • No software on the laptop. Zero agents, daemons, or processes on the target machine.

The iOS companion app (already built, outside this repo) connects to the Z840 dashboard for oversight, notifications, and the review queue.

See docs/TOPOLOGY.md for the physical machine layout and connections. See docs/ARCHITECTURE.md for the full system design.

Read these before designing or coding

  • docs/JOB.md — the 10-stage workflow Shield automates.
  • docs/ARCHITECTURE.md — four-subsystem design, Python stack, domain model, testing strategy, security/compliance, repo layout, roadmap.
  • docs/TOPOLOGY.md — physical machines, hardware connections, data-flow.
  • docs/DECISION-ARCHITECTURE.md — how deterministic logic and the LLM divide the work, and the autonomy policy.
  • docs/MODEL-STRATEGY.md — model routing, cost/capability tradeoffs, PHI guardrails.
  • docs/TRAINABILITY.md — how the system learns. Primary path is interactive teaching (teach → attempt → correct, synthetic cases); passive observation is a thin hardening layer; the learning loop handles the long tail.

Architectural invariants (do not violate when adding code)

  1. The LLM never emits a keystroke. It owns what & why (diagnosis, planning, drafting); deterministic code owns how & whether-it's-safe (navigation, HID injection, interlocks). The LLM emits typed intents; the state machine executes them.

  2. plan → execute → verify. Every actuation is preceded by a verified ScreenState read and followed by a re-capture; the engine refuses any intent whose precondition doesn't match the live screen, and re-plans on divergence.

  3. Confidence gate. OCR output is never trusted raw — low-confidence fields are marked uncertain and force human confirmation rather than action.

  4. Facts come from tables, not the model. NCPDP reject codes, formularies, BIN/PCN routing live in the SQLite knowledge base the LLM queries via tools. Never have the LLM recall these from memory (it hallucinates codes).

  5. Autonomy is E2E but earned per-workflow. Goal: close everything closable (target save 5/8 hrs), ≤1 prompt/hour. Run read/research/draft fully autonomous; gate the few dangerous writes hard. Outreach is act-then-notify. A workflow goes autonomous only after passing an eval bar.

  6. PHI stays on the Z840. OCR runs locally; raw pixels and member data do not leave the machine. LLM calls should avoid PHI where possible; PHI-touching calls must go only to BAA-covered endpoints once real data is in play.

  7. Pure-hardware target, no backdoors. HDMI in, USB HID out — like a human with a keyboard. No software agent on the laptop; no API/DB/accessibility bridge to RxConnect.

  8. Learning grows tables/macros, never weights. Solved cases promote into Skill/Fact/Rule stores — not into fine-tuned weights. Teaching is interactive and synthetic-first. The one allowed exception is a perception model (learning to read the UI).

  9. Oversight runs through the iOS companion app. Approvals, notifications, the review queue, and management surface through the companion app (already built outside this repo) — not through a separate web dashboard written here.

Stack

Python 3.11+ · Ubuntu (Z840 engine host)

Concern Library
Screen capture V4L2 / OpenCV (from HDMI SBC) · mss (dev fallback)
OCR pytesseract (Tesseract)
HID output Radxa /dev/hidg0 · pynput (dev fallback)
Web dashboard FastAPI + Uvicorn + WebSocket
LLM routing httpx → OpenRouter
DB / KB SQLite via SQLAlchemy
Domain models Pydantic v2
Structured logging structlog

Git

Work happens on feature branches. Do not push directly to main. Active design branch: docs/topology-and-arch-rewrite.