KnowLot

A multi-agent system for intelligent project knowledge retrieval using vector search, graph databases, and LLM synthesis.

Problem Statement

Before diving into the architecture and implementation, it’s important to understand the core problem this project is solving and why it exists.

The complete problem breakdown — including:

• The motivation behind the project
• Clear articulation of the problem scope and constraints

is documented in the following presentation:

KnowLot_IntelliVine.pdf

Features

• Multi-Agent Architecture: Orchestrates retrieval, graph query, timeline, and synthesis agents
• Vector Search: Uses ChromaDB for semantic document retrieval
• Graph Database: Optional Neo4j integration for entity relationships
• React Frontend: Modern UI built with React, Material-UI, and Vite
• FastAPI Backend: RESTful API with automatic OpenAPI documentation

Prerequisites

• Python 3.8+
• Node.js 16+ and npm
• (Optional) Neo4j database (defaults to bolt://localhost:7687)

Installation

1. Install Python Dependencies

pip install -r requirements.txt

This will install:

• langgraph - Multi-agent orchestration
• chromadb - Vector database
• openai - LLM and embeddings
• neo4j - Graph database client
• fastapi - Web framework
• uvicorn - ASGI server
• python-dotenv - Environment variable management

2. Install Frontend Dependencies

cd frontend
npm install

3. Build the Frontend

cd frontend
npm run build

This builds the React app and outputs to static/dist/ directory.

4. Environment Variables

Create a .env file in the root directory with your configuration:

# Required
OPENAI_API_KEY=your_openai_api_key_here

# Optional (Neo4j defaults)
NEO4J_URI=bolt://localhost:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=your_password

Running the Application

Start the Server

From the project root:

python3 server.py

The server will start on http://localhost:8000

Access the Application

• Web UI: http://localhost:8000
• API Docs: http://localhost:8000/docs (FastAPI automatic documentation)
• Health Check: http://localhost:8000/health

Development

Running Frontend in Development Mode

For frontend development with hot reload:

cd frontend
npm run dev

This starts Vite dev server (typically on port 5173). Note: The dev server proxies API calls to http://localhost:5000, but the production server runs on port 8000. You may need to update the proxy in frontend/vite.config.js if running the backend on a different port.

Project Structure

KnowLot/
├── agents/              # Multi-agent system
│   ├── orchestrator.py  # Main orchestration logic
│   ├── retrieval_agent.py
│   ├── graph_agent.py
│   ├── timeline_agent.py
│   └── synthesis_agent.py
├── config/              # Configuration
│   └── settings.py
├── data/                # Data processing
│   ├── embedding.py
│   ├── graph_builder.py
│   └── ingestion.py
├── dataset/             # Dataset generation
│   ├── generator.py
│   └── templates.py
├── frontend/            # React frontend
│   ├── src/
│   └── package.json
├── tools/               # Utility tools
│   ├── graph_query.py
│   ├── llm_client.py
│   └── vector_search.py
├── static/              # Static files (frontend build output)
│   └── dist/
├── server.py            # FastAPI server
└── requirements.txt

API Endpoints

• POST /api/query - Query the knowledge base

  {
    "query": "Your question here",
    "top_k": 5
  }

• POST /api/generate-dataset - Generate synthetic dataset

  {
    "topic": "Your topic",
    "num_docs": 30
  }

• POST /api/ingest - Ingest data into databases

  {
    "topic_slug": "topic-slug-name"
  }

• GET /health - Health check endpoint

Usage Workflow

1. Generate Dataset: Use the /api/generate-dataset endpoint to create synthetic project artifacts (emails, Slack threads, Jira tickets, documents)

2. Ingest Data: Use the /api/ingest endpoint to load the generated data into ChromaDB (and optionally Neo4j)

3. Query: Use the /api/query endpoint or the web UI to ask questions about your project knowledge

4. Answer: After submitting a query, scroll down to view the generated response. Each answer is enriched with:
   • Citations pointing to the original sources
   • A timeline summary of relevant events
   • Referenced documents
   • Suggested next steps for further exploration

5. Timeline: The timeline provides a chronological view of events related to your query. Each event may include a title, description, and associated context, making it easier to understand how the project evolved over time.

6. Graph: The graph visualizes relationships across your project knowledge, including:
   • Team members involved
   • Related tickets or tasks
   • Linked documents and sources

This helps you quickly understand how people, work items, and documentation are connected.

Notes

• The application uses OpenAI's GPT-4o for synthesis and text-embedding-3-small for embeddings
• ChromaDB data is persisted locally in the chroma_db/ directory
• Generated datasets are stored in dataset/output/
• Neo4j is optional - the system will work with just ChromaDB, but graph features won't be available

Troubleshooting

• Module not found errors: Make sure all Python dependencies are installed with pip install -r requirements.txt
• Frontend not found: Run npm run build in the frontend/ directory
• OpenAI API errors: Verify your OPENAI_API_KEY is set in the .env file
• Neo4j connection errors: The app will work without Neo4j, but graph features will be disabled