Spaces:
Sleeping
Sleeping
| 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` |