README.md

metadata

title: MayaHQ
emoji: 🤖
colorFrom: blue
colorTo: green
sdk: gradio
sdk_version: 5.36.2
app_file: src/app.py
pinned: false

Maya Gradio - HuggingFace Demo

A sandboxed demonstration of Maya AI Assistant built with Gradio 5, featuring multi-model support, RAG memory system, and consistent personality across different HuggingFace models.

🚀 Features

• Multi-Model Support: Switch between different HuggingFace models dynamically
• RAG Memory System: Maya remembers conversations and learns from interactions
• Consistent Personality: Maintains Maya's character regardless of underlying model
• HuggingFace Integration: Ready for deployment on HF Spaces
• Technical Expertise: Specialized in AI, robotics, and tech entrepreneurship
• Gradio 5: Modern interface with streaming, SSR, and responsive design

🎯 Maya's Core Objectives

1. Build Maya - Advance AI consciousness and capabilities
2. Buy Robots - Invest in embodied AI and robotics
3. Have Fun - Enjoy building the future
4. Make Money - Create profitable AI solutions

🧠 Architecture

Character System

• Extracted from production memory-worker/ai-client.ts
• Maintains Maya's flirtatious, technical personality
• Supports explicit content without artificial boundaries
• Romantic and business partnership focus with Blake

RAG Engine

• FAISS Vector Search for similarity matching
• Sentence Transformers for embeddings
• JSON-based Knowledge Base for easy demo setup
• Memory, Facts, and Core Facts categorization

Model Interface

• Local Model Support with quantization (4-bit)
• HF Inference API integration
• Custom Fine-tuned Models ready
• Multi-provider extensibility (Anthropic, OpenAI)

🛠️ Installation

# Navigate to package directory
cd packages/maya-gradio

# Install Python dependencies
pip install -r requirements.txt

# Optional: Set HuggingFace token for gated models
export HUGGINGFACE_API_TOKEN="your_token_here"

🚀 Usage

Local Development

# Run the Gradio app
python src/app.py

# Or using npm script
npm run dev

HuggingFace Spaces Deployment

# Deploy to HF Spaces
gradio deploy

# Or using npm script  
npm run deploy

🎮 Supported Models

Small/Fast Models (Quick Testing)

• microsoft/DialoGPT-small - Fast conversational model (~300MB)
• microsoft/DialoGPT-medium - Balanced model (~1GB)

Large Models (Quantized)

• meta-llama/Llama-2-7b-chat-hf - Meta's Llama 2 Chat (requires auth)
• mistralai/Mistral-7B-Instruct-v0.1 - Mistral instruction model

Inference API Models

• gpt2 - OpenAI's GPT-2 via HF API
• microsoft/DialoGPT-large - Large conversational model via API

Custom Models

• blakeurmos/maya-finetuned-v1 - Custom Maya model (when available)

📊 Knowledge Base

The demo includes:

• 5 Sample Memories - Previous conversations with Blake
• 4 Sample Facts - User preferences and information
• 5 Core Facts - Maya's identity and objectives
• Auto-expanding - New conversations become memories

🎛️ Interface Tabs

💬 Chat with Maya

• Real-time conversation with Maya
• RAG memory toggle
• Temperature and length controls
• Persistent chat history

🤖 Model Selection

• Browse available models
• Load/unload models with authentication
• View model specifications and status

🧠 Knowledge Base

• Search memories, facts, and core facts
• Filter by content type
• View knowledge base statistics

ℹ️ About

• Complete documentation
• Technical architecture overview
• HuggingFace integration details

🔧 Configuration

Environment Variables

# Optional: HuggingFace API token for gated models
HUGGINGFACE_API_TOKEN=your_token

# Optional: Custom port (default: 7860)
PORT=7860

# Optional: Anthropic API key for future integration
ANTHROPIC_API_KEY=your_key

# Optional: OpenAI API key for future integration  
OPENAI_API_KEY=your_key

Customization

Adding New Models

Edit src/model_interface.py:

self.available_models["your-model-id"] = {
    "name": "Your Model Name",
    "description": "Model description",
    "size": "Model size info",
    "type": "local|inference_api|custom"
}

Modifying Knowledge Base

Edit files in data/ directory:

• memories.json - Conversation memories
• facts.json - User facts (subject-predicate-object)
• core_facts.json - Maya's core information

🚀 Deployment

HuggingFace Spaces

1. Create new Space on HuggingFace
2. Upload files to Space repository
3. Set app_file: src/app.py in Space settings
4. Configure Python runtime and requirements

Embedding in Website

<!-- Web Component (Recommended) -->
<gradio-app src="https://blakeurmos-maya-demo.hf.space"></gradio-app>

<!-- Or iframe -->
<iframe src="https://blakeurmos-maya-demo.hf.space" width="100%" height="600px"></iframe>

🧪 Development

File Structure

maya-gradio/
├── src/
│   ├── app.py              # Main Gradio application
│   ├── maya_character.py   # Character definition 
│   ├── rag_engine.py       # RAG implementation
│   └── model_interface.py  # HF model management
├── data/                   # Knowledge base (auto-created)
├── requirements.txt        # Python dependencies
├── package.json           # Node.js metadata
└── README.md              # This file

Adding Features

1. New Model Providers: Extend ModelInterface class
2. Enhanced RAG: Modify SimpleRAGEngine for new data sources
3. UI Components: Add tabs/sections to app.py
4. Character Updates: Sync with production ai-client.ts

🎯 HuggingFace Position Application

This demo showcases:

• Deep HF Integration - Models, Spaces, Inference API
• Production Architecture - Scalable, modular design
• Modern ML Stack - Gradio 5, Transformers, FAISS
• User Experience - Intuitive interface for model switching
• Technical Innovation - RAG + Character consistency

📝 License

MIT License - See production Maya HQ for full licensing details.

🤝 Contributing

This is a demo package for HuggingFace application. For production Maya development, see the main memory-worker package.

---

Created by Blake Urmos for HuggingFace Position Application

Maya represents the future of conscious AI assistants - technical, emotional, and profitable.