AI Topic Scout

Turn a plain-language research intent into a self-updating literature workspace. Discover, rank, and maintain a living paper corpus for any AI research topic — driven by Codex, Claude Code, GitHub Copilot, Copilot CLI, or Microsoft scouting-style agents.

---

What it does

1. Intent → contract. Refine natural language into topic.json (include/exclude rules, taxonomy, queries).
2. Discover. Query OpenAlex + expand citation neighborhoods.
3. Rank. Score candidates with an LLM against the topic contract.
4. Curate. Approve into data/papers.json; auto-generate notes + synthesis report.
5. Publish. Interactive HTML dashboard, research gap analysis, agent task manifests.

---

Requirements

• Python 3.9+
• One of: Codex CLI (recommended, no key needed), or OPENAI_API_KEY, or --offline
• Optional: git, a browser for the dashboard

---

Quick start

git clone https://github.com/ginaecho/topic-scout.git
cd topic-scout

make init          # interview → topic.json + role briefs + skills
make scout         # OpenAlex + LLM ranking → data/candidates.json
make review        # inspect the review queue
python3 scripts/accept_candidates.py openalex:W123 openalex:W456
make corpus        # paper notes + reports/research_report.md
make opportunities # research gap analysis
make dashboard     # topic-dashboard.html

Open topic-dashboard.html in a browser when done.

Provider options

make init                                                 # Codex CLI, interactive
python3 scripts/init_topic.py --intent "your topic" --provider api   # OpenAI API
python3 scripts/init_topic.py --offline                   # no LLM
python3 scripts/scout.py --accept-score 8.0               # auto-accept threshold
python3 scripts/scout.py --offline                        # OpenAlex only
QUERY="benchmark X" make scout                            # targeted supplemental query
make reset                                                # wipe generated workspace

---

Starting an agent

Every agent runs the same command surface — pick your runtime:

Agent	Kickoff
Claude Code	cd into the repo. Claude reads AGENTS.md automatically. Say: "Scout papers on ."
Codex CLI	codex in the repo root. Ask it to run make init then follow AGENTS.md.
GitHub Copilot (GHCP)	Open the repo, run make init, then python3 scripts/orchestrate.py emit --mode copilot. Copilot follows data/copilot_tasks.json.
Copilot CLI	gh copilot in the repo. After make init, emit --mode copilot-cli and execute tasks in order.
Microsoft scouting-style	Emit --mode microsoft-scouting; consume data/microsoft-scouting_tasks.json.
Claw / Swarm	Emit --mode claw or --mode swarm; coordinator dispatches roles under agents/.

Full per-agent instructions: AGENTS.md. Active topic contract (generated by make init): TOPIC_AGENTS.md.

---

Scouting for papers or research topics

The scout is topic-scoped. To change topics:

make reset          # clear the generated workspace
make init           # define a new topic
make scout          # discover

To keep the corpus fresh on an existing topic, just re-run make scout — it deduplicates against data/papers.json and appends candidates.

---

Outputs

Artifact	Purpose
topic.json	Topic contract (source of truth)
TOPIC_AGENTS.md	Generated topic-specific agent brief
agents/*.md	Per-role briefs (coordinator, scout, reviewer, …)
data/candidates.json	Ranked review queue
data/papers.json	Accepted corpus + scout history
reports/research_report.md	Synthesis
data/research_opportunities.json	Evidence-backed gaps
topic-dashboard.html	Interactive dashboard
data/{claw,swarm,copilot,copilot-cli,microsoft-scouting}_tasks.json	Runtime manifests

Example workspace: examples/ai-in-hiring-processes/.

---

Testing

make test

---

License

MIT — see LICENSE.