fix: resolve 15 code review findings (5 critical, 10 warnings)

README.md

@@ -113,7 +113,7 @@ thesis research "..." --rag-collection my_papers   # also retrieve from your own
 thesis critique "Social media causes depression because teens spend too much time online"
 thesis verify "10.1038/nature14539"
 thesis papers "transformer attention" --source arxiv --limit 5
-thesis corpus ingest thesis.pdf --title "My Thesis" --discipline cs --year 2024
+thesis corpus thesis.pdf --title "My Thesis" --discipline cs --year 2024
 thesis ingest add paper.pdf --collection my_papers   # add to your RAG corpus
 thesis ingest list
 thesis sessions
@@ -187,3 +187,52 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for the full workflow.
 ## License
 
 [MIT](LICENSE-MIT).
+
+## FastAPI app
+
+The FastAPI app (`apps/api/main.py`) provides an async HTTP interface for programmatic access. Start it with:
+
+```bash
+uvicorn apps.api.main:app --reload
+# or
+make dev
+```
+
+The server starts on `http://localhost:8000` by default. Interactive docs are available at `http://localhost:8000/docs`.
+
+### Endpoints
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/health` | Health check — returns status and pending task count |
+| `POST` | `/tasks/` | Submit a research task (returns `task_id`, status `202`) |
+| `GET` | `/tasks/` | List all tasks with their current status |
+| `GET` | `/tasks/{task_id}` | Poll a task for status and result |
+| `DELETE` | `/tasks/{task_id}` | Remove a completed or failed task |
+
+### Example: submit and poll a task
+
+```bash
+# Submit
+curl -s -X POST http://localhost:8000/tasks/ \
+  -H "Content-Type: application/json" \
+  -d '{"query": "Does retrieval-augmented generation improve factuality?", "discipline": "computer_science", "mode": "balanced"}' \
+| jq .
+# {"task_id": "abc-123", "status": "queued", "created_at": "..."}
+
+# Poll until complete
+curl -s http://localhost:8000/tasks/abc-123 | jq '.status'
+```
+
+**Request fields:**
+
+| Field | Required | Default | Description |
+|-------|----------|---------|-------------|
+| `query` | yes | — | Research question to investigate |
+| `discipline` | no | `general` | Subject area (e.g. `computer_science`, `psychology`) |
+| `topic_summary` | no | same as `query` | One-sentence context for the planner |
+| `existing_knowledge` | no | `""` | What the user already knows |
+| `what_they_need` | no | `""` | Specific output they are looking for |
+| `mode` | no | `balanced` | LLM tier to use: `quality`, `balanced`, or `cheap` |
+
+Tasks run asynchronously in the background. Poll `GET /tasks/{task_id}` until `status` is `complete` or `failed`. The `result` field contains a full `ResearchSession` object in the same shape as the CLI JSON output.

apps/api/main.py

@@ -1,6 +1,7 @@
 import asyncio
 import logging
 import uuid
+from collections import OrderedDict
 from datetime import datetime, timezone
 from typing import Any, Dict, Optional
 
@@ -25,8 +26,11 @@
     version="0.2.0",
 )
 
+_MAX_TASKS = 1000
+
 # In-memory task store: task_id -> {status, result, error, created_at}
-_tasks: Dict[str, Dict[str, Any]] = {}
+_tasks: OrderedDict[str, Dict[str, Any]] = OrderedDict()
+_task_handles: Dict[str, asyncio.Task] = {}
 
 
 class TaskRequest(BaseModel):
@@ -70,6 +74,8 @@ def _make_orchestrator() -> ThesisOrchestrator:
 
 async def _run_task(task_id: str, request: TaskRequest) -> None:
     try:
+        if task_id not in _tasks:
+            return
         _tasks[task_id]["status"] = "running"
         orch = _make_orchestrator()
         rc = ResearchContext(
@@ -80,14 +86,22 @@ async def _run_task(task_id: str, request: TaskRequest) -> None:
             what_they_need=request.what_they_need or "",
         )
         session = await orch.execute(rc)
+        if task_id not in _tasks:
+            return
         _tasks[task_id]["status"] = "complete"
         _tasks[task_id]["result"] = session.model_dump()
         _tasks[task_id]["completed_at"] = datetime.now(timezone.utc).isoformat()
+    except asyncio.CancelledError:
+        return
     except Exception as exc:
         logger.exception("Task %s failed", task_id)
+        if task_id not in _tasks:
+            return
         _tasks[task_id]["status"] = "failed"
         _tasks[task_id]["error"] = str(exc)
         _tasks[task_id]["completed_at"] = datetime.now(timezone.utc).isoformat()
+    finally:
+        _task_handles.pop(task_id, None)
 
 
 @app.get("/health")
@@ -106,7 +120,10 @@ async def submit_task(request: TaskRequest):
         "error": None,
         "completed_at": None,
     }
-    asyncio.create_task(_run_task(task_id, request))
+    while len(_tasks) > _MAX_TASKS:
+        _tasks.popitem(last=False)
+    handle = asyncio.create_task(_run_task(task_id, request))
+    _task_handles[task_id] = handle
     return TaskResponse(task_id=task_id, status="queued", created_at=created_at)
 
 
@@ -142,4 +159,7 @@ async def list_tasks():
 async def delete_task(task_id: str):
     if task_id not in _tasks:
         raise HTTPException(status_code=404, detail=f"Task {task_id!r} not found")
+    handle = _task_handles.pop(task_id, None)
+    if handle and not handle.done():
+        handle.cancel()
     del _tasks[task_id]

core/blackboard/engine.py

@@ -1,5 +1,5 @@
 import uuid
-from datetime import datetime
+from datetime import datetime, timezone
 from typing import Any, Dict, List, Optional
 
 import redis
@@ -34,6 +34,7 @@ def add_entry(
             "critique",
             "citation_audit",
             "corpus_benchmarks",
+            "memory_guidance",
         }
         if entry_type not in allowed_types:
             raise ValueError(f"Invalid entry_type '{entry_type}'. Must be one of {allowed_types}")
@@ -43,7 +44,7 @@ def add_entry(
             entry_type=entry_type,
             content=content,
             metadata=metadata or {},
-            timestamp=datetime.utcnow().isoformat() + "Z",
+            timestamp=datetime.now(timezone.utc).isoformat(),
         )
 
         # Store in Redis as JSON string under session-specific key
@@ -52,9 +53,8 @@ def add_entry(
         return entry
 
     def get_entries_by_type(self, entry_type: str) -> List[BlackboardEntry]:
-        keys = self.redis.keys(f"{self.prefix}*")
         entries = []
-        for k in keys:
+        for k in self.redis.scan_iter(f"{self.prefix}*"):
             data = self.redis.get(k)
             if data:
                 entry = BlackboardEntry.model_validate_json(data)
@@ -63,9 +63,8 @@ def get_entries_by_type(self, entry_type: str) -> List[BlackboardEntry]:
         return sorted(entries, key=lambda x: x.timestamp)
 
     def get_all_entries(self) -> List[BlackboardEntry]:
-        keys = self.redis.keys(f"{self.prefix}*")
         entries = []
-        for k in keys:
+        for k in self.redis.scan_iter(f"{self.prefix}*"):
             data = self.redis.get(k)
             if data:
                 entries.append(BlackboardEntry.model_validate_json(data))

core/corpus/ingest.py

@@ -1,3 +1,4 @@
+import logging
 import re
 import uuid
 from typing import Any, List
@@ -7,6 +8,8 @@
 from core.embeddings import EMBEDDING_MODEL
 from core.schemas import CorpusSection
 
+logger = logging.getLogger(__name__)
+
 SECTION_PATTERNS = [
     (r"(?i)^\s*(?:chapter\s+\d+[.:]\s*)?introduction\s*$", "introduction"),
     (
@@ -231,9 +234,7 @@ def _ingest_raw(
                 ids=ids,
             )
         except Exception as e:
-            import sys
-
-            print(f"[CorpusIngest] add failed: {e}", file=sys.stderr)
+            logger.error("CorpusIngest.add failed: %s", e, exc_info=True)
             raise
 
         return corpus_sections

core/embedding_cache.py

@@ -42,9 +42,9 @@ def _get_cache() -> Any | None:
         logger.debug("diskcache not installed; embedding cache disabled")
         return None
 
-    import os
+    from core.config import get_settings
 
-    cache_dir = os.environ.get("EMBEDDING_CACHE_DIR", "") or _DEFAULT_CACHE_DIR
+    cache_dir = get_settings().embedding_cache_dir or _DEFAULT_CACHE_DIR
     _disk = diskcache.Cache(cache_dir)
     return _disk