README.md

metadata

title: Humanoids
emoji: 🐨
colorFrom: gray
colorTo: purple
sdk: docker
pinned: false

SpecKit-Plus Backend (Humanoids)

This is the AI-powered backend for the Physical AI & Humanoid Robotics interactive textbook. It provides Retrieval-Augmented Generation (RAG) capabilities, allowing students to query textbook content and get context-aware explanations.

Directory Structure

backend/
├── main.py                 # Main FastAPI application entry point
├── configs/
│   └── config.py          # Configuration and model settings
├── services/
│   ├── rag.py            # RAG (Retrieval Augmented Generation) service
│   ├── indexer.py        # Document indexing for Qdrant vector database
│   └── chatkit_service.py # ChatKit server with RAG capabilities
├── data/
│   ├── vector_store.py   # Qdrant vector database operations
│   └── embeddings.py     # Embedding service using FastEmbed
├── simple_agents/
│   └── aagents.py        # Triage Agent definition
├── agents/
│   └── Runner.py         # Agent runner
├── tests/
│   ├── test_keys.py      # Configuration tests
│   └── test_rag.py       # RAG functionality tests
└── history/              # History of prompts and decisions
    ├── prompts/          # Prompt History Records (PHRs)
    └── adr/             # Architecture Decision Records (ADRs)

What Has Been Done

1. Code Organization & Structure

• Organized backend files into logical directories (configs, services, data, simple_agents, agents, tests)
• Fixed import paths across all files to work with new directory structure
• Centralized model configuration in configs/config.py

2. Qdrant Integration & RAG System

• Implemented document indexing system in services/indexer.py to upload documents from frontend/docs to Qdrant
• Fixed Qdrant ID validation issues by changing from file paths to UUIDs
• Created RAG service in services/rag.py for contextual query processing
• Connected the main Agent in main.py to use Qdrant context before responding
• Updated default collection name to "Humanoids" across all components

3. Agent Integration

• Connected the Triage Agent to use RAG context from Qdrant for more informed responses
• Updated API endpoints (/api/query and /api/selection) to incorporate RAG context

4. Configuration & Security

• Centralized configuration management with proper environment variable handling
• Fixed undefined variable issues in services

What Is Left

1. Testing & Verification

• Test complete RAG flow to verify Agent uses Qdrant context properly
• Verify responses include context from uploaded documents
• Confirm sources field is populated with document references

2. Documentation & History

• Create PHR for RAG integration work
• Finalize commit with all changes

API Endpoints

• GET / - Health check endpoint
• POST /api/query - General chat queries with RAG context
• POST /api/selection - Queries based on selected text with RAG context

Setup

1. Install dependencies: uv pip install -r requirements.txt
2. Set up environment variables in .env:

   QDRANT_URL=your_qdrant_url
   QDRANT_API_KEY=your_qdrant_api_key
   EXTERNAL_API_KEY=your_external_api_key
   

3. Index documents: python services/indexer.py
4. Start server: uv run --no-dev uvicorn main:app --reload --port=8000