Knowledge Network & Ontology Tracker
KNOT is an AI-powered observability and reasoning tool that transforms unstructured text (PDFs, CSVs, Slack exports) into a traversable Knowledge Graph. It allows you to visualize entities and relationships, and uses an autonomous agent to perform complex computational reasoning over your data.
- PydanticAI Extraction (The "Gatekeeper"): Robustly converts messy, unstructured files (PDF, TXT, CSV, JSON) into strictly typed Pydantic models (Entities and Relationships) using the Groq API.
- Auto-Retry Validation: If the LLM hullucinates or misses required fields (like
source_citation), the Gatekeeper automatically prompts the LLM to correct itself. - Interactive Knowledge Visualization: Smooth, responsive 2D Force Graph to visualize project ontologies, featuring smart zooming, node coloring by type, and connection highlighting.
- Smart Query Routing:
- Fast Path: Direct LLM context injection for simple queries (Who, What, When).
- Complex Path: Autonomous SmolAgents CodeAgent (The "Weaver") that writes Python code to compute centrality, graph overlaps, and shortest paths.
- Grounding Evidence: Every query response explicitly highlights the exact nodes in the graph that were used to formulate the answer.
- Supabase Persistence: Fully backed by PostgreSQL for projects, documents, entities, relationships, and chat histories.
┌─────────────────────────────────┐ HTTP/REST ┌─────────────────────────────────┐
│ React Frontend │ ────────────────────────────► │ FastAPI Backend │
│ (Vite + TW4) │ ◄──────────────────────────── │ (Python 3.13, Uvicorn) │
│ │ │ │
│ • Project Sidebar │ │ • /api/projects (CRUD) │
│ • Chat UI │ │ • /api/upload (Parsers) │
│ • 2D Force Graph (Viz) │ │ • /api/query (Agents/LLM) │
│ • Grounding Evidence Pane │ │ • /api/graph (Nodes/Edges) │
└─────────────────────────────────┘ └─────────────┬───────────────────┘
│
┌────────────────────────────────────┼───────────────────────────┐
│ │ │
▼ │ ▼
┌──────────────────────────────┐ │ ┌─────────────────────────────┐
│ Supabase (PostgreSQL) │ │ │ Groq LLM API │
│ │ │ │ (llama-3.3-70b) │
│ • projects • entities │ │ │ │
│ • documents • relations │ │ │ • PydanticAI Extraction │
│ • messages │ │ │ • SmolAgents Reasoning │
└──────────────────────────────┘ │ └─────────────────────────────┘
│
▼
┌───────────────────────────┐
│ The "Gatekeeper" │
│ (Structured Extraction) │
├───────────────────────────┤
│ The "Weaver" │
│ (Graph Query/Analysis) │
└───────────────────────────┘
- Frontend: React 19, Vite, Tailwind CSS (v4), Framer Motion, React Force Graph 2D, Lucide Icons.
- Backend: FastAPI (Python 3.13), Uvicorn.
- Database: Supabase (PostgreSQL).
- AI & Reasoning:
- Groq API (Llama 3.3 70B Versatile) for high-speed inference.
- PydanticAI for type-safe data extraction.
- SmolAgents (HuggingFace) for CodeAgent reasoning.
- Node.js 18+
- Python 3.13+
- Supabase account (Free tier)
- Groq API Key (Free tier)
- Create a new project in your Supabase Dashboard.
- Go to the SQL Editor.
- Copy the contents of
python_backend/create_tables.sql. - Run the SQL script to generate the required tables (
projects,documents,entities,relationships,messages).
cd python_backend
# Create a virtual environment
python -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
# Install dependencies
pip install -r requirements.txt
# Configure Environment Variables
cp .env.example .env
# Edit .env and add your GROQ_API_KEY, SUPABASE_URL, and SUPABASE_KEY
# Start the FastAPI server
python main.pyThe backend will run on http://localhost:8000.
Open a new terminal window:
# Return to root directory
cd ..
# Install dependencies
npm install
# Start the development server
npm run devThe frontend will run on http://localhost:3000.
- Create a Project: Click "New Project" in the sidebar to create a dedicated sandbox.
- Upload Data: Click the "Upload" button (☁️) in the chat header. Select a PDF, CSV, TXT, or JSON file. The system will slice it, extract entities via PydanticAI, and populate the graph.
- Explore the Graph: Drag nodes, zoom in/out. Nodes are color-coded by their ontological category (Person, Technology, Location, etc.).
- Chat & Reason:
- Ask simple questions: "Who is participating in the project?" (Uses direct LLM routing for speed).
- Ask complex questions: "Which entities have the most overlap?" or "What is the shortest path between Node A and Node B?" (Triggers the SmolAgent to write and execute analytical Python code).
- Inspect Grounding: Click on the highlighted "Grounding Evidence" pills below an agent response to watch the graph auto-zoom and illuminate the exact data points referenced.
This project is licensed under the MIT License - see the LICENSE file for details.