Latoff/GR15ALF447

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

🤖 Kawasaki Robot Expert - RAG System

An intelligent AI assistant specialized in Kawasaki industrial robotics documentation and AS programming language. Built with hybrid vector search and advanced RAG (Retrieval-Augmented Generation) techniques.

🌟 Features

🧠 Intelligent Document Processing

• —Hybrid Vector Search: Combines ChromaDB semantic search + BM25 keyword matching
• —Smart Chunking: AS code-aware chunking for programming examples
• —Context Expansion: Automatically retrieves neighboring document sections
• —Multi-format Support: PDF, TXT, and AS code files

🎯 Specialized Knowledge Domains

• —AS Programming: Syntax, functions, procedures, motion commands
• —I/O Handling: Signal management and external equipment integration
• —Safety Procedures: Emergency protocols and safety guidelines
• —Troubleshooting: Diagnostic procedures and error resolution
• —Technical Specifications: Hardware specs and installation guides

📊 Advanced Visualization

• —t-SNE Embedding Clusters: Visualize document relationships
• —Interactive Document Explorer: Browse document sections
• —Debug Interface: View RAG prompts and search results
• —Real-time Statistics: Monitor database content

🔧 Developer Features

• —Modular Architecture: Separate vector store and agent components
• —Debug Tools: Comprehensive logging and search debugging
• —Flexible Configuration: Easy model and parameter adjustment
• —Extensible Design: Add new document types and LLM backends

🚀 Quick Start

1. Environment Setup

# Set your Fireworks AI API key
export FIREWORKS_API_KEY="your_fireworks_api_key_here"

2. Install Dependencies

uv sync
# or
pip install -r requirements.txt

3. Run the Application

uv run kawasaki-expert
# or
python app/main.py

4. Upload Documents

• —Navigate to the "➕ Add Document" tab
• —Upload your robotics documentation (PDF, TXT, AS files)
• —Select appropriate document type
• —System automatically indexes and processes content

📁 Document Organization

The system organizes documents into specialized categories:

• —`Practical_Recomendations/` - Procedures, I/O specifications, teaching methods
• —`Programming_Language_and_Examples/` - AS language reference, syntax guides
• —`Reference/` - Technical handbooks, specifications, general robotics
• —`Code_Examples/` - AS programming examples, function libraries
• —`General_Robotics/` - General robotics knowledge and principles

🎮 Usage Examples

Basic Queries

"What are the values for external equipment I/O?"
"How do I program a pick and place operation?"
"What are the safety procedures for robot maintenance?"

AS Programming

"Show me how to implement error handling in AS?"
"What's the syntax for motion commands?"
"Give me an example of I/O signal management"

Technical Troubleshooting

"How do I troubleshoot communication errors?"
"What are the calibration procedures for a new robot?"
"Explain the tip compensation reset procedure"

🏗️ Architecture

Hybrid Vector Store

• —ChromaDB: Persistent vector database with cosine similarity
• —SentenceTransformers: all-MiniLM-L6-v2 for embeddings
• —BM25: Keyword-based retrieval for technical terms
• —Smart Chunking: Content-aware document splitting

Agent System

• —Fireworks AI: Qwen 2.5 72B model for responses
• —Context Expansion: Retrieves neighboring document sections
• —Source Citation: Automatic reference to specific documents/sections
• —Memory Management: Conversation history with debug info

Web Interface

• —Gradio: Interactive chat interface
• —Real-time Visualization: t-SNE embedding clusters
• —Debug Tools: Prompt inspection and search result analysis
• —Document Management: Upload and browse capabilities

🔬 Technical Details

Chunking Strategies

• —Code Files: 3000 chars, AS-aware separators (END FUNCTION, END PROCEDURE)
• —Documentation: 6000 chars, semantic separators for complete procedures
• —Context Expansion: Retrieves 5 neighboring sections with proximity scoring

Search Algorithm

1. 1.Semantic Search: Vector similarity using embeddings
2. 2.Keyword Search: BM25 scoring for technical terms
3. 3.Hybrid Scoring: Weighted combination (70% semantic, 30% keyword)
4. 4.Context Expansion: Add neighboring chunks from top results
5. 5.Ranking: Sort by combined relevance score

Performance Optimizations

• —Intelligent Sampling: Max 2000 points for visualization
• —Efficient Indexing: Incremental BM25 rebuilding
• —Memory Management: Conversation history pruning
• —Caching: Persistent vector storage

🛠️ Development

Project Structure

app/
├── vector_store.py      # Hybrid vector search system
├── robot_agent.py       # AI agent and chat interface
├── ui_gradio.py         # Web interface components
├── main.py             # Application entry point
└── agent_kawasaki.py   # Legacy compatibility layer

Adding New Document Types

1. 1.Create folder in app/data/YourDocumentType/
2. 2.Add documents (PDF, TXT, AS files)
3. 3.System automatically detects and processes

Extending LLM Support

Modify robot_agent.py to support different models:

self.current_model = "your_preferred_model"

📊 Performance Metrics

• —Database Size: Supports 3000+ document chunks
• —Search Speed: Sub-second retrieval for most queries
• —Context Size: Up to 16 expanded sections per query
• —Visualization: Handles 2000+ points with t-SNE
• —Memory: Efficient conversation history management

🤝 Contributing

1. 1.Fork the repository
2. 2.Create a feature branch
3. 3.Add your improvements
4. 4.Test with robotics documentation
5. 5.Submit a pull request

📄 License

This project is open source and available under the MIT License.

🙏 Acknowledgments

• —Kawasaki Robotics for comprehensive technical documentation
• —ChromaDB for vector storage capabilities
• —Fireworks AI for powerful language model inference
• —Gradio for intuitive web interface
• —Sentence Transformers for semantic embeddings

Built for robotics engineers, by robotics engineers. Making technical documentation instantly accessible through AI.