Nexus (hackathon stack)

What this repo is

• Backend: backend/ FastAPI. Agent loop: backend/app/tinyfish_runner.py (run_agent_for_session, run_live_agent, two-phase _run_two_phase_live).
• Redis: backend/app/redis_client.py — sessions, papers, streams, crawl logs, timeline, run incidents (append_run_incident / read_run_incidents).
• Realtime GraphQL: Cosmo Router + EDFS over Redis; schema in router/subgraphs/research.graphql.
• Frontend: frontend/ Vite + React; force graph src/components/graph/ForceGraph.tsx.

Session start & URLs

• POST /sessions in backend/app/routers/sessions.py — seedUrl optional; default seed for topic substring "ai chip supply chain" is configured there and in frontend/src/components/HomeLanding.tsx.
• Two-phase live: Phase 1 calls discover_web_urls (backend/app/discovery.py). Search hits exclude built-in hosts (e.g. deloitte.wsj.com, bain.com) and DISCOVERY_EXCLUDE_HOSTS (comma-separated). The session seed is prepended to the discovered URL list (deduped) so extraction starts from the chosen page first.
• Single-phase: Agent runs only on seedUrl.

Final report & blocked runs

• GET /sessions/{id}/final-report builds from read_session_papers (canonical papers in Redis), not raw graph text.
• On TinyFish COMPLETE, empty/blocked outcomes append to Redis incidents; emptyReason and markdown ## Extraction issues reflect them. Modal shows full markdown when empty.

Normalization & findings bug class

• normalize_paper_record in backend/app/normalization.py must treat keyFindings (and references/citedBy) as a string vs list via _coerce_flexible_string_list — never iterate a string per-character into list fields.
• paper_to_entity_claims in backend/app/parsers.py repairs legacy single-character keyFindings lists for UI “Findings”.

Embeddings / semantic context

• Vectors index in backend/app/context_engine.py; index_context_document runs from upsert_canonical_paper after a paper exists. Requires EMBEDDING_API_KEY, REDIS_VECTOR_ENABLED, Redis Stack, and EMBEDDING_DIMENSION matching the embedding model. No stored papers ⇒ no vectors.

Graph layout

• frontend/src/components/graph/ForceGraph.tsx: forceLink uses fixed distance(80) and strength(0.4); links are visually directed (markerEnd arrow) but physics is symmetric between endpoints.

Publishing to Shipables

• Before npx @senso-ai/shipables publish, set author.github in shipables.json to your GitHub username (must match Sign in with GitHub). On each release, bump version in shipables.json and metadata.version in this file’s YAML frontmatter together so they stay aligned.
• After a successful publish, the CLI prints the web URL on codeables.dev — it is always https://codeables.dev/skills/<author.github>/nexus from shipables.json (must match your GitHub username exactly, including case). Do not use a different slug than the CLI prints or you will get 404.
• Install (same slug as URL): npx @senso-ai/shipables install <author.github>/nexus --cursor (add -y to skip prompts). With a global CLI shim, shipables install <author.github>/nexus --cursor is equivalent.

Conventions for agents

• Prefer small, focused diffs; match existing style; do not edit user-attached plan markdown files unless asked.
• When touching normalization or discovery, from the repo root run cd backend && python3 -m pytest so imports resolve against backend/app.
• .env: never commit secrets; document new env vars in code (Settings) when adding config.