# Project export: Flow-AI Research

This document was generated by HackStack to give an AI agent context about a hackathon project. Sections are labeled with their provenance; content marked as truncated was cut to keep this document small.

## Project metadata

- Hackathon: OpenAI Build Week
- Tagline: An evidence-grounded AI workspace that turns research documents into a traceable, human-verified knowledge graph.
- Devpost: https://devpost.com/software/flow-ai-e9pd1y
- GitHub: https://github.com/gith1t/Flow-AI
- Video: https://www.youtube.com/embed/0EZGODnNA2I?enablejsapi=1&hl=en_US&rel=0&start=&version=3&wmode=transparent
- Team: 1 GitHub contributor(s) — gith1t (34 commits)

## Devpost submission (written by the team)

### Inspiration

Research work is often scattered across PDFs, notes, transcripts, and separate AI chats. This makes it difficult to understand how individual facts relate to the original source and which conclusions can actually be trusted. We built Flow-AI Research IDE to make research more structured, traceable, and easier to verify. What We Built Flow-AI transforms research documents into an interactive, evidence-grounded knowledge workspace. Users can: Upload research sources such as PDF, DOCX, TXT, Markdown, CSV, or JSON files. Ask a focused research question. Review AI-generated findings in an Inbox before accepting them. Inspect exact source evidence for every proposed fact. Merge verified findings into a visual knowledge graph. Explore relationships between topics and facts. Use Context Co-Pilot to identify gaps and suggest further research directions. Work in English, Ukrainian, or the detected source language. Export the resulting research as a Markdown report. The system keeps the human researcher in control: AI proposes, but the user verifies and commits information to the workspace. How We Built It The frontend is a Vite React single-page application styled with Tailwind CSS. React Flow powers the interactive research canvas and graph relationships. The backend is built with FastAPI, Python, Pydantic, and Uvicorn. It handles document ingestion, text extraction, structured AI responses, evidence mapping, workspace state, and snapshots. OpenAI GPT-5.6 Luna is used for document analysis, finding extraction, evidence-grounded reasoning, and Context Co-Pilot suggestions. Codex helped us implement and refine the full-stack workflow, including the graph UI, API integration, persistence, localization, testing, and the one-command local launcher. What We Learned The most important lesson was that useful AI research is not only about generating plausible answers. Each finding must remain connected to its source evidence and be easy for a human to inspect. We also learned that visual structure is valuable: a graph can reveal missing links, competing ideas, and research gaps that are difficult to notice in a linear document. Challenges The main challenges were maintaining consistency between the FastAPI schemas and React state, preserving graph positions and relationships, supporting multiple documents, and preventing unsupported AI conclusions from appearing as verified facts. We addressed these challenges with structured Pydantic models, explicit evidence fields, human approval steps, local workspace persistence, and a clear separation between proposals and committed findings. Current Scope Flow-AI is an MVP for evidence-grounded research exploration. It is designed for researchers, analysts, students, and knowledge workers who need to move from unstructured documents to a traceable visual understanding of a topic. GitHub repository Demo video

## README (from the GitHub repository)

# 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](https://github.com/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
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
powershell -ExecutionPolicy Bypass -File .\start-flow-ai.ps1 -FreshWorkspace
```

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

Useful options:

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

### macOS/Linux — two terminals

Backend:

```bash
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:

```bash
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`](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
powershell -ExecutionPolicy Bypass -File .\start-flow-ai.ps1 -FreshWorkspace
```

Then import [`demo/sample_research.md`](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`](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

```powershell
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](LICENSE)


## Detected evidence (automated analysis)

Indexed codebase: 16 recognized source files, 350 KB.
- CSS (language) — detected in the code
- FastAPI (technology) — detected in the code
- HTML (language) — detected in the code
- JavaScript (language) — detected in the code
- OpenAI (technology) — detected in the code
- Python (language) — detected in the code
- React (technology) — detected in the code
- Tailwind CSS (technology) — detected in the code

## Codebase structure (from repository index)

### Files (26 of 26)

```
.gitignore
backend/.env.example
backend/.gitignore
backend/main.py
backend/requirements.txt
backend/test_ai.py
backend/tests/__init__.py
backend/tests/test_api_contract.py
backend/tests/test_core_pipeline.py
demo/sample_research.md
frontend/.gitignore
frontend/.oxlintrc.json
frontend/index.html
frontend/package.json
frontend/postcss.config.js
frontend/README.md
frontend/src/App.css
frontend/src/App.jsx
frontend/src/index.css
frontend/src/main.jsx
frontend/tailwind.config.js
frontend/vite.config.js
LICENSE
README.md
requirements.txt
start-flow-ai.ps1
```

### Dependencies

- backend/requirements.txt: fastapi, openai, pydantic, pypdf, python-docx, python-dotenv, python-multipart, uvicorn
- frontend/package.json: @types/react@^19.2.17, @types/react-dom@^19.2.3, @vitejs/plugin-react@^6.0.3, @xyflow/react@^12.11.2, autoprefixer@^10.5.4, oxlint@^1.71.0, postcss@^8.5.19, react@^19.2.7, react-dom@^19.2.7, tailwindcss@^3.4.19, vite@^8.1.1

### Recent commits (newest first)

- fix: keep merged findings visible on canvas
- docs: clarify build week judge setup
- feat: harden evidence research pipeline
- feat: add clean workspace launcher mode
- docs: prepare hackathon submission package
- docs: simplify README presentation
- docs: refresh hackathon README
- refactor: remove red team terminology
- feat: finalize Flow-AI research workspace
- fix: stabilize canvas state and evidence provenance
- chore: add venv to gitignore
- fix(core): confidence_score, absolute coordinates for layers, and real Time Travel with ui_state
- Revise README with project overview and setup guide
- feat(backend): add targeted socratic review and smart layout inference
- fix: targeted socratic review, readonly canvas modes, smart layout sync and file ingestion
- fix: targeted socratic review, readonly canvas modes, smart layout sync and file ingestion
- fix: add Socratic fact-targeting (Red Teamer) and WorkspaceState.suggested_layout
- fix: revive TopBar UI, add file upload to modal, fix layout math and language override
- feat: complete UI overhaul with TopBar, Ingest Modal and Layout Switcher
- feat: complete MVP with Magic Layout, Markdown Export and Backend Language Override

## Key source files (fetched from GitHub, selected and truncated for size)

### demo/sample_research.md

```markdown
# Synthetic Flow-AI demo source

This short document is synthetic demonstration data created for the Flow-AI Research IDE hackathon demo.

## Question

How can a small research team reduce the time spent validating claims across multiple papers?

## Observations

Evidence-first workflows make each extracted claim point back to an exact source passage. This lets a reviewer distinguish a supported finding from a plausible but unverified interpretation.

When two sources describe the same mechanism using different terminology, a relationship candidate can help a researcher compare them. The candidate should remain reviewable until the researcher confirms that both passages support the proposed link.

Separating unrelated sources is also important. A paper about battery materials should not automatically create a relationship with a paper about team communication simply because both contain the word “efficiency”.

## Intended outcome

A useful research workspace should expose claims, confidence, source evidence, possible relationships, and human approval history in one navigable view.

```

### requirements.txt

```
-r backend/requirements.txt

```

### backend/requirements.txt

```
fastapi
uvicorn
pydantic
openai
python-dotenv
pypdf
python-multipart
python-docx

```

### frontend/package.json

```
{
  "name": "frontend",
  "private": true,
  "version": "0.0.0",
  "type": "module",
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "lint": "oxlint",
    "preview": "vite preview"
  },
  "dependencies": {
    "@xyflow/react": "^12.11.2",
    "react": "^19.2.7",
    "react-dom": "^19.2.7"
  },
  "devDependencies": {
    "@types/react": "^19.2.17",
    "@types/react-dom": "^19.2.3",
    "@vitejs/plugin-react": "^6.0.3",
    "autoprefixer": "^10.5.4",
    "oxlint": "^1.71.0",
    "postcss": "^8.5.19",
    "tailwindcss": "^3.4.19",
    "vite": "^8.1.1"
  }
}

```

### frontend/src/main.jsx

```javascript
import { StrictMode } from 'react'
import { createRoot } from 'react-dom/client'
import './index.css'
import App from './App.jsx'

createRoot(document.getElementById('root')).render(
  <StrictMode>
    <App />
  </StrictMode>,
)

```

### frontend/postcss.config.js

```javascript
export default {
  plugins: {
    tailwindcss: {},
    autoprefixer: {},
  },
}

```

### frontend/vite.config.js

```javascript
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

// https://vite.dev/config/
export default defineConfig({
  plugins: [react()],
})

```

### frontend/tailwind.config.js

```javascript
/** @type {import('tailwindcss').Config} */
export default {
  content: [
    "./index.html",
    "./src/**/*.{js,ts,jsx,tsx}",
  ],
  theme: {
    extend: {},
  },
  plugins: [],
}

```

### frontend/index.html

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>frontend</title>
  </head>
  <body>
    <div id="root"></div>
    <script type="module" src="/src/main.jsx"></script>
  </body>
</html>

```

### backend/test_ai.py

```python
"""Тест ендпоінту /api/research на запущеному сервері Yomirai (http://localhost:8000)."""
import json
import urllib.request
import urllib.error

URL = "http://localhost:8000/api/research"
PAYLOAD = {
    "query": "Троянська війна: ключові події",
    "text": "Лекція про Троянську війну: Ахіль вбив Гектора біля стін Трої, але Одіссей придумав коня.",
}


def post(url: str, payload: dict) -> tuple[int, dict]:
    data = json.dumps(payload).encode("utf-8")
    req = urllib.request.Request(
        url, data=data, headers={"Content-Type": "application/json"}, method="POST"
    )
    try:
        with urllib.request.urlopen(req) as resp:
            return resp.status, json.loads(resp.read().decode("utf-8"))
    except urllib.error.HTTPError as e:
        return e.code, json.loads(e.read().decode("utf-8"))


if __name__ == "__main__":
    status, body = post(URL, PAYLOAD)
    print(f"Статус відповіді: {status}")
    proposals = body.get("new_proposals", [])
    print(f"Отримано карток-proposals: {len(proposals)}")
    print(json.dumps(proposals, ensure_ascii=False, indent=2))

```

[4 more indexed source files omitted to keep this export small. The full file list is in the Codebase structure section above.]