CLAUDE.md

1# NightmareNet — Agent Instructions
2 
3## Project Overview
4 
5NightmareNet is an **Autonomous AI Self-Improvement Platform** using a sleep-inspired training paradigm. It forces neural networks to learn invariant structures through 4-phase cycles: Wake → Dream → Nightmare → Compress.
6 
7**Stack**: Python ≥3.9, PyTorch, Transformers, FastAPI, Next.js 14 (frontend)
8 
9## Repository Structure
10 
11```
12nightmarenet/           # Core Python package
13  api/                  # FastAPI endpoints (app.py, schemas.py)
14  compression/          # Knowledge distillation
15  data/                 # Dataset loading & processing
16  distortions/          # Dream & nightmare distortion engines
17  evaluation/           # Robustness evaluation & metrics
18  training/             # Training loops, DDP, experiment tracking
19  utils/                # Config, early stopping, type hints
20frontend/               # Next.js 14 + Framer Motion + Tailwind
21  src/components/       # React components (cyberpunk UI)
22  src/lib/api.ts        # TypeScript API client
23tests/                  # pytest suite (206+ tests)
24configs/                # YAML training configs
25scripts/                # CLI entry points
26```
27 
28## Critical Build & Test Commands
29 
30```bash
31# Activate venv (ALWAYS use .venv312 — Python 3.12 + CUDA)
32.venv312\Scripts\Activate.ps1       # Windows
33source .venv/bin/activate            # Unix
34 
35# Run all tests
36pytest tests/ -v --tb=short
37 
38# Run specific test module
39pytest tests/test_distortions.py -v
40 
41# Lint (must pass with 0 errors)
42ruff check .
43 
44# Type check
45mypy nightmarenet/
46 
47# Start API server (--env-file ensures .env propagates to reload workers)
48uvicorn nightmarenet.api.app:app --reload --port 8000 --env-file .env
49 
50# Frontend
51cd frontend && npm run dev           # Dev server on :3000
52cd frontend && npm run build         # Production build
53```
54 
55## Code Style & Conventions
56 
57- **Line length**: 100 chars
58- **Ruff rules**: E, F, W, I, N, UP, B (ignore UP007, UP045)
59- **Imports**: isort via ruff — stdlib, third-party, local (alphabetical within groups)
60- **Type hints**: Use `Union[X, Y]` not `X | Y` (Python 3.9 compat)
61- **DO NOT** use `from __future__ import annotations` in any file that uses FastAPI `Body(...)` — it breaks Pydantic v2 at runtime
62- **Docstrings**: Google style, only on public APIs
63- **Error handling**: Raise with context (`raise X from e`), not bare `raise`
64 
65## Architecture Constraints
66 
671. **No `from __future__ import annotations`** in `nightmarenet/api/` — Pydantic v2 + FastAPI incompatibility
682. **Python 3.9 minimum** — no walrus operator assumptions, use `Union[X, Y]` over `X | Y`
693. **Optional deps are optional** — guard imports with try/except: `accelerate`, `wandb`, `tensorboard`
704. **FastAPI Body singletons** — `_DISTORTION_BODY` and `_ROBUSTNESS_BODY` are module-level to avoid B008
715. **CORS** — configured via `NIGHTMARENET_CORS_ORIGINS` env var (default: `*`)
726. **Health** — optional `NIGHTMARENET_HEALTH_TEST_COUNT=1` enables subprocess `pytest --collect-only` in `/api/v1/health` (off by default; avoid in production)
737. **Pipeline registry** — `NIGHTMARENET_MAX_PIPELINE_RUNNERS` caps in-memory runners (default 64); completed runs are evicted first
748. **Next.js proxy** — `frontend/next.config.ts` uses `NEXT_API_REWRITE_URL` for where `/api/`* rewrites; see `frontend/README.md`
75 
76## Testing Requirements
77 
78- **206+ tests passing** — never commit code that reduces the test count
79- Run `pytest` before claiming any task is complete
80- Run `ruff check .` before claiming lint cleanliness
81- Tests live in `tests/` — mirror the package structure
82- Use `monkeypatch` for env vars, never modify `os.environ` directly
83 
84## API Endpoints
85 
86 
87| Method | Path                          | Purpose                                       |
88| ------ | ----------------------------- | --------------------------------------------- |
89| GET    | `/api/v1/health`              | Health check (status, version, tests)         |
90| POST   | `/api/v1/generate/dream`      | Dream distortion `{text, strength, seed}`     |
91| POST   | `/api/v1/generate/nightmare`  | Nightmare distortion `{text, strength, seed}` |
92| POST   | `/api/v1/evaluate/robustness` | Multi-strength eval `{text, strengths[]}`     |
93 
94 
95## Frontend Notes
96 
97- **Framework**: Next.js 14 (App Router), TypeScript, Tailwind CSS v4
98- **Design**: Cyberpunk dark theme — void (#020617), dream (#818CF8), nightmare (#EF4444), neural (#06B6D4)
99- **Animations**: Framer Motion throughout
100- **API client**: `frontend/src/lib/api.ts` — typed client for all 4 endpoints
101- **Key constraint**: Tailwind v4 uses `@theme inline` block, not `tailwind.config.js`
102 
103## Git Workflow
104 
105- Conventional commits: `feat:`, `fix:`, `docs:`, `test:`, `refactor:`, `chore:`
106- Run tests + lint before any commit
107- Keep commits atomic — one concern per commit
108 
109## Known Issues & Gotchas
110 
111- `Accelerator` import is optional — guarded with `Accelerator: Any = None` fallback
112- `evaluator._log_eval()` guards against `self.tracker is None`
113- Rate limiting on API uses `slowapi` — 60 req/min on generate, 10 req/min on evaluate
114 
115<!-- gitnexus:start -->
116# GitNexus — Code Intelligence
117 
118This project is indexed by GitNexus as **NightmareNet** (4310 symbols, 7685 relationships, 161 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.
119 
120> If any GitNexus tool warns the index is stale, run `npx gitnexus analyze` in terminal first.
121 
122## Always Do
123 
124- **MUST run impact analysis before editing any symbol.** Before modifying a function, class, or method, run `gitnexus_impact({target: "symbolName", direction: "upstream"})` and report the blast radius (direct callers, affected processes, risk level) to the user.
125- **MUST run `gitnexus_detect_changes()` before committing** to verify your changes only affect expected symbols and execution flows.
126- **MUST warn the user** if impact analysis returns HIGH or CRITICAL risk before proceeding with edits.
127- When exploring unfamiliar code, use `gitnexus_query({query: "concept"})` to find execution flows instead of grepping. It returns process-grouped results ranked by relevance.
128- When you need full context on a specific symbol — callers, callees, which execution flows it participates in — use `gitnexus_context({name: "symbolName"})`.
129 
130## Never Do
131 
132- NEVER edit a function, class, or method without first running `gitnexus_impact` on it.
133- NEVER ignore HIGH or CRITICAL risk warnings from impact analysis.
134- NEVER rename symbols with find-and-replace — use `gitnexus_rename` which understands the call graph.
135- NEVER commit changes without running `gitnexus_detect_changes()` to check affected scope.
136 
137## Resources
138 
139| Resource | Use for |
140|----------|---------|
141| `gitnexus://repo/NightmareNet/context` | Codebase overview, check index freshness |
142| `gitnexus://repo/NightmareNet/clusters` | All functional areas |
143| `gitnexus://repo/NightmareNet/processes` | All execution flows |
144| `gitnexus://repo/NightmareNet/process/{name}` | Step-by-step execution trace |
145 
146## CLI
147 
148| Task | Read this skill file |
149|------|---------------------|
150| Understand architecture / "How does X work?" | `.claude/skills/gitnexus/gitnexus-exploring/SKILL.md` |
151| Blast radius / "What breaks if I change X?" | `.claude/skills/gitnexus/gitnexus-impact-analysis/SKILL.md` |
152| Trace bugs / "Why is X failing?" | `.claude/skills/gitnexus/gitnexus-debugging/SKILL.md` |
153| Rename / extract / split / refactor | `.claude/skills/gitnexus/gitnexus-refactoring/SKILL.md` |
154| Tools, resources, schema reference | `.claude/skills/gitnexus/gitnexus-guide/SKILL.md` |
155| Index, status, clean, wiki CLI commands | `.claude/skills/gitnexus/gitnexus-cli/SKILL.md` |
156 
157<!-- gitnexus:end -->
158