Ai Hackathon Demo

NASA Document Q&A System

> An intelligent question-answering system powered by LangChain and OpenAI that provides executive-level insights from NASA technical documents.

[](https://python.org) [](https://langchain.com) [](https://openai.com) [](https://trychroma.com) [](https://docker.com)

📋 Table of Contents

• [Overview](#overview)
• [Features](#features)
• [Prerequisites](#prerequisites)
• [Installation](#installation)
• [Configuration](#configuration)
• [Usage](#usage)
• [Quick Start](#quick-start)
• [Example Prompts](#example-prompts)
• [Advanced Usage](#advanced-usage)
• [Docker Deployment](#-docker-deployment)
• [Architecture](#architecture)
• [Debugging & Troubleshooting](#debugging--troubleshooting)
• [Development](#development)
• [Contributing](#contributing)
• [License](#license)

🎯 Overview

This system transforms NASA's technical documentation into an interactive Q&A interface designed for executives and technical leaders. Built with LangChain's React agent pattern and OpenAI's GPT-5-mini, it provides accurate, contextual answers by intelligently retrieving relevant information from processed NASA documents. The system features optional MCP (Model Context Protocol) integration for enhanced filesystem capabilities and follows a clean 5-layer modular architecture.

What Problems Does This Solve?

• Information Overload: NASA documents are extensive and complex - this system extracts key insights quickly
• Executive Decision Making: Provides executive-level summaries and analysis from technical documents
• Compliance Tracking: Enables quick retrieval of governance and compliance information
• Knowledge Discovery: Uncovers connections between different NASA documents and initiatives

Why This Technology Stack?

• LangChain: Provides robust document processing, retrieval pipelines, and React agent framework
• OpenAI GPT-5-mini: Delivers high-quality, cost-effective text generation and embeddings
• Chroma Vector Database: Enables semantic search across document chunks
• MCP (Model Context Protocol): Optional integration for filesystem and external tool access
• React Agent Pattern: Intelligent reasoning and tool selection for complex queries

✨ Features

• 📄 PDF Document Processing: Automatically ingests and processes NASA PDFs
• 🔍 Semantic Search: Vector-based similarity search for relevant content
• 🎯 Executive Summaries: Tailored responses for executive audiences
• ⚡ Fast Retrieval: Sub-second query processing with 361 indexed documents
• 🛠️ Comprehensive Debugging: Built-in tools for system health monitoring
• 🔧 Modular Architecture: Clean 5-layer architecture with single responsibility components
• 🔌 MCP Integration: Optional Model Context Protocol support for filesystem operations
• 🤖 React Agent Pattern: Intelligent tool selection and reasoning capabilities
• 🐳 Docker Ready: Containerized deployment with interactive support
• 📊 Analytics Ready: Built-in metrics and performance monitoring
• ⚙️ Environment-Driven: Configuration management with validation and graceful degradation

🔧 Prerequisites

System Requirements

• Python: 3.13+ (tested with 3.13.1)
• OpenAI API Key: Required for embeddings and text generation
• Memory: 4GB+ RAM recommended for vector operations
• Storage: 500MB+ for vector database and documents

Supported Platforms

• macOS (ARM64/Intel)
• Linux (x86_64/ARM64)
• Windows (WSL recommended)

🚀 Installation

You can run the NASA Q&A system either locally with Python or using Docker. Choose the method that best fits your environment:

• 🐍 Local Python Setup: Full development capabilities with debugging tools
• 🐳 Docker Setup: Isolated environment, consistent deployment (see [Docker Deployment](#-docker-deployment))

> 💡 Pro Tip: Get your OpenAI API key from platform.openai.com/account/api-keys

Quick Setup (Recommended)

# 1. Clone and navigate to the project
git clone https://github.com/driches/ai-hackathon-demo
cd hackathon-demo

# 2. Edit your API key in the .env file
# Replace 'your_openai_api_key_here' with your actual OpenAI API key
cp .env.example .env
nano .env  # or use your preferred editor

# 3. Build Docker Container
make docker-build

# 4. Start Chat
make docker-interactive

Local Setup

# 1. Run the automated setup script
make setup

# 2. Edit your API key in the .env file
# Replace 'your_openai_api_key_here' with your actual OpenAI API key
cp .env.example .env
nano .env  # or use your preferred editor

Activation for Development

# Activate the environment for future sessions
source ./activate.sh

# Or use the standard activation
source .venv/bin/activate

2. Verify Setup

# Test your configuration
make debug-env

# Expected output:
# ✅ OPENAI_API_KEY: Set
# ✅ Python 3.13.1 detected
# ✅ Virtual environment active

🎮 Usage

Quick Start

1. Complete Setup

# Activate environment, download data, and ingest documents
source ./activate.sh
make fetch-data
make ingest

# Verify the vector database
make debug-vectordb

# Start an MCP server
make mcp-http 

2. Start Asking Questions

# To run with MCP tools (if configured in .env)
make run

# To run without MCP tools
make run-no-mcp

# You'll see the prompt:
# Ask ▶ 

3. Try Your First Query

Ask ▶ What are the key risk mitigation strategies in NASA's Systems Engineering Handbook?

→ The NASA Systems Engineering Handbook outlines several key risk mitigation strategies:

1. **Risk-Informed Decision Making (RIDM)**: A systematic approach that combines...
2. **Continuous Risk Management (CRM)**: Ongoing identification and assessment...
3. **Technical Risk Assessment**: Dual approach combining quantitative and qualitative...

[Detailed response continues...]

4. Exit the Application

Ask ▶ quit
# or press Ctrl+C

Example Prompts

Here are proven prompts that demonstrate the system's capabilities:

| Prompt | Expected Angle | Use Case | |--------|----------------|----------| | "Summarize the key technical risk mitigation steps recommended by NASA's Systems Engineering Handbook." | Compliance / governance traceability | Risk management compliance, audit preparation | | "List the mission objectives of Artemis I and the success metrics." | KPI extraction from press kit | Executive briefings, mission status reports | | "What are the primary systems engineering processes NASA recommends for large-scale projects?" | Process standardization | Project planning, methodology alignment | | "Describe the safety requirements and protocols mentioned in the NASA documentation." | Safety compliance | Safety audits, regulatory compliance | | "What testing and validation procedures does NASA require for mission-critical systems?" | Quality assurance | QA process development, validation planning | | "Summarize the budget allocations and cost considerations for Artemis I." | Financial oversight | Budget reviews, cost analysis | | "What are the key stakeholder communication requirements in NASA projects?" | Stakeholder management | Communication planning, governance | | "List the environmental and sustainability considerations in NASA missions." | Environmental compliance | ESG reporting, environmental impact |

Advanced Usage

Custom Document Processing

To add your own PDF documents:

# 1. Add PDFs to the data directory
cp your-document.pdf ./data/

# 2. Re-ingest documents
make clean-vectordb
make ingest

# 3. Verify new documents
make debug-vectordb

Batch Query Processing

# Test multiple queries
make test-retrieval

# Custom retrieval testing
python test_retrieval.py

Performance Monitoring

# Comprehensive system check
make debug

# Individual component testing
make test-components
make debug-embeddings

MCP (Model Context Protocol) Integration

The system supports optional MCP integration for enhanced filesystem operations alongside NASA document search.

What is MCP?

MCP (Model Context Protocol) is a protocol that allows AI agents to interact with external tools and services. In our system, it provides filesystem access capabilities that complement the NASA document search.

MCP Features

• Filesystem Operations: Read, write, list files and directories
• Distributed Architecture: MCP servers run separately from the main application
• Graceful Degradation: System works with or without MCP servers
• Async/Sync Bridge: Seamless integration between MCP's async protocol and LangChain's sync tools

Running with MCP

# 1. Configure MCP in your .env file
# This is usually done once
echo "MCP_SERVER_URLS=http://127.0.0.1:8000/mcp/" >> .env

# 2. Start an MCP server
make mcp-http 

# 3. Run the application with MCP support
make run

# The agent will now have both NASA search AND filesystem tools

Running without MCP

# Run with NASA documents only (no filesystem tools)
make run-no-mcp

# Or leave MCP_SERVER_URLS empty in .env file

MCP Architecture

User Query → React Agent → Tool Selection
                 │
       ┌─────────┼─────────┐
       │         │         │
  NASA Search   MCP    File System
  (Vector DB)  Bridge   Operations
       │         │         │
  Executive    HTTP     Read/Write
  Response    Request    Files

🐳 Docker Deployment

Docker provides an isolated, reproducible environment for running the NASA Q&A system. The containerized version automatically handles data fetching, document ingestion, and application startup.

Prerequisites for Docker

• Docker Desktop: Latest version recommended
• OpenAI API Key: Required and configured in .env file
• Memory: 4GB+ RAM for Docker container operations

Quick Docker Start

1. Build the Docker Image

# Build the Docker image with all dependencies
make docker-build

# Or use direct Docker command:
# docker build -t nasa-qa-demo .

2. Run Interactively (Recommended)

# Start interactive Q&A session in Docker
make docker-interactive

# This will:
# ✅ Download NASA documents automatically
# ✅ Process them into vector database
# ✅ Start the interactive Q&A interface
# ✅ Show the thinking animation
# ✅ Allow you to ask questions and get responses

You'll see output like:

🐳 Starting interactive NASA Q&A system in Docker...
💡 You can now ask questions about NASA documents!
💡 Type 'quit', 'exit', or 'q' to stop, or press Ctrl+C

↓ nasa_se_handbook.pdf
↓ artemis_i_press_kit.pdf
↓ clps_press_kit.pdf
NASA docs ready → ./data
🚀 NASA Document Q&A System
Ask questions about NASA documents. Type 'quit', 'exit', or 'q' to stop.
============================================================
Ask ▶ 

3. Test Your Docker Setup

# Run non-interactive mode for testing
make docker-run

# This validates the complete pipeline without user interaction

Docker Commands Reference

| Command | Purpose | Use Case | |---------|---------|----------| | make docker-build | Build Docker image | Initial setup, after code changes | | make docker-interactive | Interactive Q&A session | Normal usage, demonstrations | | make docker-run | Non-interactive pipeline test | CI/CD, automated testing |

Direct Docker Commands

If you prefer using Docker directly:

# Build image
docker build -t nasa-qa-demo .

# Run interactively (recommended for Q&A)
docker run -it --rm --env-file .env nasa-qa-demo

# Run non-interactively (for testing)
docker run --rm --env-file .env nasa-qa-demo

Docker vs Local Development

| Aspect | Docker | Local Development | |--------|--------|-------------------| | Setup | One command after build | Multi-step setup process | | Dependencies | Isolated container | Requires Python 3.13+ | | Performance | ~10% overhead | Native performance | | Debugging | Limited access | Full debugging tools | | Updates | Rebuild required | Instant code changes |

Docker Troubleshooting

Common Docker Issues

1. Container Exits Immediately

# Check Docker logs
docker logs 

# Verify .env file exists and has OPENAI_API_KEY
ls -la .env

2. Interactive Mode Not Working

# Use our recommended command
make docker-interactive

# NOT: docker-compose up (has interactive input limitations)

3. API Key Issues in Docker

# Verify .env file format
cat .env

# Should contain:
# OPENAI_API_KEY=sk-your-actual-key-here

4. Out of Memory Errors

# Increase Docker memory limit in Docker Desktop
# Recommended: 4GB+ for smooth operation

When to Use Docker

✅ Use Docker when:

• Deploying to production servers
• Ensuring consistent environments across teams
• Running in CI/CD pipelines
• Avoiding local Python environment conflicts
• Demonstrating to stakeholders

🔧 Use Local Development when:

• Actively developing and debugging code
• Need access to debugging tools (make debug)
• Frequent code changes and testing
• Full performance optimization required

🏗️ Architecture

System Flow

┌─────────────┐    ┌──────────────┐    ┌─────────────┐
│  PDF Docs   │───▶│   Ingestion  │───▶│  Vector DB  │
└─────────────┘    └──────────────┘    └─────────────┘
                                              │
┌─────────────┐    ┌──────────────┐    ┌─────▼─────┐
│   Response  │◀───│  AI Agent    │◀───│ Retrieval │
└─────────────┘    └──────────────┘    └───────────┘
                           ▲                  ▲
                    ┌──────▼──────┐    ┌──────▼──────┐
                    │ User Query  │    │ MCP Tools   │
                    └─────────────┘    └─────────────┘

5-Layer Clean Architecture

The system follows a modular, clean architecture pattern with distinct layers:

1. Configuration Layer (common/config.py): Environment setup and validation
2. Data Layer (common/nasa_search.py): Vector database and document retrieval
3. Integration Layer (common/mcp_client.py): External MCP server connections
4. Agent Layer (common/agent_factory.py): AI agent creation and configuration
5. Presentation Layer (main.py): User interface and interaction

Key Components

• main.py: Main application using modular components
• common/config.py: Environment and configuration management with validation
• common/nasa_search.py: RAG implementation for NASA document search
• common/mcp_client.py: MCP (Model Context Protocol) integration with async/sync bridge
• common/agent_factory.py: Factory for creating configured AI agents
• common/thinking_spinner.py: UI components with threading support
• ingest.py: PDF processing and vector database creation
• debug_embeddings.py: Comprehensive embedding pipeline testing
• test_retrieval.py: Query testing and validation
• chroma_db/: Vector database storage
• data/: Source PDF documents

Agent Architecture (React Pattern)

┌─────────────┐
│ User Query  │
└─────┬───────┘
      │
┌─────▼───────┐
│ React Agent │ ◀── LangChain create_react_agent
└─────┬───────┘
      │
┌─────▼───────┐    ┌─────────────┐    ┌─────────────┐
│    Tools    │◀──▶│ NASA Search │ +  │ MCP Tools   │
└─────┬───────┘    └─────────────┘    └─────────────┘
      │                    │                  │
┌─────▼───────┐    ┌─────▼─────┐    ┌─────▼─────┐
│  Response   │    │Vector DB  │    │File System│
└─────────────┘    └───────────┘    └───────────┘

Design Patterns Used

• Singleton Pattern: Configuration and client instances
• Factory Pattern: Agent creation with different tool configurations
• Adapter Pattern: Async/sync bridge for MCP integration
• Strategy Pattern: Different tool sets ba

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: driches
• Source: driches/ai-hackathon-demo
• License: MIT

Install and usage instructions live in the source repository linked above.