IdeaGraph Studio

A fully local, deterministic research and brainstorming application that converts technical documents into an "Idea Architecture" knowledge graph with strict provenance and editability.

Features

• Fully Local: No external APIs, all processing runs on your machine
• Deterministic: Reproducible outputs with fixed seeds and deterministic hashing
• Transparent: Every node and edge is traceable to source evidence
• Editable: Manual editing of nodes and edges with full provenance tracking
• Multi-Domain: Support for ML/AI, Statistics, Business, OR, Energy, Bio/Medical, Physics, Chemistry, Social Science, Software Engineering, and General domains

Requirements

• Python 3.10+
• Node.js 18+
• Docker and Docker Compose
• Ollama installed locally with required models

Ollama Models Required

Install the following models using Ollama:

ollama pull qwen2.5:7b-instruct
ollama pull qwen3-embedding:4b

For fallback embeddings (optional):

# Install sentence-transformers via pip (handled in requirements.txt)

Quick Start

1. Start Neo4j

docker-compose up -d

Wait ~10 seconds for Neo4j to initialize. Verify at http://localhost:7474 (username: neo4j, password: ideagraph)

2. Start Backend

Option A: Using the startup script

./start_backend.sh

Option B: Manual start

cd backend
pip install -r requirements.txt
uvicorn main:app --reload

The backend will be available at http://localhost:8000 API documentation at http://localhost:8000/docs

3. Start Frontend

In a new terminal:

cd frontend
npm install
npm start

The frontend will be available at http://localhost:3000

Project Structure

.
├── backend/          # FastAPI backend
│   ├── api/         # API endpoints
│   ├── core/        # Core processing logic
│   └── tests/       # Test suite
├── frontend/         # React frontend
├── docker-compose.yml
├── start_backend.sh  # Backend startup script
└── README.md

Architecture

Backend (FastAPI)

• Core Pipeline: Document parsing → Research question detection → Entity extraction → Relation extraction → Graph construction
• Storage: Neo4j for graph persistence
• LLM: Ollama for local LLM inference
• Embeddings: Ollama embeddings with sentence-transformers fallback

Frontend (React + D3)

• Dashboard: Project management
• Workspace: Graph visualization and editing
• Evidence Panel: Provenance tracking

Key Features

1. Deterministic Processing: All IDs are hashes, LLM uses temperature=0
2. Strict Ontology: Only predefined node types allowed
3. Research Question Gate: Must detect or user must provide at least one research question
4. Full Provenance: Every node/edge linked to source chunks
5. Editable: Manual editing with provenance preservation

Troubleshooting

Backend Not Running

If you see "Cannot connect to backend" error:

1. Check if backend is running:

   lsof -i :8000
   # or
   curl http://localhost:8000/api/health

2. Start the backend:

   ./start_backend.sh
   # or
   cd backend && uvicorn main:app --reload

3. Check for errors:

   • Look at the backend terminal for Python errors
   • Check browser console (F12) for detailed error messages
   • Verify Neo4j is running: docker ps

Neo4j Connection Issues

• Ensure Docker is running: docker ps
• Check Neo4j logs: docker logs ideagraph-neo4j
• Verify connection: Visit http://localhost:7474

PDF Upload Fails

• Check file format is supported (PDF, DOCX, MD, TXT, TEX, JSON)
• Ensure document has digital text (no scanned PDFs)
• Check backend logs for detailed error messages
• Verify Ollama models are installed: ollama list

See TROUBLESHOOTING.md for more details.

Development

Run tests:

cd backend
pytest

Known Limitations

• PDF parsing requires digital text (no OCR support)
• Large documents may take significant time to process
• Neo4j requires Docker to be running
• Ollama must be running locally with required models
• Research question detection may require user input if confidence is low

License

MIT