Version2.1

.dockerignore

@@ -3,6 +3,7 @@
 venv/
 **/__pycache__/
 *.pyc
+*.egg-info/
 
 # Git
 .git
@@ -13,20 +14,38 @@ node_modules
 src/website/node_modules
 
 # Local caches and data
+.env
+**/.env
 .cache
 .hypothesis
 .coverage
 secrets
 
-# Project data directories
+# Project data directories (and database dumps written by the backup service)
+backups/
 Data
 .data
 
 data/
 
+# Build and test outputs. The e2e harness runs on the host; e2e/runs alone
+# used to add ~4 GB to every image.
+build/
+dist/
+e2e/runs/
+e2e/.cache/
+e2e/.venv/
+e2e/.browser-venv/
+**/.pytest_cache
+**/.ruff_cache
+
 # Docker files
 Dockerfile*
 docker-compose*.yml
 
+# Development-only scripts (e.g. the guarded research-study seeder) must never
+# be baked into the server image.
+scripts/dev/
+
 # OS
 .DS_Store

.env.example

@@ -0,0 +1,179 @@
+# Example environment variables for the agent subsystem.
+#
+# PLACEHOLDER VALUES ONLY — never commit a real credential to this file.
+# Copy the entries you need into your own `.env` (which is gitignored for real
+# values) and fill them in there.
+#
+# This file documents only the agent-specific variables added by the agent
+# subsystem. See README.md for the base platform's configuration (database,
+# Redis, Celery, email, model serving).
+
+
+# ─── Upstream LLM provider ───────────────────────────────────────────────────
+#
+# Per merge decision 6 there is no hardcoded provider. Each `agent_profile` row
+# names its own `base_url` + `api_key_ref` + `model`, and the only requirement
+# is that the endpoint speaks the OpenAI-compatible chat-completions wire
+# format. Ollama, Groq, OpenRouter, vLLM and OpenAI all qualify.
+#
+# Keys are NEVER stored in the database. A profile stores `api_key_ref`, the
+# *name* of an environment variable, and the key is read from the environment
+# at request time — so dumping the profile table cannot leak a credential.
+
+# Fallback upstream, used when a profile leaves `base_url` empty.
+# Defaults to a local Ollama instance, which needs no key and costs nothing.
+AGENT_UPSTREAM_BASE_URL=http://localhost:11434/v1
+
+# Fallback API key, used when a profile leaves `api_key_ref` empty.
+# Safe to leave blank for local providers that don't authenticate.
+AGENT_UPSTREAM_API_KEY=
+
+# Per-provider keys. Create one variable per provider you use and point the
+# matching profile's `api_key_ref` at its name. The seeded default profiles
+# reference OLLAMA_API_KEY, AGENT_UPSTREAM_API_KEY and OPENAI_API_KEY.
+OLLAMA_API_KEY=
+OPENAI_API_KEY=your_openai_api_key_here
+GROQ_API_KEY=your_groq_api_key_here
+OPENROUTER_API_KEY=your_openrouter_api_key_here
+
+
+# ─── Codex Responses API ─────────────────────────────────────────────────────
+#
+# Codex speaks OpenAI's proprietary Responses API rather than chat-completions,
+# so it is handled as a special-cased normalization path. When a Codex profile
+# targets a non-OpenAI base_url, the proprietary fields are rewritten; when it
+# targets OpenAI, the payload is forwarded largely as-is.
+
+# Optional operator override for reasoning effort, e.g. to cap cost.
+# Valid values: low | medium | high. Leave blank to let Codex decide (with a
+# clamp applied for models that reject its default).
+AGENT_REASONING_EFFORT=
+
+# Optional positive output-token cap for Codex Responses requests routed to a
+# non-OpenAI provider. Leave blank to preserve the agent's requested budget.
+AGENT_RESPONSES_MAX_OUTPUT_TOKENS=
+
+# ─── Research inference gateway and participant budgets ──────────────────────
+#
+# Goose and built-in study arms spend from the study's provider connection
+# (the env var named by its `secret_ref`) through a metered relay. Every call
+# reserves its worst-case cost before it is forwarded and settles the actual
+# usage afterwards. Defaults are conservative; all values are optional.
+
+# Global per-call output cap (tokens); the injected max_tokens never exceeds it.
+INFERENCE_OUTPUT_TOKEN_CEILING=8192
+# Below this affordable output cap a call is refused (402) instead of sent.
+INFERENCE_MIN_OUTPUT_TOKENS=256
+# Multiplier on the byte-based prompt estimate (>= 1.0).
+INFERENCE_INPUT_ESTIMATE_SAFETY=1.5
+# Estimator constants.
+INFERENCE_INPUT_BYTES_PER_TOKEN=3
+INFERENCE_PER_MESSAGE_TOKEN_OVERHEAD=4
+# A hold older than this is charged in full by the next reservation (seconds).
+INFERENCE_RESERVATION_DEADLINE_SECONDS=900
+# Wall-clock cap on one streamed response (seconds; keep below the deadline
+# minus the 120 s upstream timeout).
+INFERENCE_STREAM_TOTAL_TIMEOUT_SECONDS=600
+# Lifetime of the inference capability handed to Goose (seconds). Goose reads
+# it once per process; liveness, budget and revocation are re-checked per call.
+INFERENCE_CAPABILITY_TTL_SECONDS=604800
+# The metered relay paths get a per-IP floor of 20000 requests/hour unless
+# MAX_REQUEST_RATE_PER_HOUR_CONFIG names them, e.g.
+# MAX_REQUEST_RATE_PER_HOUR_CONFIG={"/api/research/inference/v1/chat/completions": 50000}
+
+
+# ─── Production inventory (docker-compose.prod.yml) ──────────────────────────
+#
+# The application reads `.env` through `env_file`; the compose file additionally
+# asserts the secrets below with `${VAR:?}` so `docker compose up` fails fast
+# instead of a participant discovering a dead research plane. Everything the
+# backend requires (no default in Code4meV2Config) is listed; values here are
+# placeholders.
+
+# --- Secrets the research plane cannot run without --------------------------
+# HMAC key for bootstrap manifests and session/inference capabilities. Read at
+# request time; a missing/blank value makes every bootstrap answer 503 and the
+# server refuses to start (except under TEST_MODE). Generate with:
+#   python3 -c 'import secrets; print(secrets.token_urlsafe(48))'
+BOOTSTRAP_SIGNING_SECRET=replace-with-a-long-random-secret
+# Redis `requirepass` (auth tokens, sessions, ACP grants live there).
+REDIS_PASSWORD=replace-with-a-long-random-password
+# The https:// origin participants use; becomes CORS_ALLOWED_ORIGINS and the
+# website's compiled backend host (the same origin, nginx proxies /api/).
+PUBLIC_ORIGIN=https://study.example.org
+
+# --- Database / cache / broker (compose overrides the hosts and ports) -------
+DB_NAME=code4meV2
+DB_USER=postgres
+DB_PASSWORD=replace-me
+DB_POOL_SIZE=10
+DB_MAX_OVERFLOW=20
+DB_POOL_TIMEOUT=30
+DB_POOL_RECYCLE=1800
+# Host port Postgres is bound to on 127.0.0.1 (backups, psql); never public.
+DB_HOST_PORT=5432
+# Only used outside compose (the compose file sets the container hosts/ports).
+DB_HOST=localhost
+DB_PORT=5432
+REDIS_HOST=localhost
+REDIS_PORT=6379
+CELERY_BROKER_HOST=localhost
+CELERY_BROKER_PORT=6379
+
+# --- Server ------------------------------------------------------------------
+SERVER_HOST=0.0.0.0
+SERVER_PORT=8008
+SERVER_VERSION_ID=1
+# Uvicorn workers; assignment/session/receipt authority lives in Postgres.
+CODE4ME_WEB_WORKERS=2
+# Comma-separated proxies whose X-Forwarded-For is trusted (rate limiting and
+# uvicorn); the compose sets "*" because only nginx can reach the backend.
+FORWARDED_ALLOW_IPS=127.0.0.1
+# Secure cookies (set by the compose; keep false for plain-HTTP local stacks).
+COOKIE_SECURE=false
+# Grace after a session ended during which its late events are still stored.
+TELEMETRY_LATE_EVENT_GRACE_SECONDS=900
+# Serve the classic completion/chat rows (provider-backed by default).
+CLASSIC_MODELS_ENABLED=true
+PRELOAD_MODELS=false
+
+# --- Tokens / rate limits ----------------------------------------------------
+AUTHENTICATION_TOKEN_EXPIRES_IN_SECONDS=86400
+SESSION_TOKEN_EXPIRES_IN_SECONDS=86400
+EMAIL_VERIFICATION_TOKEN_EXPIRES_IN_SECONDS=86400
+RESET_PASSWORD_TOKEN_EXPIRES_IN_SECONDS=900
+TOKEN_HOOK_ACTIVATION_IN_SECONDS=60
+# Per client (real address behind nginx) per path per hour. Research-plane
+# paths (sessions, telemetry batches, bootstrap) and the inference relay get a
+# 20000/h floor regardless; override a path with MAX_REQUEST_RATE_PER_HOUR_CONFIG.
+DEFAULT_MAX_REQUEST_RATE_PER_HOUR=1000
+MAX_REQUEST_RATE_PER_HOUR_CONFIG={}
+
+# --- Email (verification / password reset) -----------------------------------
+EMAIL_HOST=smtp.example.org
+EMAIL_PORT=587
+EMAIL_USERNAME=noreply@example.org
+EMAIL_PASSWORD=replace-me
+EMAIL_USE_TLS=true
+EMAIL_FROM=noreply@example.org
+VERIFICATION_URL=https://study.example.org/verify
+RESET_PASSWORD_URL=https://study.example.org/reset-password
+
+# --- Website / misc required by the configuration model ----------------------
+WEBSITE_HOST=website
+WEBSITE_PORT=80
+# Required by the config model even when pgAdmin is not deployed.
+PGADMIN_HOST=localhost
+PGADMIN_PORT=5050
+PGADMIN_DEFAULT_EMAIL=admin@example.org
+PGADMIN_DEFAULT_PASSWORD=replace-me
+
+# --- Backups (backup service) ------------------------------------------------
+BACKUP_DIR=./backups
+BACKUP_RETENTION_DAYS=14
+BACKUP_INTERVAL_SECONDS=86400
+# Optional off-host copy, run with the dump path as $1, e.g.
+#   rclone copy "$1" remote:code4me-backups
+BACKUP_OFFHOST_CMD=
+# Host port for the website/nginx container (80 behind an external TLS edge).
+HTTP_PORT=80