AGENTS.md

Antigravity Developer & Workspace Instructions (AGENTS.md)

Welcome, Agent! You are continuing work on WitGym — a Case-Based Reasoning Retrieval-Augmented Generation (CBR-RAG) comedy engine built for the HuggingFace Build Small 2026 Hackathon (Track 2).

---

🚨 MANDATORY INSTRUCTION: Read the Durable Memory Bank First

Before you execute any commands, modify any source files, or write any code, you MUST read the detailed project status, architecture breakdown, hardware optimization strategies, and current task plans documented in: 👉 Durable Memory Bank

---

🛠️ Global Developer Constitution Rules

As a world-class AI engineer and strategic partner, you must strictly adhere to the following principles:

1. Grounding & Freshness: Prioritize codebase-grounded research. Do not guess real-time API structures or assume how witgym is loaded. Inspect imports and files.
2. Surgical Precision: Touch only the exact files/lines required. Avoid cleanups or drive-by refactorings of adjacent files.
3. Simplicity First: Deliver the simplest, most direct, and verifiable solutions. No speculative over-engineering.
4. Think Before Acting: Clearly state all context assumptions, outline alternatives, and halt on ambiguous requirements.
5. No Placeholders: Never write placeholders, print logs, or mock data. Everything should be production-grade.

---

💡 Local Project Constraints & Guidelines

• MacBook Unified Memory Constraints:

  • The model is configured as Qwen/Qwen3.5-9B running on Apple Silicon MPS with bfloat16.
  • To prevent RAM consumption spiking over 50 GB, ensure CONTEXT_WINDOW is set conservatively (e.g. 4096 or 8192 tokens) in config.py.
  • Explicitly clear active cache blocks with torch.mps.empty_cache() and run gc.collect() after each inference step.
  • Terminate any running Python processes before starting a run.

• Transcript Homogeneity:

  • Keep dialogues restricted strictly to The Office sitcom content. Avoid Seinfeld or other sitcom scripts.
  • Verify that the index is compiled exclusively from The Office data.

• Closed-Loop Experiments:

  • Execute a comprehensive evaluation loop after every major modification using python -m witgym.main --debug with standard test inputs.
  • Evaluate result brevity, sharpness, humor, and alignment with the retrieved precedents.

• ⚠️ Testing Rule — API Only, Never Local Model:

  • Never load the local Qwen model (27B on MPS) during UI/closed-loop testing. It takes 2–5 minutes to load weights and blocks verification.
  • For UI changes: verify visually via preview_screenshot on the landing page and inject synthetic HTML via preview_eval to test CSS/layout of practice-screen elements.
  • For functional tests requiring inference: use the HF Inference API endpoint, not uv run python app.py waiting for local weights.