feat: add Chicago (Author-Date) and MLA 9th Edition citation styles

Implement full formatting support for Chicago and MLA citation styles
across in-text citations, reference lists, and the generation pipeline.
Wire citation_style parameter through CLI, backend worker, and both
copies of draft_generator. Add 17 tests covering all formatters.

Author: Federico De Ponte

docs/ARCHITECTURE.md

@@ -0,0 +1,60 @@
+# OpenDraft Architecture
+
+## Engine Overview
+
+OpenDraft uses a multi-agent pipeline to generate academic papers. The engine is in `engine/` with a backend copy in `backend/` for the web worker.
+
+### Core Pipeline
+
+```
+CLI / Web API
+  -> generate_draft()
+    -> Scout Agent (research + citations)
+    -> Architect Agent (outline)
+    -> Formatter Agent (style)
+    -> Scribe/Crafter/Enhancer Agents (writing)
+    -> Citation Compiler (replace {cite_XXX} with formatted citations)
+    -> Export (PDF + DOCX)
+```
+
+---
+
+## Citation System
+
+### Components
+
+| Component | File | Purpose |
+|-----------|------|---------|
+| Citation model | `engine/utils/citation_database.py` | `Citation` class, `CitationDatabase`, `CitationStyle` type |
+| Citation compiler | `engine/utils/citation_compiler.py` | In-text formatting, reference list generation, missing citation research |
+| Citation researcher | `engine/utils/api_citations/` | Crossref, Semantic Scholar, Gemini fallback chain |
+
+### Supported Citation Styles
+
+The citation compiler supports four styles, configured via the `CitationStyle` literal type:
+
+- **APA 7th** -- `(Author, Year)` in-text, alphabetical references
+- **IEEE** -- `[N]` numbered in-text, order-of-appearance references
+- **Chicago (Author-Date)** -- `(Author Year)` in-text, alphabetical references
+- **MLA 9th Edition** -- `(Author)` in-text (no year), alphabetical Works Cited
+
+Style is selected in the CLI (`--style` flag or interactive menu) and flows through `generate_draft()` -> `CitationDatabase` -> `CitationCompiler`.
+
+### Citation Flow
+
+1. Scout agent discovers citations via API (Crossref, Semantic Scholar)
+2. Citations stored in `CitationDatabase` with chosen style
+3. Writing agents reference citations as `{cite_001}`, `{cite_002}`, etc.
+4. `CitationCompiler.compile_citations()` replaces placeholders with formatted in-text citations
+5. `CitationCompiler.generate_reference_list()` appends the reference/bibliography section
+
+---
+
+## Entry Points
+
+| Entry Point | File | Notes |
+|-------------|------|-------|
+| CLI (interactive + quick) | `engine/opendraft/cli.py` | `--style` flag for citation style |
+| Backend worker | `backend/worker.py` | Reads from job record, defaults to APA |
+| Web API | `app/app/api/thesis/generate/route.ts` | Citation style not yet exposed |
+| Benchmarks | `benchmark/run_opendraft.py` | Always uses default APA |

docs/CITATION_STYLES_ROADMAP.md

@@ -0,0 +1,59 @@
+# Citation Styles Roadmap
+
+## Overview
+
+Multi-style citation support for the OpenDraft citation compiler. Citations are formatted for both in-text references and full reference lists.
+
+---
+
+## Phase 1: Chicago & MLA (Complete)
+
+**Status:** Complete
+
+**Styles added:**
+- **Chicago (Author-Date)** -- In-text: `(Smith 2023)`, `(Smith and Johnson 2023)`, `(Smith et al. 2023)`
+- **MLA 9th Edition** -- In-text: `(Smith)`, `(Smith and Johnson)`, `(Smith et al.)`
+
+**Files changed:**
+- `engine/utils/citation_compiler.py` -- Formatter methods + dispatch
+- `engine/draft_generator.py` -- `citation_style` parameter, style resolution
+- `backend/draft_generator.py` -- Same as above (backend copy)
+- `backend/worker.py` -- Pass-through from job record
+- `engine/opendraft/cli.py` -- Wire style to `generate_draft()`
+- `tests/test_citation_styles.py` -- 17 tests
+
+**Reference formats supported per source type:** journal, book, conference, report/website, fallback.
+
+**Sorting:** Chicago and MLA reference lists are sorted alphabetically by first author (same as APA).
+
+---
+
+## Phase 2: Harvard & Vancouver (Planned)
+
+**Status:** Not started
+
+- **Harvard** -- Similar to APA but with minor formatting differences
+- **Vancouver** -- Numbered style similar to IEEE, used in medical/biomedical fields
+
+---
+
+## Phase 3: Web API Integration (Planned)
+
+**Status:** Not started
+
+- Expose `citation_style` in the web API route (`app/app/api/thesis/generate/route.ts`)
+- Add `citation_style` column to the database schema
+- Frontend UI for style selection
+
+---
+
+## Supported Styles Summary
+
+| Style | In-Text Format | Reference Sorting | Status |
+|-------|---------------|-------------------|--------|
+| APA 7th | `(Smith, 2023)` | Alphabetical | Shipped |
+| IEEE | `[1]` | Order of appearance | Shipped |
+| Chicago | `(Smith 2023)` | Alphabetical | Shipped |
+| MLA | `(Smith)` | Alphabetical | Shipped |
+| Harvard | TBD | TBD | Planned |
+| Vancouver | TBD | TBD | Planned |

engine/draft_generator.py

@@ -714,6 +714,7 @@ def generate_draft(
     second_examiner: Optional[str] = None,
     location: Optional[str] = None,
     student_id: Optional[str] = None,
+    citation_style: str = "apa",
 ) -> Tuple[Path, Path]:
     """
     Generate a complete academic draft using 19 specialized AI agents.
@@ -737,6 +738,7 @@ def generate_draft(
         second_examiner: Second examiner name
         location: City/location for date line
         student_id: Student matriculation number
+        citation_style: Citation style shorthand ('apa', 'ieee', 'chicago', 'mla')
 
     Returns:
         Tuple[Path, Path]: (pdf_path, docx_path) - Paths to generated draft files
@@ -760,6 +762,11 @@ def generate_draft(
     # STARTUP AND INITIALIZATION
     # ====================================================================
     draft_start_time = time.time()
+
+    # Resolve citation style shorthand to full name
+    style_map = {"apa": "APA 7th", "ieee": "IEEE", "chicago": "Chicago", "mla": "MLA"}
+    resolved_style = style_map.get(citation_style, "APA 7th")
+
     logger.info("="*80)
     logger.info("DRAFT GENERATION STARTED")
     logger.info("="*80)
@@ -1015,7 +1022,7 @@ def progress_callback(message: str, event_type: str) -> None:
             model=model,
             name="Formatter - Apply Style",
             prompt_path="prompts/02_structure/formatter.md",
-            user_input=f"Apply academic formatting:\n\n{architect_output[:2500]}\n\nStyle: APA 7th edition",
+            user_input=f"Apply academic formatting:\n\n{architect_output[:2500]}\n\nStyle: {resolved_style} edition",
             save_to=folders['drafts'] / "00_formatted_outline.md",
             skip_validation=skip_validation,
             verbose=verbose
@@ -1049,7 +1056,7 @@ def progress_callback(message: str, event_type: str) -> None:
 
         citation_database = CitationDatabase(
             citations=scout_citations,
-            citation_style="APA 7th",
+            citation_style=resolved_style,
             draft_language=get_language_name(language).lower()
         )
 

engine/opendraft/cli.py

@@ -666,7 +666,8 @@ def run_interactive():
             author_name=author_name,
             institution=institution,
             department=department,
-            advisor=advisor
+            advisor=advisor,
+            citation_style=style
         )
 
         print()
@@ -919,7 +920,8 @@ def main():
             author_name=args.author,
             institution=args.institution,
             department=args.department,
-            advisor=args.advisor
+            advisor=args.advisor,
+            citation_style=args.style
         )
 
         print()