patientzero 0.1.0__tar.gz

patientzero-0.1.0/.env.example

@@ -0,0 +1,25 @@
+# LLM Providers (set the ones you need)
+OPENAI_API_KEY=
+ANTHROPIC_API_KEY=
+KIMI_API_KEY=your_kimi_api_key_here
+
+# Local LLM (e.g. Ollama)
+LOCAL_LLM_URL=http://localhost:11434
+
+# Active provider: mock | openai | claude | kimi | local
+LLM_PROVIDER=mock
+
+# Model overrides (optional, defaults set in config/settings.py)
+OPENAI_MODEL=gpt-4o
+ANTHROPIC_MODEL=claude-sonnet-4-20250514
+
+# Server
+BACKEND_PORT=8000
+FRONTEND_PORT=5173
+
+# Concurrency (see GET /api/settings)
+MAX_CONCURRENT_SIMULATIONS=5
+MAX_CONCURRENT_OPTIMIZATIONS=1
+
+# Database
+DB_PATH=patientzero.db

patientzero-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,49 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v6
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --extra dev --extra backend
+
+      - name: Run tests
+        run: uv run python -m pytest core/tests/ backend/tests/ -v
+
+  build:
+    runs-on: ubuntu-latest
+    needs: test
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v6
+
+      - name: Build package
+        run: |
+          uv sync --extra dev
+          uv run python -m build
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/

patientzero-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,26 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v6
+
+      - name: Build package
+        run: |
+          uv sync --extra dev
+          uv run python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

patientzero-0.1.0/.gitignore

@@ -0,0 +1,43 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+*.egg
+
+.auriga
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Environment
+.env
+
+# Frontend
+node_modules/
+frontend/dist/
+
+# Database
+*.db
+*.db-wal
+*.db-shm
+*.db-journal
+
+# Data output
+backend/data/
+
+# Simulation logs
+logs/

patientzero-0.1.0/CLAUDE.md

@@ -0,0 +1,50 @@
+# CLAUDE.md
+
+## Project: PatientZero
+
+Simulation system that uses LLM agents to simulate doctor-patient interactions around medical test results. A DoctorAgent explains, a PatientAgent responds, and a JudgeAgent scores comprehension.
+
+## Commands
+
+All commands run from project root (`project/`), not `backend/`.
+
+```bash
+uv sync                                              # install python deps
+uv run uvicorn backend.api.main:app --reload          # run backend
+uv run python -m pytest core/tests/ backend/tests/ -v # run tests
+uv run python -m evaluations.judge.run [--model M]    # run judge evals
+cd frontend && npm install && npm run dev              # run frontend (port 5173)
+```
+
+## Repo Structure
+
+```
+core/           # All domain logic, no FastAPI dependency
+  agents/       # DoctorAgent, PatientAgent, JudgeAgent + prompts.py
+  llm/          # LLMProvider ABC, factory, Mock/OpenAI/ClaudeCLI providers
+  services/     # run_simulation_streaming() orchestration
+  simulation/   # Simulation runner (state machine: run/step/pause/resume/stop)
+  config/       # Settings, personas, 3 scenarios (CBC, HbA1c, Metformin)
+  db/           # SQLite (WAL), schema.sql, queries/{sessions,simulations,evaluations}.py
+  types/        # Dataclasses & enums split across modules, re-exported from __init__
+backend/        # FastAPI routes (chat.py, simulate.py), tests
+evaluations/    # Judge eval harness — hardcoded transcripts, auto-discovered
+frontend/       # React 19 + Vite + TS, Tailwind + shadcn/ui
+```
+
+## Key Patterns
+
+- **LLM models** use `"provider:model"` format (e.g. `"kimi:kimi-k2.5"`). Parsed by `parse_provider_model()` in `core/llm/factory.py`.
+- **Providers**: `mock` (testing), `kimi`, `claude` (via CLI), `openai`, `local`. Factory in `core/llm/factory.py`.
+- **Prompts** are format-string templates in `core/agents/prompts.py` (not a directory).
+- **Simulation** alternates doctor/patient turns via SSE streaming. Service layer in `core/services/simulation.py` handles DB persistence.
+- **API** endpoints all prefixed with `/api`. Routes in `backend/api/routes/`.
+- **Environment**: `.env` at project root. Key vars: `LLM_PROVIDER` (default `mock`), `KIMI_API_KEY`, `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`. See `.env.example`.
+
+## Testing
+
+Tests split by concern:
+- `core/tests/` — domain logic (agents, analysis, db, feedback, generators, llm, simulation). Mirrors `core/` layout.
+- `backend/tests/api/` — FastAPI route tests only.
+
+All use `MockProvider(delay=0)`. Shared fixtures (`db`, `experiment`, `mock_provider`) live in project-root `conftest.py`. The `test_client` fixture lives in `backend/tests/conftest.py`.

patientzero-0.1.0/Dockerfile.test

@@ -0,0 +1,34 @@
+FROM python:3.11-slim
+
+WORKDIR /app
+
+# Install the wheel (built on host, copied in)
+COPY dist/*.whl /tmp/
+RUN pip install /tmp/patientzero-*.whl
+
+# 1. Verify core imports with only the base dependency (python-dotenv)
+RUN python -c "\
+import core; \
+from core.db.database import Database; \
+d = Database(':memory:'); d.init(); \
+print('PASS: core import + schema init')"
+
+# 2. Verify openai is NOT required for core
+RUN python -c "\
+from core.llm.factory import get_provider; \
+p = get_provider('mock'); \
+print('PASS: mock provider works without openai')"
+
+# 3. Install with all extras and verify backend imports
+RUN pip install "/tmp/$(ls /tmp/patientzero-*.whl | head -1 | xargs basename)[all]"
+RUN python -c "\
+from backend.api.main import app; \
+print('PASS: backend app imports')"
+
+# 4. Copy the full source and run the test suite against the installed package
+COPY . /src
+WORKDIR /src
+RUN pip install pytest pytest-asyncio httpx
+RUN python -m pytest core/tests/ backend/tests/ -v
+
+CMD ["echo", "All tests passed"]

patientzero-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Surya Mani, Aaron Tamte, Lile Zhang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

patientzero-0.1.0/PKG-INFO

@@ -0,0 +1,96 @@
+Metadata-Version: 2.4
+Name: patientzero
+Version: 0.1.0
+Summary: A generic framework for LLM-driven patient simulations.
+Author: Surya Mani, Aaron Tamte, Lile Zhang
+License: MIT
+License-File: LICENSE
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Requires-Dist: python-dotenv>=1.0.0
+Provides-Extra: all
+Requires-Dist: fastapi>=0.115; extra == 'all'
+Requires-Dist: openai>=1.0.0; extra == 'all'
+Requires-Dist: pydantic>=2.0.0; extra == 'all'
+Requires-Dist: sse-starlette>=2.0; extra == 'all'
+Requires-Dist: uvicorn>=0.30; extra == 'all'
+Provides-Extra: backend
+Requires-Dist: fastapi>=0.115; extra == 'backend'
+Requires-Dist: pydantic>=2.0.0; extra == 'backend'
+Requires-Dist: sse-starlette>=2.0; extra == 'backend'
+Requires-Dist: uvicorn>=0.30; extra == 'backend'
+Provides-Extra: dev
+Requires-Dist: build>=1.0.0; extra == 'dev'
+Requires-Dist: httpx>=0.27.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Provides-Extra: openai
+Requires-Dist: openai>=1.0.0; extra == 'openai'
+Description-Content-Type: text/markdown
+
+# PatientZero
+
+Explaining Health: How AI Explanation Styles and Interaction Modalities Affect User Comprehension of Medical Information
+
+## Overview
+
+A simulation system that uses LLM-powered agents to simulate doctor-patient interactions around medical test results and evaluate patient comprehension.
+
+## Tech Stack
+
+- **Frontend**: React + Vite + TypeScript, Tailwind CSS, shadcn/ui
+- **Backend**: Python, FastAPI, SQLite
+- **LLM**: Abstracted provider layer (Mock, OpenAI, Claude, Local)
+
+## Project Structure
+
+```
+PatientZero/
+├── core/              # Domain logic (imported by the backend)
+├── frontend/          # React app
+├── backend/           # FastAPI HTTP layer
+└── report.txt         # Research report
+```
+
+## Prerequisites
+
+- Python 3.12+
+- Node.js 20+
+- [uv](https://docs.astral.sh/uv/) (Python package manager)
+
+## Quick Start
+
+1. Clone the repo:
+```bash
+git clone https://github.com/tamteaa/PatientZero.git
+cd PatientZero
+```
+
+2. Set up environment:
+```bash
+cp .env.example .env
+```
+
+3. Install Python deps and start the backend (from the repo root so `core` imports resolve):
+```bash
+uv sync
+uv run uvicorn backend.api.main:app --reload
+```
+
+4. Start the frontend:
+```bash
+cd frontend
+npm install
+npm run dev
+```
+
+5. Open http://localhost:5173
+
+## License
+
+MIT

patientzero-0.1.0/README.md

@@ -0,0 +1,61 @@
+# PatientZero
+
+Explaining Health: How AI Explanation Styles and Interaction Modalities Affect User Comprehension of Medical Information
+
+## Overview
+
+A simulation system that uses LLM-powered agents to simulate doctor-patient interactions around medical test results and evaluate patient comprehension.
+
+## Tech Stack
+
+- **Frontend**: React + Vite + TypeScript, Tailwind CSS, shadcn/ui
+- **Backend**: Python, FastAPI, SQLite
+- **LLM**: Abstracted provider layer (Mock, OpenAI, Claude, Local)
+
+## Project Structure
+
+```
+PatientZero/
+├── core/              # Domain logic (imported by the backend)
+├── frontend/          # React app
+├── backend/           # FastAPI HTTP layer
+└── report.txt         # Research report
+```
+
+## Prerequisites
+
+- Python 3.12+
+- Node.js 20+
+- [uv](https://docs.astral.sh/uv/) (Python package manager)
+
+## Quick Start
+
+1. Clone the repo:
+```bash
+git clone https://github.com/tamteaa/PatientZero.git
+cd PatientZero
+```
+
+2. Set up environment:
+```bash
+cp .env.example .env
+```
+
+3. Install Python deps and start the backend (from the repo root so `core` imports resolve):
+```bash
+uv sync
+uv run uvicorn backend.api.main:app --reload
+```
+
+4. Start the frontend:
+```bash
+cd frontend
+npm install
+npm run dev
+```
+
+5. Open http://localhost:5173
+
+## License
+
+MIT

patientzero-0.1.0/backend/README.md

@@ -0,0 +1,71 @@
+# PatientZero Backend
+
+FastAPI server with SQLite database and abstracted LLM provider layer.
+
+## Setup
+
+```bash
+uv sync
+cp ../.env.example ../.env  # if not done already
+```
+
+## Running
+
+```bash
+uv run uvicorn api.main:app --reload
+
+```
+
+Server runs at http://localhost:8000
+
+## Project Structure
+
+```
+backend/
+├── api/
+│   ├── main.py              # FastAPI app, CORS, lifespan
+│   ├── dependencies.py      # Shared db + provider instances
+│   └── routes/
+│       └── chat.py          # Chat + session endpoints
+├── config/
+│   └── settings.py          # Environment config
+├── db/
+│   ├── database.py          # Database class (SQLite, raw queries)
+│   ├── schema.sql           # Table definitions
+│   └── queries/
+│       └── sessions.py      # Session + turn CRUD
+├── llm/
+│   ├── base.py              # Abstract LLMProvider
+│   ├── mock.py              # Mock provider (testing)
+│   └── factory.py           # Provider factory
+└── pyproject.toml
+```
+
+## API Endpoints
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `POST` | `/api/sessions` | Create a new chat session |
+| `GET` | `/api/sessions` | List all sessions |
+| `GET` | `/api/sessions/{id}` | Get session with turns |
+| `POST` | `/api/chat` | Send message, receive SSE stream |
+
+## LLM Providers
+
+Set `LLM_PROVIDER` in `.env`:
+
+| Provider | Value | Status |
+|----------|-------|--------|
+| Mock | `mock` | Available |
+| OpenAI | `openai` | Planned |
+| Claude | `claude` | Planned |
+| Local | `local` | Planned |
+
+## Database
+
+SQLite with WAL mode. Tables:
+
+- `sessions` — chat sessions (id, title, created_at)
+- `turns` — individual messages (session_id, role, content, turn_number)
+
+Database file is created automatically on first run.

patientzero-0.1.0/backend/api/dependencies.py

@@ -0,0 +1,8 @@
+from core.config.settings import DB_PATH
+from core.db.database import Database
+from core.repositories import RepoSet
+from core.logger import SimulationLogger
+
+db = Database(DB_PATH)
+repos = RepoSet.for_db(db)
+logger = SimulationLogger()

patientzero-0.1.0/backend/api/main.py

@@ -0,0 +1,81 @@
+import logging
+import traceback
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI, Request
+from fastapi.exceptions import HTTPException, RequestValidationError
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import JSONResponse
+
+logger = logging.getLogger("patientzero.api")
+
+from core import Experiment
+from core.config.settings import FRONTEND_URL
+from core.examples.medical.config import MEDICAL_EXAMPLE_CONFIG
+from backend.api.dependencies import db, repos
+from backend.api.routes.agents import router as agents_router
+from backend.api.routes.analysis import router as analysis_router
+from backend.api.routes.chat import router as chat_router
+from backend.api.routes.distributions import router as distributions_router
+from backend.api.routes.experiments import router as experiments_router
+from backend.api.routes.settings import router as settings_router
+from backend.api.routes.simulate import router as simulate_router
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    db.init()
+    if not repos.experiments.list_all():
+        Experiment(MEDICAL_EXAMPLE_CONFIG, repos)
+    yield
+    db.close()
+
+
+app = FastAPI(title="PatientZero", lifespan=lifespan)
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=[FRONTEND_URL],
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+
+@app.exception_handler(HTTPException)
+async def http_exception_handler(request: Request, exc: HTTPException):
+    if exc.status_code >= 400:
+        print(
+            f"\033[33m[{exc.status_code}]\033[0m {request.method} {request.url.path} "
+            f"→ {exc.detail}",
+            flush=True,
+        )
+    return JSONResponse(status_code=exc.status_code, content={"detail": exc.detail})
+
+
+@app.exception_handler(RequestValidationError)
+async def validation_exception_handler(request: Request, exc: RequestValidationError):
+    print(
+        f"\033[33m[422]\033[0m {request.method} {request.url.path} → validation error:\n"
+        f"  {exc.errors()}",
+        flush=True,
+    )
+    return JSONResponse(status_code=422, content={"detail": exc.errors()})
+
+
+@app.exception_handler(Exception)
+async def unhandled_exception_handler(request: Request, exc: Exception):
+    print(
+        f"\033[31m[500]\033[0m {request.method} {request.url.path} → {type(exc).__name__}: {exc}",
+        flush=True,
+    )
+    traceback.print_exc()
+    return JSONResponse(status_code=500, content={"detail": f"{type(exc).__name__}: {exc}"})
+
+
+app.include_router(chat_router, prefix="/api")
+app.include_router(simulate_router, prefix="/api")
+app.include_router(analysis_router, prefix="/api")
+app.include_router(settings_router, prefix="/api")
+app.include_router(experiments_router, prefix="/api")
+app.include_router(distributions_router, prefix="/api")
+app.include_router(agents_router, prefix="/api")

patientzero-0.1.0/backend/api/routes/agents.py

@@ -0,0 +1,24 @@
+from fastapi import APIRouter, HTTPException
+
+from backend.api.dependencies import repos
+
+router = APIRouter()
+
+
+@router.get("/experiments/{exp_id}/agents")
+def get_experiment_agents(exp_id: str):
+    experiment = repos.experiments.get(exp_id)
+    if experiment is None:
+        raise HTTPException(status_code=404, detail="Experiment not found")
+    config = experiment.config
+    return {
+        "agents": [
+            {"name": a.name, "prompt": a.prompt, "model": a.model}
+            for a in config.agents
+        ],
+        "judge": {
+            "rubric": dict(config.judge.rubric),
+            "instructions": config.judge.instructions,
+            "model": config.judge.model,
+        },
+    }