research-hub

research-hub

A local workspace connecting literature, research artifacts, and manuscripts through traceable work.

繁體中文 · Workspace guide · Existing setup · Developer architecture

Workspace merged in source; installed capability must be checked separately. PR #135 is merged. Use the pinned source path below for this baseline; do not infer published-wheel or native-host readiness from the source version. Start with the capability and setup baseline.

Why this exists

Research crosses files and tools: a paper informs a question, an analysis changes a result, and a manuscript needs revision. Keep those connections visible when you or an AI assistant picks up the next task.

Start with local files. Connect Zotero for references, Obsidian for notes, and NotebookLM for source-based briefings when needed. Empirical studies and literature reviews share the workspace.

Start with native literature discovery (Stage 1)

In a native AI agent that can read the research-hub skill and has public search/read tools, start with one request:

Find literature on LLMs simulating human decisions.

The agent should choose a sensible initial scope, search/read available sources, and return a short list with original links, relevance, versions, and reading/access limits—not ask you to fill a research form or write JSON. Zotero, Obsidian, NotebookLM, and Hub storage are optional.

A real cloud-native rehearsal on 2026-10-26 returned three distinct starting points:

• Aher et al. (2023): simulation of group behavior from existing experiments.
• Park et al. (assessed 2024 preprint v1): personalized agents grounded in human interviews; newer versions were not read in this rehearsal.
• Gao et al. (2025): mismatched decision distributions as a validity check. The rehearsal read a DOI-matched public PDF mirror, not a successfully retrieved publisher PDF.

Then, if useful, say:

Focus on economic decisions and compare the human baselines and evaluation methods.

Search snippets are not full-paper reading; human-like outputs are not evidence that human participants can be replaced. The agent retains unavailable sources and unresolved questions rather than inventing coverage.

What was actually exercised: one request → native search and original-text sections → a short, qualified result. This was a cloud-native run after directly reading the skill—not verification of Codex/Claude Code installation, automatic skill triggering, every host, Hub saving, or UI opening. No JSON, CLI, additional integration/provider account, or Stage 2 was required in that rehearsal.

For an optional visual handoff, the agent—not the researcher—can organize observations and use an already available, authorized Hub interface to save them. A confirmed save returns an exact saved-result link. The saved-result contract separates this path from native research: current secure file persistence/viewing is POSIX-only, Windows is not yet supported, and opening a result does not authenticate research or start provider writes.

What you work with

Page	Your work
Project	State the question, goal, and project type.
Literature	Find references and record inclusion or exclusion decisions.
Evidence	Connect claims to sources and inspect unresolved support.
Design & results	Record methods, results, limitations, and supporting files.
Manuscript	Register Word, LaTeX, or Markdown; prepare outlines and revisions.
Review & delivery	Inspect proposals, record decisions, and prepare a local handoff.

Files stay in your selected workspace. Registration records paths and hashes; your editor remains responsible for changing original documents.

How to try it

Workspace preview

Use Python 3.10+ and Git. Choose a new or empty workspace-demo directory. These commands install the immutable source baseline 6381dfa7d474dd27cd4adb33f0f59ea8ec395150 without depending on a feature-branch name.

git clone -c core.autocrlf=false https://github.com/WenyuChiou/research-hub.git
cd research-hub
git fetch origin 6381dfa7d474dd27cd4adb33f0f59ea8ec395150
git checkout --detach 6381dfa7d474dd27cd4adb33f0f59ea8ec395150

Then choose one command block for your system. These call the virtual-environment Python directly: no activation script or PowerShell execution-policy change is needed.

macOS / Linux

python3 -m venv .venv
./.venv/bin/python -m pip install -e .
./.venv/bin/python -m research_hub project demo --root ./workspace-demo --json
./.venv/bin/python -m research_hub serve --workspace --root ./workspace-demo

Windows PowerShell

py -3 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e .
.\.venv\Scripts\python.exe -m research_hub project demo --root ./workspace-demo --json
.\.venv\Scripts\python.exe -m research_hub serve --workspace --root ./workspace-demo

Open the local workspace. The demo needs no account and contains a small numerical summation example and a literature-review fixture. These are teaching inputs, not model-generated research findings.

The pinned runtime snapshot retains older local documentation and does not include this new capability-baseline document or its clean-source tests. Read the current online capability baseline alongside that runtime; tests in this PR are evidence for this changeset, not for the exact older README commands. The snapshot retains its original documentation; use the current workspace guide for the merged producer pin, your own files, writing setup, task handoffs, and review. See dated verification and remaining checks before relying on the preview.

Published literature dashboard

python -m pip install research-hub-pipeline
research-hub dashboard --sample

This account-free sample opens the existing dashboard. For real integrations, use the setup guide, first 10 minutes, and dashboard tour.

How writing works

Mode	What happens
Portable handoff	Export a task for your AI host; import its prose and candidate hashes. Export leaves the task waiting for the agent.
Connected Codex	An authenticated, compatible Codex CLI uses an explicitly trusted public writing bundle to produce prose without tools. Results wait for human review.

The public writing adapter was merged in academic-writing-skills PR #17. This integration pins its immutable main commit bc15e29e976cd6ade3484aeaa4f1230444697f8a. Verify and configure it explicitly; it is optional and is not installed as a permanent research-hub dependency. The Hub workspace is merged in source; this does not establish published-package or native-host readiness. Connected Codex receives bounded text excerpts, not binary document contents. Use your editor for Word formatting, LaTeX compilation, and final document changes.

What you can trust

• Traceable inputs: tasks retain input revisions, results, and decisions. Changed registered bytes can make a task stale; the workspace reports review impact.
• Separate judgments: a resolvable reference does not prove a claim. Source identity, claim support, and human task acceptance remain distinct.
• Explicit handoff: accepted proposals can enter a separately approved local ZIP. This does not authorize publication or cloud upload.

Local approval records an operator's assertion; it does not authenticate identity on a shared computer. Existing direct-write MCP, dashboard, and cloud tools are outside workspace approval protection. The workflow's eight stages do not advance automatically when a task finishes. Read the boundaries and recovery guide.

Existing integrations, credentials, and troubleshooting

Use setup to choose integrations, then run research-hub doctor. NotebookLM needs a visible Google sign-in; its last recorded authentication attempt failed and has not been reverified. Treat that integration as degraded/unchecked until your own check succeeds. See NotebookLM setup and troubleshooting.

Existing persona	Optional extras
Researcher	[playwright,secrets]
Humanities	[playwright,secrets]
Analyst	[import,secrets]
Internal KM	[import,secrets]

These credentials apply to the existing integrations; the local workspace demo needs none.

Name	Required	Purpose
ZOTERO_API_KEY	Zotero only	Zotero API authentication
ZOTERO_LIBRARY_ID	Zotero only	Zotero library identifier
SEMANTIC_SCHOLAR_API_KEY	no	Optional search API key
SEMANTIC_SCHOLAR_RPS	no	Optional search request-rate override
TAVILY_API_KEY	no	Optional web search backend
BRAVE_API_KEY	no	Optional web search backend

Connect through MCP/REST, check the AI host support matrix, or use local file import. The CLI reference, EZproxy guide, and live smoke checklist cover detailed operations.

Developer links

The workspace architecture explains the task ledger and approval boundaries. See the workflow runtime, MCP tools, stable API, file formats, and OpenWiki for technical detail. Use python -m research_hub describe --filter mcp_tools and --filter skills for current inventories.

Earlier dashboard material remains available: MCP flow diagram, recorded dashboard demo, and full-resolution video.

Contributing · Releases · Release process · MIT license