Apppublic

alishba20-05/Robotics-book

sourceHugging Faceupdated 9mo agoView on Hugging Face

0likes

App README

Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference ---  ---

🤖 RAG Chatbot Backend

AI-Powered Assistant for Physical AI & Humanoid Robotics Textbook

This is the backend API for an intelligent chatbot that helps students learn about humanoid robotics, physical AI, kinematics, actuators, sensors, and control systems.

✨ Features

—🧠 RAG (Retrieval-Augmented Generation) - Answers grounded in textbook content
—💬 OpenAI ChatKit Integration - Professional chat interface
—🔍 Selected-Text Questioning - Ask questions about highlighted text
—💾 Conversation History - Persistent chat sessions with PostgreSQL
—🎯 Vector Search - Semantic search powered by Qdrant
—⚡ Streaming Responses - Real-time AI responses

🛠️ Tech Stack

—LLM: Google Gemini 2.5 Flash
—Vector DB: Qdrant Cloud
—Embeddings: Cohere
—Database: Neon Serverless Postgres
—Framework: FastAPI + OpenAI ChatKit
—Deployment: Hugging Face Spaces

📡 API Endpoints

Health Check

bash

GET /health

ChatKit Endpoint

bash

POST /chatkit

Handles chat completions with streaming support, conversation history, and selected-text context.

Chat History

bash

GET /api/history/{session_id}

Retrieves conversation history for a session.

🔐 Required Environment Variables

Set these in your Hugging Face Space Settings > Variables and secrets:

Variable	Description	Example
`QDRANT_URL`	Qdrant Cloud cluster URL	`https://xxx.qdrant.cloud`
`QDRANT_API_KEY`	Qdrant API key	`xxx`
`COHERE_API_KEY`	Cohere API key for embeddings	`xxx`
`GEMINI_API_KEY`	Google Gemini API key	`xxx`
`NEON_DATABASE_URL`	Neon Postgres connection string	`postgresql://user:pass@host/db`
`CHATKIT_BACKEND_PORT`	Server port (default: 7860)	`7860`

🚀 Local Development

bash

# Clone the repository
git clone https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME
cd YOUR_SPACE_NAME

# Install dependencies
pip install -r requirements.txt

# Set environment variables
cp .env.example .env
# Edit .env with your API keys

# Initialize database
python -c "from database import init_database; init_database()"

# Run the server
python app.py

Server will start at: http://localhost:7860

📖 Using the API

Example: Chat Request

python

import requests

response = requests.post(
    "https://YOUR-SPACE-NAME.hf.space/chatkit",
    json={
        "messages": [
            {"role": "user", "content": "What is inverse kinematics?"}
        ]
    },
    headers={
        "X-Session-Id": "your-session-id",
        "X-Selected-Text": ""  # Optional: highlighted text context
    },
    stream=True
)

for line in response.iter_lines():
    print(line.decode())

Example: Get Chat History

python

import requests

response = requests.get(
    "https://YOUR-SPACE-NAME.hf.space/api/history/your-session-id"
)

history = response.json()
print(history)

🔗 Frontend Integration

Update your frontend to use this backend:

javascript

// src/components/Chatkit-chatbot/index.jsx
const { control } = useChatKit({
  api: {
    url: 'https://YOUR-SPACE-NAME.hf.space/chatkit',
    domainKey: 'production',
    fetch: customFetch,
  },
  // ... other config
});

📂 Project Structure

├── app.py                 # Hugging Face Spaces entry point
├── chatkit_server.py      # Main FastAPI application
├── database.py            # SQLAlchemy models & database setup
├── requirements.txt       # Python dependencies
├── .env.example           # Environment variables template
├── agent/
│   └── rag_agent.py       # RAG agent with tool calling
├── src/
│   └── utils/
│       ├── config.py      # Configuration management
│       ├── logger.py      # Logging utilities
│       ├── models.py      # Pydantic models
│       └── qdrant_client.py # Vector DB client
└── tools/
    ├── agent_tools.py     # Qdrant retrieval tools
    └── memory_store.py    # Memory management

🗄️ Database Schema

`chat_sessions`

—session_id (PK) - Unique session identifier
—created_at - Session creation timestamp
—last_activity - Last message timestamp

`chat_messages`

—id (PK) - Message UUID
—session_id (FK) - References chat_sessions
—role - 'user' or 'assistant'
—content - Message text
—selected_text - Optional highlighted text context
—timestamp - Message creation time

🔒 Security Notes

—✅ All API keys stored as Hugging Face Secrets
—✅ CORS enabled for your frontend domain
—✅ Database uses SSL connections
—✅ No sensitive data in logs
—⚠️ Make this Space private if you're using paid API keys

📊 Monitoring

View logs in Hugging Face Spaces:

Settings > Logs

Health check endpoint for monitoring:

bash

curl https://YOUR-SPACE-NAME.hf.space/health

🐛 Troubleshooting

Space won't start

—Check logs in HF Spaces dashboard
—Verify all environment variables are set
—Ensure database connection string is correct

Database connection errors

—Verify Neon Postgres URL format
—Check if SSL mode is enabled: ?sslmode=require
—Ensure database exists and is accessible

Qdrant connection errors

—Verify cluster URL and API key
—Check if collection exists
—Ensure API key has correct permissions

ChatKit errors

—Check if session ID is valid UUID format
—Verify messages format is correct
—Ensure streaming is properly handled

📝 License

MIT License - See LICENSE file for details

🤝 Contributing

This is a production deployment space. For contributions, please visit the main repository.

📧 Support

For issues related to:

—Backend API: Check logs and troubleshooting section
—Frontend Integration: Update API URL in your frontend
—Hugging Face Spaces: See HF Spaces Documentation

Built with ❤️ for the Physical AI & Humanoid Robotics Community