AI Knowledge Explorer

Drop files — documents or source code — into a chatbot. The agent extracts entities, concepts, and relationships (or modules, classes, functions, and dependencies), then renders an interactive knowledge graph you can explore.

Click a node to see details. Double-click to expand it — the agent extracts sub-concepts (or sub-components for code) and adds them to the graph. Ask questions in chat to navigate.

How It Works

1. Drop files — drag documents (.txt, .md, .json, .csv) or code files (.py, .ts, .js, .java, .go, .rs, and more) onto the canvas
2. Agent extracts — the LLM identifies structure: entities and concepts for text, modules and functions for code
3. Graph renders — nodes and edges appear as the agent processes each file
4. You explore — click nodes, expand them, ask questions, steer the agent

Architecture

• Shared state: The knowledge graph (nodes + edges) lives in agent state and syncs bidirectionally via CopilotKit v2
• Generative UI: Each tool call produces visible changes — new nodes, new edges, expanded detail
• Human-in-the-loop: Click to select, double-click to expand, chat to steer

Tech Stack

Layer	Technology
Frontend	Next.js 16, React 19, TailwindCSS 4
Agent	LangGraph (Python), CopilotKit Middleware
Graph	react-force-graph-2d
LLM	OpenAI (configurable via env)
Protocol	AG-UI (state streaming)

On the default model (gpt-4o): extraction (extract_knowledge, find_connections, expand_node) works by prompting the model to return raw JSON and parsing it — there's no function-calling schema or structured-output mode tuned specifically to gpt-4o, so any model with solid instruction-following should work as a drop-in swap via OPENAI_MODEL. gpt-4o was picked as a well-understood, inexpensive baseline for reliably following the "return only JSON" instruction, not because it was benchmarked against newer models for this task. If you swap in a newer or reasoning-focused model, expect it to work, but re-verify the "ONLY valid JSON" instruction is still being honored (some models wrap output in explanation or markdown even when told not to).

Prerequisites

• Node.js 18+
• Python 3.12
• uv — the agent's Python dependencies are managed with uv, and npm install runs uv sync automatically. Install it with curl -LsSf https://astral.sh/uv/install.sh | sh (macOS/Linux) or powershell -c "irm https://astral.sh/uv/install.ps1 | iex" (Windows). uv fetches Python 3.12 for you if it isn't already installed.

Setup

# 1. Install dependencies (also runs `uv sync` for the Python agent)
npm install

# 2. Set your API key
cp .env.example .env
# Edit .env and add your OPENAI_API_KEY

# 3. Start the app
npm run dev

This starts both the Next.js frontend (port 3000) and the LangGraph agent (port 8125). On Windows the same npm scripts run the .bat equivalents under scripts/.

Example Content

Two built-in example sets let you try both modes — click the buttons on the empty state to load them instantly.

Documents — 3 markdown files about AI agents:

• what-are-agents.md — defines agents, core components (LLM, tools, memory, planning)
• agent-frameworks.md — compares LangGraph, CrewAI, AutoGen, CopilotKit
• agent-challenges.md — hallucination, tool reliability, evaluation, cost, security

Expected graph: ~15-22 nodes, ~20-33 edges covering the AI agent ecosystem.

Codebase — 3 Python files forming a FastAPI auth system:

• auth.py — JWT token creation, password hashing, TokenService class
• routes.py — login, register, refresh endpoints, dependency injection
• models.py — SQLAlchemy User, Post, AuditLog models

Expected graph: ~20 nodes showing modules, classes, functions, and their imports/calls/extends relationships.

Agent Tools

Tool	Purpose
extract_knowledge	Parse documents or code, extract entities/concepts/relationships or modules/classes/functions
find_connections	Discover deeper links between existing nodes
expand_node	Deep-dive into a node — adds sub-concepts and detail

Project Structure

ai-knowledge-explorer/
├── agent/                    # Python LangGraph agent
│   ├── main.py               # Agent entry point
│   └── src/
│       ├── state.py           # KnowledgeState schema
│       └── tools.py           # extract, connect, expand tools
├── src/                       # Next.js frontend
│   ├── app/
│   │   ├── page.tsx           # Main page (chat + graph canvas)
│   │   ├── layout.tsx         # CopilotKit v2 provider
│   │   └── api/
│   │       ├── copilotkit/    # CopilotKit runtime route
│   │       └── upload/        # File upload endpoint
│   ├── components/
│   │   ├── KnowledgeGraph.tsx  # Force-directed graph visualization
│   │   ├── NodeDetail.tsx      # Detail panel on node select
│   │   └── ToolReasoning.tsx   # Tool call status indicators
│   ├── hooks/
│   │   ├── use-knowledge-ui.tsx
│   │   └── use-suggestions.tsx
│   └── lib/
│       ├── types.ts            # KnowledgeNode, KnowledgeEdge types
│       └── example-content.ts  # Built-in example documents and code
├── package.json
└── .env.example