Flow-AI Research IDE

An evidence-grounded spatial workspace that turns papers and notes into a traceable research graph.

OpenAI Build Week 2026 — submission category: Developer Tools Repository: gith1t/Flow-AI

The idea

Research teams need more than an AI summary. They need to know:

• which claims were extracted;
• which exact passage supports each claim;
• how verified claims relate to one another;
• what changed in the workspace over time.

Flow-AI answers these questions in one local-first canvas. AI proposals stay separate from human-approved findings, every finding keeps source evidence, and relationships remain reviewable instead of being invented silently.

What the demo shows

• Import PDF, DOCX, TXT, Markdown, CSV, TSV, JSON, or LOG sources.
• Create a research topic and extract evidence-backed proposals.
• Review confidence scores and exact quotations in the AI Inbox.
• Merge approved facts into a React Flow knowledge graph.
• Discover reviewable relationships that require an exact quotation from both connected findings; incomplete suggestions remain hypotheses.
• Run an on-demand Internal Evidence Check for a verified fact: it rates support from its mapped quotation, flags limitations and concrete rhetorical signals, and clearly marks external verification as not checked.
• Use Context Co-Pilot for targeted questions and hypothesis drafts.
• Group facts, switch Graph/Tree/Timeline/Comparison layouts, and restore previous UI snapshots.
• Download a Markdown report containing verified findings and evidence.

Technology

• React 19, Vite 8, Tailwind CSS, @xyflow/react
• FastAPI, Uvicorn, Pydantic
• OpenAI Python SDK with gpt-5.6-luna
• PDF/DOCX extraction with pypdf and python-docx
• Local persistence in workspace_state.json

Run locally

Requirements: Python 3.10+, Node.js 20.19+ (or 22.12+), and an OpenAI API key with access to the configured model.

Windows — one command

From the repository root:

powershell -ExecutionPolicy Bypass -File .\start-flow-ai.ps1

The launcher creates the backend environment, installs missing dependencies, starts FastAPI on http://localhost:8000, starts Vite on http://localhost:5173, and opens the browser. It stops with a clear message if either port is already occupied, so it never silently opens an older app instance.

For a clean demo session, explicitly reset the local workspace before opening the app:

powershell -ExecutionPolicy Bypass -File .\start-flow-ai.ps1 -FreshWorkspace

Without -FreshWorkspace, existing findings, topics, and Time Travel history are preserved.

Useful options:

.\start-flow-ai.ps1 -NoBrowser
.\start-flow-ai.ps1 -SkipInstall

macOS/Linux — two terminals

Backend:

cd backend
python3 -m venv venv
source venv/bin/activate
python -m pip install -r requirements.txt
python -m uvicorn main:app --reload --port 8000

Frontend:

cd frontend
npm install
npm run dev

Open http://localhost:5173.

OpenAI key

The app can extract files without a key. For AI analysis, either paste a session-only key in Spotlight Ingestion or copy backend/.env.example to backend/.env and add OPENAI_API_KEY.

Session keys are used only for the current browser session and are not written to local storage. Never commit a real key.

Judge quick start

Supported platforms: Windows (one-command launcher), macOS, and Linux (manual two-terminal setup below).

This is a local-first MVP with no hosted instance. The included synthetic source lets judges test the complete interface without private material:

powershell -ExecutionPolicy Bypass -File .\start-flow-ai.ps1 -FreshWorkspace

Then import demo/sample_research.md. An OpenAI API key is required only for AI generation of proposals, connections, evidence checks, and Co-Pilot drafts; extraction, the canvas shell, and local workspace reset start without one. A session key can be pasted in Spotlight Ingestion and is never persisted by the app.

Fast demo path

1. Start the project.
2. Open Spotlight Ingestion and select Auto, English, or Ukrainian.
3. Enter a query and upload demo/sample_research.md, or use your own permitted source.
4. Analyze the source, inspect evidence in AI Inbox, and merge proposals.
5. Select a merged fact and run Internal Evidence Check to inspect its local support and limitations.
6. Merge two or more facts and run Discover Connections.
7. Select a fact and run Context Co-Pilot.
8. Try a layout, group facts, restore a previous revision, and download the report.

Codex and GPT-5.6

Codex was the primary coding agent for the React Flow canvas, FastAPI/Pydantic contracts, evidence validation, topic isolation, localization, UI-state snapshots, regression checks, and the one-command launcher.

GPT-5.6 (gpt-5.6-luna) generates structured findings, confidence scores, topic-fit decisions, layout suggestions, relationship candidates, and Socratic drafts. Human approval remains required before proposals or relationships become part of the verified workspace.

OpenAI Build Week submission checklist

The Devpost submission must include:

• the Developer Tools category;
• a public YouTube demo shorter than three minutes, with audio explaining the product and the use of Codex and GPT-5.6;
• the public repository URL (or a private repository shared with the addresses specified by Devpost);
• the Codex Session ID from /feedback in the primary build task;
• this README, including setup instructions, sample data, and a clear explanation of how Codex and GPT-5.6 were used.

Keep API keys, private documents, runtime logs, and the Codex Session ID out of Git. The synthetic demo source is included so judges can test the full flow without rebuilding the app.

Verification

cd frontend
npm run lint
npm run build

python -m py_compile backend/main.py
python -m unittest discover -s backend/tests -p "test_*.py" -v

Current scope

This is a local-first hackathon MVP. Evidence mapping and the Internal Evidence Check assess only the imported workspace; they do not replace external source verification or establish real-world truth. Hosted multi-user persistence, authentication, OCR for image-only PDFs, external web fact checking, and production job queues are outside the current scope.

License

MIT