adding files again

.gitignore

@@ -0,0 +1,124 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Virtual environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# IDEs and editors
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Operating System
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+
+# uv
+uv.lock
+
+# Logs
+*.log
+
+# Runtime data
+pids
+*.pid
+*.seed
+*.pid.lock
+
+# Optional npm cache directory (if you use any JS tools)
+.npm
+
+# Optional eslint cache
+.eslintcache
+
+# Microbundle cache
+.rpt2_cache/
+.rts2_cache_cjs/
+.rts2_cache_es/
+.rts2_cache_umd/
+
+# Optional REPL history
+.node_repl_history
+
+# Output of 'npm pack'
+*.tgz
+
+# Yarn Integrity file
+.yarn-integrity
+
+# dotenv environment variables file
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+# Temporary folders
+tmp/
+temp/
+
+# Project-specific
+*.sqlite
+*.db

README.md

@@ -11,4 +11,208 @@ license: mit
 short_description: An MCP server that navigates through your docs!
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Docs Navigator MCP
+A powerful documentation assistant that combines **Model Context Protocol (MCP)** with **Claude AI** to provide intelligent Q&A over your documentation files. Built with FastMCP and Gradio for an easy-to-use web interface.
+
+## ✨ Features
+
+- 🔍 **Smart Document Search**: Full-text search across your documentation files
+- 🤖 **AI-Powered Responses**: Uses Claude AI to provide intelligent answers based on your docs
+- 📁 **Multi-Format Support**: Works with `.md`, `.txt`, `.rst`, and `.pdf` files
+- 🌐 **Web Interface**: Clean Gradio-based chat interface
+- ⚡ **MCP Integration**: Leverages Model Context Protocol for seamless tool integration
+- 🔧 **Easy Setup**: Simple configuration and deployment
+- 📄 **PDF Support**: Extract and analyze text from PDF documents
+
+## 🏗️ Architecture
+
+```
+┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
+│   Gradio UI     │───▶│   Client Agent   │───▶│   Claude AI     │
+│  (Chat Interface)│    │  (MCP Client)    │    │   (Anthropic)   │
+└─────────────────┘    └──────────────────┘    └─────────────────┘
+                                │
+                                ▼
+                       ┌──────────────────┐
+                       │   MCP Server     │
+                       │  (FastMCP)       │
+                       └──────────────────┘
+                                │
+                                ▼
+                       ┌──────────────────┐
+                       │   docs/ folder   │
+                       │  (.md, .txt,     │
+                       │   .rst files)    │
+                       └──────────────────┘
+```
+
+## 🚀 Quick Start
+
+### Prerequisites
+
+- Python 3.10 or higher
+- An Anthropic API key
+- UV package manager (recommended) or pip
+
+### 1. Clone and Setup
+
+```bash
+git clone <your-repo-url>
+cd docs-navigator
+```
+
+### 2. Install Dependencies
+
+Using UV (recommended):
+```bash
+uv sync
+```
+
+Or using pip:
+```bash
+pip install -r requirements.txt
+```
+
+### 3. Configure Environment
+
+Create a `.env` file:
+```bash
+echo "ANTHROPIC_API_KEY=your_api_key_here" > .env
+```
+
+### 4. Add Your Documentation
+
+Place your documentation files in the `docs/` directory:
+```
+docs/
+├── overview.md
+├── setup.md
+├── troubleshooting.md
+└── your-other-docs.txt
+```
+
+### 5. Launch the Application
+
+```bash
+# Using UV
+uv run app_gradio.py
+
+# Or directly with Python
+python app_gradio.py
+```
+
+The app will be available at `http://127.0.0.1:7860`
+
+## 📚 Usage Examples
+
+Once the app is running, you can ask questions like:
+
+- "How do I set up the authentication?"
+- "What are the troubleshooting steps for connection issues?"
+- "Where can I find information about API endpoints?"
+- "Summarize the main features mentioned in the docs"
+
+The AI will search through your documentation and provide contextual answers with references to the source files.
+
+## 🛠️ Development
+
+### Project Structure
+
+```
+docs-navigator/
+├── app_gradio.py          # Gradio web interface
+├── client_agent.py        # MCP client and Claude integration
+├── server_docs.py         # MCP server with doc tools
+├── docs/                  # Your documentation files
+├── tests/                 # Test scripts
+│   ├── test_mcp.py       # Test MCP server functionality
+│   ├── test_anthropic.py # Test Claude API connection
+│   └── test_complete.py  # End-to-end functionality test
+├── .env                   # Environment variables
+├── pyproject.toml         # Project configuration
+└── requirements.txt       # Python dependencies
+```
+
+### Available MCP Tools
+
+The server exposes these tools to the AI:
+
+1. **`list_docs()`**: Get a list of all available documentation files
+2. **`search_docs(query, max_results)`**: Search for specific content across all docs
+
+### Testing
+
+Run the test suite:
+
+```bash
+# Test MCP server functionality
+python test_mcp.py
+
+# Test Claude API connection
+python test_anthropic.py
+
+# Test complete end-to-end functionality
+python test_complete.py
+```
+
+## 🔧 Configuration
+
+### Environment Variables
+
+| Variable | Description | Required |
+|----------|-------------|----------|
+| `ANTHROPIC_API_KEY` | Your Anthropic Claude API key | Yes |
+
+### Supported File Formats
+
+- **Markdown**: `.md`
+- **Text**: `.txt`
+- **reStructuredText**: `.rst`
+- **PDF Documents**: `.pdf` (text extraction)
+
+### Model Configuration
+
+The app currently uses `claude-3-haiku-20240307`. To change the model, edit the model name in `client_agent.py`:
+
+```python
+model="claude-3-haiku-20240307"  # Change to your preferred model
+```
+
+## 🐛 Troubleshooting
+
+### Common Issues
+
+1. **"Model not found" error**: Your API key may not have access to the specified Claude model. The app will automatically test available models.
+
+2. **MCP connection issues**: Ensure the `server_docs.py` script is executable and in the correct location.
+
+3. **No documents found**: Make sure your documentation files are in the `docs/` folder with supported extensions.
+
+4. **Gradio interface not loading**: Check that port 7860 is available or modify the port in `app_gradio.py`.
+
+### Debug Mode
+
+Enable verbose logging by modifying the logging level in the respective files.
+
+## 🤝 Contributing
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## 🙏 Acknowledgments
+
+- Built with [FastMCP](https://github.com/modelcontextprotocol/mcp) for Model Context Protocol integration
+- Powered by [Anthropic Claude](https://www.anthropic.com/) for AI responses
+- UI created with [Gradio](https://gradio.app/)
+- Package management with [UV](https://docs.astral.sh/uv/)
+
+---
+
+For more detailed instructions, see the [Getting Started Guide](/guides/GETTING_STARTED.md).

app copy.py

@@ -0,0 +1,38 @@
+#!/usr/bin/env python3
+"""
+Docs Navigator MCP - Launcher Script
+
+This script launches Gradio UI for the Docs Navigator MCP application.
+"""
+
+import os
+import sys
+from pathlib import Path
+
+# Add the project root to the Python path
+project_root = Path(__file__).parent
+sys.path.insert(0, str(project_root))
+
+# Change to project directory to ensure relative paths work
+os.chdir(project_root)
+
+# Import and run the app
+from src.ui.app import demo
+
+def main():
+    """Main entry point for the application."""
+    print("🚀 Starting Docs Navigator MCP...")
+    print("📚 AI-Powered Documentation Assistant")
+    print("🌐 The app will be available at: http://127.0.0.1:7863")
+    print("💡 Ask questions about your documentation!")
+    print("-" * 50)
+    
+    demo.launch(
+        server_name="127.0.0.1",
+        server_port=7863,
+        show_error=True,
+        share=False  # Set to True if you want a public link
+    )
+
+if __name__ == "__main__":
+    main()

docs/PDF_TESTING_README.md

@@ -0,0 +1,27 @@
+# PDF Support Testing
+
+## How to Test PDF Functionality
+
+1. **Add a PDF file** to the `docs/` folder
+2. **Run the test script**: `python tests/test_pdf_support.py`
+3. **Use the Gradio interface** to ask questions about your PDF content
+
+## Supported PDF Features
+
+- Text extraction from all pages
+- Full-text search across PDF content  
+- AI-powered Q&A over PDF documents
+- Section analysis and summarization
+- PDF content integrated with other docs
+
+## Example Questions to Try
+
+- "What topics are covered in the PDF?"
+- "Summarize the main points from the PDF"
+- "Search for [specific term] in all documents"
+
+## Notes
+
+- PDFs with images/scanned text require OCR (not yet implemented)
+- Complex layouts may have formatting issues
+- Page numbers are preserved for reference

docs/auroraai_report.txt

@@ -0,0 +1,62 @@
+AuroraAI Technical Report
+
+AuroraAI is an enterprise-grade multimodal assistant designed for
+documentation, engineering analysis, and workflow automation.
+
+Core Capabilities
+
+-   Long-context reasoning (200k tokens)
+-   Code generation and API reasoning
+-   Retrieval-augmented responses
+-   Document drafting, editing, and summarization
+-   Secure, role-based enterprise integration
+
+Architecture Summary
+
+AuroraAI is a 70B-parameter transformer model featuring: - Hierarchical
+and sliding-window attention mechanisms - 8192-dimensional hidden
+layers - 96 transformer blocks - 64 attention heads - SwiGLU-activated
+feed-forward networks - Rotary positional embeddings with extended
+scaling
+
+Training Methodology
+
+AuroraAI was trained using: - Autoregressive next-token prediction - A
+mixture of technical documentation, code corpora, research texts, RFCs,
+and synthetic alignment sets - AdamW optimization with warmup and cosine
+decay - Distributed training across 1024–4096 GPUs - BF16
+mixed-precision gradient computation - Redundant asynchronous
+checkpointing
+
+Evaluation Results
+
+-   HumanEval+ accuracy: 86%
+-   Document QA improvement: +22% over baseline
+-   Retrieval fidelity: 99% at 200k-token context
+-   Hallucination rate reduction: 38% via strict retrieval routing
+
+Safety & Alignment
+
+AuroraAI employs: - Supervised fine-tuning on technical reasoning
+tasks - Reinforcement learning from human preferences - Multi-layer
+content filtering - Policy-driven guardrails engine - Encrypted opt-in
+user memory with immediate deletion controls
+
+Intended Use Cases
+
+AuroraAI performs best in: - Developer documentation workflows - API
+lifecycle and architectural content creation - Engineering ticket
+summarization - Knowledge retrieval from large document bases -
+Enterprise search and analysis tasks
+
+Limitations
+
+AuroraAI is not optimized for: - Unsupervised high-risk autonomous
+decision making - Medical, legal, or hazardous domain outputs without
+human review - Context-free speculation or queries lacking grounding
+data
+
+Version Information
+
+AuroraAI v1.0 - Expanded to 200k token window - Upgraded retrieval
+engine - Added enterprise integration modules

docs/configuration.md

@@ -0,0 +1,226 @@
+# Configuration Options
+
+This document discusses the various configuration options available for Aurora AI.
+
+## Overview
+
+Aurora AI provides a comprehensive configuration framework supporting multi-tenancy, enterprise-grade security, and extensible integration patterns. The system employs a hierarchical configuration model with environment-specific overrides, schema validation, and runtime hot-reloading capabilities.
+
+## Core Configuration Architecture
+
+### Configuration Hierarchy
+
+Aurora AI implements a cascading configuration system with the following precedence order:
+
+1. **Runtime overrides** - Programmatic configuration via API
+2. **Environment variables** - System-level configuration with `AURORA_` prefix
+3. **Configuration files** - YAML/JSON/TOML format files
+4. **Default values** - Embedded fallback configuration
+
+### Configuration File Structure
+
+```yaml
+aurora:
+    engine:
+        inference_backend: "transformers"
+        model_path: "/models/aurora-v3"
+        device_map: "auto"
+        quantization:
+            enabled: true
+            bits: 4
+            scheme: "gptq"
+    runtime:
+        max_concurrent_requests: 128
+        request_timeout_ms: 30000
+        graceful_shutdown_timeout: 60
+```
+
+## Model Configuration
+
+### Inference Engine Parameters
+
+- **`model_path`**: Filesystem path or Hugging Face model identifier
+- **`device_map`**: Hardware allocation strategy (`auto`, `balanced`, `sequential`, or custom JSON mapping)
+- **`torch_dtype`**: Precision mode (`float32`, `float16`, `bfloat16`, `int8`, `int4`)
+- **`attention_implementation`**: Mechanism selection (`flash_attention_2`, `sdpa`, `eager`)
+- **`rope_scaling`**: Rotary Position Embedding interpolation configuration
+- **`kv_cache_dtype`**: Key-value cache quantization type
+
+### Quantization Strategies
+
+Aurora AI supports multiple quantization backends:
+
+- **GPTQ**: 4-bit grouped quantization with calibration datasets
+- **AWQ**: Activation-aware weight quantization
+- **GGUF**: CPU-optimized quantization format
+- **BitsAndBytes**: Dynamic 8-bit and 4-bit quantization
+
+## API Configuration
+
+### REST API Settings
+
+```yaml
+api:
+    host: "0.0.0.0"
+    port: 8080
+    workers: 4
+    uvicorn:
+        loop: "uvloop"
+        http: "httptools"
+        log_level: "info"
+    cors:
+        enabled: true
+        origins: ["https://*.example.com"]
+        allow_credentials: true
+    rate_limiting:
+        enabled: true
+        requests_per_minute: 60
+        burst_size: 10
+```
+
+### Authentication & Authorization
+
+- **API Key Authentication**: Header-based (`X-API-Key`) or query parameter
+- **OAuth 2.0**: Support for Authorization Code and Client Credentials flows
+- **JWT Tokens**: RS256/ES256 signature verification with JWKS endpoints
+- **mTLS**: Mutual TLS authentication for service-to-service communication
+
+## Integration Patterns
+
+### Vector Database Integration
+
+Aurora AI integrates with enterprise vector stores:
+
+```yaml
+vector_store:
+    provider: "pinecone"  # or "weaviate", "qdrant", "milvus", "chromadb"
+    connection:
+        api_key: "${PINECONE_API_KEY}"
+        environment: "us-west1-gcp"
+        index_name: "aurora-embeddings"
+    embedding:
+        model: "text-embedding-3-large"
+        dimensions: 3072
+        batch_size: 100
+```
+
+### Message Queue Integration
+
+Asynchronous processing via message brokers:
+
+- **RabbitMQ**: AMQP 0-9-1 protocol with exchange routing
+- **Apache Kafka**: High-throughput event streaming with consumer groups
+- **Redis Streams**: Lightweight pub/sub with consumer group support
+- **AWS SQS/SNS**: Cloud-native queue and notification services
+
+### Observability Stack
+
+```yaml
+observability:
+    metrics:
+        provider: "prometheus"
+        port: 9090
+        path: "/metrics"
+    tracing:
+        provider: "opentelemetry"
+        exporter: "otlp"
+        endpoint: "http://jaeger:4317"
+        sampling_rate: 0.1
+    logging:
+        level: "INFO"
+        format: "json"
+        output: "stdout"
+```
+
+## Memory Management
+
+### Cache Configuration
+
+```yaml
+cache:
+    inference_cache:
+        enabled: true
+        backend: "redis"
+        ttl_seconds: 3600
+        max_size_mb: 2048
+    prompt_cache:
+        enabled: true
+        strategy: "semantic_hash"
+        similarity_threshold: 0.95
+```
+
+### Context Window Management
+
+- **Sliding Window**: Maintains fixed-size context with FIFO eviction
+- **Semantic Compression**: Entropy-based summarization for long contexts
+- **Hierarchical Attention**: Multi-level context representation
+- **External Memory**: Vector store-backed infinite context
+
+## Distributed Deployment
+
+### Kubernetes Configuration
+
+```yaml
+deployment:
+    replicas: 3
+    strategy: "RollingUpdate"
+    resources:
+        requests:
+            cpu: "4000m"
+            memory: "16Gi"
+            nvidia.com/gpu: "1"
+        limits:
+            cpu: "8000m"
+            memory: "32Gi"
+            nvidia.com/gpu: "1"
+    autoscaling:
+        enabled: true
+        min_replicas: 2
+        max_replicas: 10
+        target_cpu_utilization: 70
+```
+
+### Service Mesh Integration
+
+Aurora AI supports Istio, Linkerd, and Consul service mesh architectures with:
+
+- **Traffic management**: Weighted routing, circuit breaking, retries
+- **Security**: mTLS encryption, authorization policies
+- **Observability**: Distributed tracing, metrics aggregation
+
+## Advanced Features
+
+### Custom Plugin System
+
+```yaml
+plugins:
+    enabled: true
+    plugin_path: "/opt/aurora/plugins"
+    plugins:
+        - name: "custom_tokenizer"
+            module: "aurora.plugins.tokenizers"
+            config:
+                vocab_size: 65536
+        - name: "retrieval_augmentation"
+            module: "aurora.plugins.rag"
+            config:
+                top_k: 5
+                rerank: true
+```
+
+### Multi-Model Orchestration
+
+Configure model routing and ensemble strategies:
+
+- **Load-based routing**: Distribute requests based on model server load
+- **A/B testing**: Traffic splitting for model evaluation
+- **Cascade patterns**: Fallback to alternative models on failure
+- **Ensemble voting**: Aggregate predictions from multiple models
+
+## Security Hardening
+
+- **Secrets management**: Integration with HashiCorp Vault, AWS Secrets Manager
+- **Network policies**: Zero-trust networking with pod security policies
+- **Input sanitization**: Prompt injection and jailbreak detection
+- **Output filtering**: PII redaction and content safety validation
+- **Audit logging**: Immutable logs with cryptographic verification

docs/overview.md

@@ -0,0 +1,86 @@
+# Aurora AI Overview
+
+This documentation provides an overview of Aurora AI, its architecture, and how it works.
+
+## Architecture
+
+AuroraAI follows a modular, plugin-based architecture that enables extensibility and scalability:
+
+```mermaid
+graph TD
+    A[User Interface] --> B[Core Engine]
+    B --> C[Plugin Manager]
+    C --> D[Knowledge Base Plugin]
+    C --> E[API Integration Plugin]
+    C --> F[Analytics Plugin]
+    B --> G[Context Manager]
+    G --> H[Session State]
+    G --> I[Memory Store]
+```
+
+## Supported Models
+
+AuroraAI supports multiple AI model providers to suit different use cases and deployment requirements:
+
+| Provider | Model | Context Window | Best For |
+|----------|-------|----------------|----------|
+| OpenAI | GPT-4 Turbo | 128K tokens | Complex reasoning, code generation |
+| OpenAI | GPT-3.5 Turbo | 16K tokens | Fast responses, general queries |
+| Anthropic | Claude 3 Opus | 200K tokens | Long document analysis |
+| Anthropic | Claude 3 Sonnet | 200K tokens | Balanced performance |
+| Local | Llama 2 | 4K tokens | Privacy-sensitive deployments |
+
+## System Requirements
+
+| Component | Minimum | Recommended |
+|-----------|---------|-------------|
+| CPU | 4 cores | 8+ cores |
+| RAM | 8 GB | 16+ GB |
+| Storage | 10 GB | 50+ GB (with local models) |
+| Network | 10 Mbps | 100+ Mbps |
+
+## Plugin Ecosystem
+
+AuroraAI's functionality can be extended through plugins:
+
+- **Documentation Plugins**: Confluence, SharePoint, Notion, GitBook
+- **Development Tools**: GitHub, GitLab, Jira, Linear
+- **Communication**: Slack, Microsoft Teams, Discord
+- **Data Sources**: SQL databases, REST APIs, GraphQL endpoints
+
+## Security & Compliance
+
+- **Authentication**: OAuth 2.0, SAML, API keys
+- **Encryption**: AES-256 at rest, TLS 1.3 in transit
+- **Access Control**: Role-based permissions (RBAC)
+- **Audit Logging**: Complete activity tracking
+- **Compliance**: SOC 2 Type II, GDPR, HIPAA-ready
+
+## Performance Metrics
+
+Typical response times under standard load:
+
+| Operation | Avg Response Time | Throughput |
+|-----------|------------------|------------|
+| Simple query | < 2 seconds | 100 req/min |
+| Document search | < 3 seconds | 60 req/min |
+| Code generation | 3-5 seconds | 40 req/min |
+| Long document analysis | 8-15 seconds | 20 req/min |
+
+
+## What Is AuroraAI?
+AuroraAI is a lightweight, multimodal AI assistant designed to help teams write, search, analyze, and automate workflows across enterprise environments. It integrates seamlessly with documentation platforms, internal tools, and external APIs.
+
+## Key Features
+- Natural language understanding for queries, tasks, and workflows.
+- Plugin-based architecture for integrating knowledge bases, project systems, and developer tools.
+- Context-aware responses optimized for technical writing and software development.
+- Secure by design, with role-based access and encrypted local config.
+
+## Ideal Use Cases
+- Generating and editing documentation.
+- Summarizing tickets, requirements, and engineering discussions.
+- Producing API specs, code snippets, troubleshooting trees, and templates.
+- Providing real-time answers based on uploaded files or internal docs.
+
+

docs/prompting-guidelines.md

@@ -0,0 +1,23 @@
+# AuroraAI Prompting Guidelines
+
+
+## Best Practices
+- **Be explicit** about the output format (tables, JSON, Markdown, etc.).
+- **Provide context** such as code samples, user stories, or error logs.
+- **Use constraints** like tone, word limits, or style rules.
+- **Iterate** by refining instructions rather than restarting.
+
+## Example Prompts
+### Technical Writing Prompt
+"Rewrite this API overview in a concise style and include an authentication section. Output in Markdown."
+
+### Engineering Prompt
+"Given this error log, diagnose the root cause and propose three fixes ranked by difficulty."
+
+### Documentation Prompt
+"Create troubleshooting steps for users who can't authenticate. Include a table of error codes."
+
+## Anti-Patterns to Avoid
+- Vague commands like "Fix this".
+- Multi-task prompts that blend unrelated asks.
+- Lack of constraints when requesting decisions.

docs/setup.md

@@ -0,0 +1,42 @@
+# AuroraAI Setup Guide
+
+## Prerequisites
+- Node.js 18+ or Python 3.10+
+- Access to the AuroraAI developer portal
+- API key with Assistant-level permissions
+- Optional: GitHub, Jira, or Confluence integration tokens
+
+## Installation
+```bash
+yarn global add auroraai
+# OR
+pip install auroraai-cli
+```
+
+## Initialization
+```bash
+aurora init
+```
+This command:
+- Creates a project directory
+- Generates a `.aurora/config.json` file
+- Prompts you to add your API key
+
+## Configuration File Example
+```json
+{
+  "apiKey": "YOUR_API_KEY",
+  "model": "aurora-pro",
+  "contextWindow": 200000,
+  "integrations": {
+    "github": true,
+    "jira": false
+  }
+}
+```
+
+## Connecting Knowledge Sources
+```bash
+aurora connect ./docs
+```
+This indexes your local documentation for retrieval.

docs/troubleshooting.md

@@ -0,0 +1,247 @@
+# AuroraAI Troubleshooting Guide
+
+## Common Issues & Fixes
+
+### 1. Assistant Not Responding
+**Symptoms:** Long delays or no output.
+
+**Possible Causes & Fixes:**
+- Network issue → Check VPN/firewall.
+- Expired API key → Run `aurora auth refresh`.
+- Large file uploads throttled → Compress or split files.
+
+### 2. Incorrect or Irrelevant Answers
+**Symptoms:** Hallucinations, outdated info.
+
+**Fixes:**
+- Re-index documentation: `aurora connect ./docs --force`.
+## Troubleshooting Connection Issues
+
+### Symptoms
+- Failed API requests or timeouts
+- Unable to connect to external services (GitHub, Jira, etc.)
+- Network-related error messages
+
+### Common Causes and Solutions
+
+#### Network Connectivity
+- **Check internet connection**: Verify your network is stable and accessible
+- **Firewall settings**: Ensure Aurora is allowed through your firewall
+- **Proxy configuration**: If behind a corporate proxy, configure proxy settings in Aurora's config file
+
+#### DNS Resolution
+- **Verify domain resolution**: Test connectivity to API endpoints using `ping` or `nslookup`
+- **DNS cache**: Clear system DNS cache if experiencing intermittent issues
+- **Alternative DNS**: Try switching to public DNS servers (e.g., 8.8.8.8)
+
+#### SSL/TLS Errors
+- **Certificate validation**: Update system certificates or use `--insecure` flag for testing only
+- **Protocol version**: Ensure TLS 1.2+ is supported on your system
+- **Corporate SSL inspection**: Request certificate authority (CA) certificate from IT if applicable
+
+#### Timeout Issues
+- **Increase timeout values**: Use `--timeout=60` flag to extend wait time
+- **Check service status**: Verify third-party service availability at their status pages
+- **Reduce payload size**: Break large requests into smaller batches
+
+#### Debug Mode
+Enable verbose logging to diagnose connection problems:
+- Add explicit context to prompts.
+- Enable strict retrieval with: `--retrieval=strict`.
+
+### 3. Authentication Errors
+| Code | Meaning | Fix |
+|------|---------|------|
+| 401 | Invalid token | Re-enter API key |
+| 403 | Permission denied | Check role settings |
+| 429 | Rate limit exceeded | Reduce request size or upgrade plan |
+
+### 4. Integration Sync Failures
+**Fixes:**
+- Validate GitHub/Jira tokens.
+- Re-auth via: `aurora integrate github --reset`.
+- Clear cache: `aurora cache purge`.
+
+### 5. Advanced Connection Diagnostics
+
+#### Network Layer Analysis
+**TCP/IP Stack Verification:**
+- Run `netstat -an | grep ESTABLISHED` to check active connections
+- Monitor packet loss: `ping -c 100 api.aurora.ai` and analyze statistics
+- Use `traceroute api.aurora.ai` to identify routing bottlenecks
+- Check MTU settings: `ping -M do -s 1472 api.aurora.ai` to test fragmentation
+
+**Port Availability:**
+- Verify required ports are open: 443 (HTTPS), 80 (HTTP fallback)
+- Test with `telnet api.aurora.ai 443` or `nc -zv api.aurora.ai 443`
+- Check for port conflicts: `lsof -i :443` (Linux/macOS) or `netstat -ano | findstr :443` (Windows)
+
+#### Protocol-Level Debugging
+**HTTP/HTTPS Traffic Inspection:**
+- Capture traffic with `tcpdump -i any -w aurora.pcap host api.aurora.ai`
+- Analyze with Wireshark to inspect TLS handshakes and HTTP headers
+- Use `curl -vvv https://api.aurora.ai/health` for detailed handshake output
+- Enable request/response logging: `export AURORA_DEBUG_HTTP=1`
+
+**TLS Handshake Failures:**
+- Check cipher suite compatibility: `openssl s_client -connect api.aurora.ai:443 -tls1_2`
+- Verify certificate chain: `openssl s_client -showcerts -connect api.aurora.ai:443`
+- Test SNI (Server Name Indication): `openssl s_client -servername api.aurora.ai -connect api.aurora.ai:443`
+- Inspect client certificate requirements if mutual TLS is enabled
+
+#### DNS Deep Dive
+**Resolution Path Analysis:**
+- Query authoritative nameservers: `dig @8.8.8.8 api.aurora.ai +trace`
+- Check DNS response times: `dig api.aurora.ai | grep "Query time"`
+- Verify DNSSEC validation: `dig api.aurora.ai +dnssec`
+- Test DNS-over-HTTPS: Configure DoH provider in system settings
+
+**DNS Cache Management:**
+- Linux: `sudo systemd-resolve --flush-caches` or `sudo service nscd restart`
+- macOS: `sudo dscacheutil -flushcache; sudo killall -HUP mDNSResponder`
+- Windows: `ipconfig /flushdns`
+- Verify `/etc/hosts` (Unix) or `C:\Windows\System32\drivers\etc\hosts` (Windows) for override entries
+
+#### Proxy and VPN Troubleshooting
+**Proxy Configuration Validation:**
+- Check environment variables: `echo $HTTP_PROXY $HTTPS_PROXY $NO_PROXY`
+- Test proxy authentication: `curl -x http://proxy.corp.com:8080 --proxy-user user:pass https://api.aurora.ai`
+- Configure in Aurora config: `aurora config set proxy.url http://proxy.corp.com:8080`
+- Bypass proxy for testing: `export NO_PROXY=api.aurora.ai`
+
+**VPN-Specific Issues:**
+- Check split-tunneling configuration
+- Verify VPN MTU: `ip link show` and adjust if < 1500
+- Test with VPN disabled to isolate issue
+- Check for IPv6 leakage: `curl -6 https://api.aurora.ai` vs `curl -4 https://api.aurora.ai`
+
+#### Application-Level Diagnostics
+**Aurora Internal Logs:**
+- Enable maximum verbosity: `aurora --log-level=trace <command>`
+- Tail log file in real-time: `tail -f ~/.aurora/logs/aurora.log`
+- Filter connection events: `grep -i "connection\|socket\|timeout" ~/.aurora/logs/aurora.log`
+- Structured JSON logging: `aurora --log-format=json <command> | jq '.level="error"'`
+
+**Request/Response Inspection:**
+- Capture full HTTP exchange: `AURORA_DUMP_REQUESTS=1 aurora <command>`
+- Measure round-trip time: `time aurora api healthcheck`
+- Test with minimal request: `aurora api raw --method GET --endpoint /v1/health`
+- Verify request headers: Check `User-Agent`, `Authorization`, `Content-Type` in debug output
+
+#### System Resource Constraints
+**Connection Pool Exhaustion:**
+- Check open file descriptors: `ulimit -n` and increase if needed
+- Monitor active sockets: `lsof -p $(pgrep aurora) | grep TCP`
+- Review connection pool settings: `aurora config get http.max_connections`
+- Adjust keep-alive timeout: `aurora config set http.keepalive_timeout 30`
+
+**Memory and CPU Impact:**
+- Profile resource usage: `top -p $(pgrep aurora)` or `htop`
+- Check for memory leaks during long-running operations
+- Monitor thread count: `ps -eLf | grep aurora | wc -l`
+- Enable profiling: `aurora --profile=cpu <command>`
+
+#### Enterprise Environment Considerations
+**Corporate Security Appliances:**
+- SSL/TLS Inspection: Export CA certificate and install system-wide
+- Web Application Firewalls: Whitelist Aurora user-agent string
+- DLP (Data Loss Prevention): Configure exceptions for Aurora traffic
+- CASB (Cloud Access Security Broker): Add Aurora domains to allowlist
+
+**Authentication Mechanisms:**
+- NTLM proxy authentication: `aurora config set proxy.auth ntlm`
+- Kerberos/SPNEGO: Ensure valid ticket with `klist`
+- Client certificates: Specify with `--client-cert=/path/to/cert.pem --client-key=/path/to/key.pem`
+- OAuth token refresh: `aurora auth token --refresh`
+
+#### Advanced Debugging Techniques
+**Packet Capture and Analysis:**
+```bash
+# Capture on specific interface
+sudo tcpdump -i eth0 -s 0 -w aurora_debug.pcap 'host api.aurora.ai'
+
+# Filter by port and decode HTTP
+sudo tcpdump -i any -A 'tcp port 443 and host api.aurora.ai'
+
+# Real-time monitoring with timestamps
+sudo tcpdump -i any -tttt 'host api.aurora.ai'
+```
+
+**SystemTap/eBPF Tracing (Linux):**
+- Trace system calls: `strace -f -e trace=network aurora <command>`
+- Monitor DNS queries: `sudo tcpdump -i any port 53`
+- Track connection states: Use `ss -tan state established`
+
+**Performance Profiling:**
+- Generate flame graph: `aurora --profile=cpu --profile-output=profile.pb.gz <command>`
+- Analyze with pprof: `go tool pprof -http=:8080 profile.pb.gz`
+- Network timing breakdown: Use browser DevTools Network tab for web UI
+
+#### Configuration File Troubleshooting
+**Verify Configuration Syntax:**
+```bash
+# Validate config file
+aurora config validate
+
+# Show effective configuration
+aurora config show --resolved
+
+# Reset to defaults
+aurora config reset --confirm
+
+# Override specific setting
+aurora --config=/tmp/test.yaml <command>
+```
+
+**Common Configuration Issues:**
+- Incorrect endpoint URLs: Verify `api.base_url` setting
+- Timeout values too low: Increase `http.timeout` and `http.read_timeout`
+- Retry logic disabled: Enable with `http.retry.enabled=true`
+- Connection limits: Adjust `http.max_connections_per_host`
+
+#### External Service Integration Testing
+**GitHub Connectivity:**
+```bash
+# Test GitHub API access
+curl -H "Authorization: token YOUR_TOKEN" https://api.github.com/user
+
+# Verify webhook endpoint
+curl -X POST https://api.aurora.ai/webhooks/github/test
+
+# Check SSH access
+ssh -T [email protected]
+```
+
+**Jira Connectivity:**
+```bash
+# Test Jira REST API
+curl -u [email protected]:api_token https://your-domain.atlassian.net/rest/api/3/myself
+
+# Verify webhook delivery
+aurora integrate jira test-webhook --project KEY
+```
+
+#### Logging and Monitoring
+**Continuous Monitoring Setup:**
+- Configure log aggregation: Ship logs to ELK, Splunk, or Datadog
+- Set up alerts for connection failures
+- Monitor error rates: `grep -c "connection refused\|timeout" aurora.log`
+- Track success rates over time
+
+**Metrics Collection:**
+- Enable Prometheus metrics: `aurora serve --metrics-port=9090`
+- Export connection statistics: `aurora metrics export --format=json`
+- Dashboard visualization: Import Aurora Grafana dashboard
+
+#### Emergency Workarounds
+**Temporary Fixes:**
+- Use alternative endpoint: `aurora --api-url=https://backup.aurora.ai`
+- Offline mode (if supported): `aurora --offline <command>`
+- Fallback to local processing: `aurora --no-remote <command>`
+- Manual API calls: Use `curl` with stored authentication token
+
+**Escalation Path:**
+1. Collect diagnostic bundle: `aurora diagnostic collect --output=aurora-diag.zip`
+2. Include system information: `aurora version --verbose`
+3. Attach relevant logs and packet captures
+4. Submit to support with issue details

document_intelligence.py

@@ -0,0 +1,403 @@
+"""
+Document Intelligence Module for Advanced Text Analysis and Processing
+"""
+from pathlib import Path
+from typing import List, Dict, Any
+import re
+import math
+from collections import Counter
+
+
+class DocumentIntelligence:
+    """Advanced document intelligence for smart analysis and summarization."""
+    
+    def __init__(self, docs_root: Path):
+        self.docs_root = docs_root
+        
+    def generate_smart_summary(self, content: str, summary_type: str = "medium") -> str:
+        """Generate an intelligent summary based on content analysis."""
+        # Handle PDF page markers
+        content = self._clean_pdf_content(content)
+        
+        sentences = self._split_into_sentences(content)
+        
+        if not sentences:
+            return "No content available for summarization."
+        
+        # Score sentences based on multiple factors
+        sentence_scores = {}
+        
+        # Factor 1: Word frequency
+        words = self._extract_words(content)
+        word_freq = Counter(words)
+        
+        # Factor 2: Position (early sentences often important)
+        # Factor 3: Length (moderate length sentences preferred)
+        # Factor 4: Keywords (technical terms, action words)
+        
+        for i, sentence in enumerate(sentences):
+            score = 0
+            sentence_words = self._extract_words(sentence)
+            
+            # Word frequency score
+            for word in sentence_words:
+                score += word_freq.get(word, 0)
+            
+            # Position score (first and last sentences get bonus)
+            if i < 3:
+                score += 5
+            elif i >= len(sentences) - 2:
+                score += 3
+                
+            # Length score (prefer moderate length)
+            word_count = len(sentence_words)
+            if 10 <= word_count <= 25:
+                score += 3
+            elif 5 <= word_count <= 35:
+                score += 1
+                
+            # Keyword bonus
+            keywords = ['important', 'key', 'main', 'primary', 'essential', 
+                       'note', 'must', 'should', 'required', 'configure', 
+                       'setup', 'install', 'create', 'build']
+            for keyword in keywords:
+                if keyword in sentence.lower():
+                    score += 2
+            
+            sentence_scores[i] = score / max(len(sentence_words), 1)
+        
+        # Select top sentences based on summary type
+        if summary_type == "short":
+            top_count = min(3, len(sentences))
+        elif summary_type == "long":
+            top_count = min(10, len(sentences))
+        else:  # medium
+            top_count = min(6, len(sentences))
+        
+        # Get top scoring sentences, maintaining order
+        top_sentence_indices = sorted(
+            sorted(sentence_scores.items(), key=lambda x: x[1], reverse=True)[:top_count],
+            key=lambda x: x[0]
+        )
+        
+        summary_sentences = [sentences[i] for i, _ in top_sentence_indices]
+        return ' '.join(summary_sentences)
+    
+    def extract_key_concepts(self, content: str, min_frequency: int = 2) -> List[Dict[str, Any]]:
+        """Extract key concepts and terms from content."""
+        # Clean PDF content for better concept extraction
+        content = self._clean_pdf_content(content)
+        
+        concepts = []
+        
+        # Extract technical terms (words in backticks)
+        tech_terms = re.findall(r'`([^`]+)`', content)
+        tech_term_freq = Counter(tech_terms)
+        
+        for term, freq in tech_term_freq.items():
+            if freq >= min_frequency:
+                concepts.append({
+                    'concept': term,
+                    'frequency': freq,
+                    'type': 'technical_term'
+                })
+        
+        # Extract important phrases (words in bold)
+        bold_terms = re.findall(r'\*\*([^*]+)\*\*', content)
+        bold_term_freq = Counter(bold_terms)
+        
+        for term, freq in bold_term_freq.items():
+            if freq >= min_frequency:
+                concepts.append({
+                    'concept': term,
+                    'frequency': freq,
+                    'type': 'emphasized_term'
+                })
+        
+        # Extract capitalized words (potential proper nouns/concepts)
+        words = re.findall(r'\b[A-Z][a-z]+\b', content)
+        cap_word_freq = Counter(words)
+        
+        for word, freq in cap_word_freq.items():
+            if freq >= min_frequency and len(word) > 3:
+                concepts.append({
+                    'concept': word,
+                    'frequency': freq,
+                    'type': 'proper_noun'
+                })
+        
+        # Sort by frequency and return top concepts
+        concepts.sort(key=lambda x: x['frequency'], reverse=True)
+        return concepts[:20]
+    
+    def analyze_readability(self, content: str) -> Dict[str, Any]:
+        """Analyze content readability using various metrics."""
+        # Clean PDF content for better analysis
+        content = self._clean_pdf_content(content)
+        
+        sentences = self._split_into_sentences(content)
+        words = self._extract_words(content)
+        
+        if not sentences or not words:
+            return {"flesch_score": 0, "grade_level": 0, "complexity": "unknown"}
+        
+        # Basic counts
+        sentence_count = len(sentences)
+        word_count = len(words)
+        syllable_count = sum(self._count_syllables(word) for word in words)
+        
+        # Average sentence length
+        avg_sentence_length = word_count / sentence_count
+        
+        # Average syllables per word
+        avg_syllables = syllable_count / word_count if word_count > 0 else 0
+        
+        # Flesch Reading Ease Score
+        flesch_score = 206.835 - (1.015 * avg_sentence_length) - (84.6 * avg_syllables)
+        flesch_score = max(0, min(100, flesch_score))  # Clamp to 0-100
+        
+        # Grade level estimation
+        grade_level = 0.39 * avg_sentence_length + 11.8 * avg_syllables - 15.59
+        grade_level = max(1, grade_level)
+        
+        # Complexity assessment
+        if flesch_score >= 70:
+            complexity = "easy"
+        elif flesch_score >= 50:
+            complexity = "moderate"
+        elif flesch_score >= 30:
+            complexity = "difficult"
+        else:
+            complexity = "very difficult"
+        
+        return {
+            "flesch_score": round(flesch_score, 1),
+            "grade_level": round(grade_level, 1),
+            "complexity": complexity,
+            "avg_sentence_length": round(avg_sentence_length, 1),
+            "avg_syllables_per_word": round(avg_syllables, 2),
+            "total_sentences": sentence_count,
+            "total_words": word_count
+        }
+    
+    def extract_questions_and_answers(self, content: str) -> List[Dict[str, str]]:
+        """Extract Q&A pairs from content."""
+        qa_pairs = []
+        
+        # Look for FAQ sections
+        sections = self._extract_sections(content)
+        for section in sections:
+            if any(keyword in section['title'].lower() for keyword in ['faq', 'question', 'q&a', 'troubleshoot']):
+                pairs = self._extract_qa_from_section(section['content'])
+                qa_pairs.extend(pairs)
+        
+        # Look for question patterns throughout the text
+        question_patterns = [
+            r'(?:Q:|Question:|Q\d+:)\s*([^?]+\?)\s*(?:A:|Answer:)?\s*([^Q\n]+)',
+            r'(?:^|\n)([^.!?\n]*\?)\s*\n([^?\n]+)',
+            r'How (?:do|to|can) ([^?]+\?)\s*([^?\n]+)'
+        ]
+        
+        for pattern in question_patterns:
+            matches = re.findall(pattern, content, re.MULTILINE | re.IGNORECASE)
+            for match in matches:
+                if len(match) == 2:
+                    question, answer = match
+                    qa_pairs.append({
+                        "question": question.strip(),
+                        "answer": answer.strip()[:300],  # Limit answer length
+                        "type": "extracted"
+                    })
+        
+        return qa_pairs[:15]  # Return top 15 Q&A pairs
+    
+    def find_related_content(self, query: str, doc_paths: List[Path], max_results: int = 5) -> List[Dict[str, Any]]:
+        """Find documents related to a query using TF-IDF-like scoring."""
+        query_words = set(self._extract_words(query.lower()))
+        results = []
+        
+        for path in doc_paths:
+            try:
+                content = path.read_text(encoding='utf-8', errors='ignore')
+                content_words = self._extract_words(content.lower())
+                
+                if not content_words:
+                    continue
+                
+                # Calculate similarity score
+                word_freq = Counter(content_words)
+                score = 0
+                
+                for query_word in query_words:
+                    if query_word in word_freq:
+                        # TF-IDF like scoring
+                        tf = word_freq[query_word] / len(content_words)
+                        score += tf * len(query_word)  # Longer words get more weight
+                
+                if score > 0:
+                    # Normalize by document length
+                    normalized_score = score / math.log(len(content_words) + 1)
+                    
+                    # Get context snippet
+                    snippet = self._extract_snippet(content, query_words)
+                    
+                    results.append({
+                        'path': str(path.relative_to(self.docs_root)),
+                        'relevance_score': normalized_score,
+                        'snippet': snippet,
+                        'word_count': len(content_words)
+                    })
+                    
+            except Exception:
+                continue
+        
+        # Sort by relevance and return top results
+        results.sort(key=lambda x: x['relevance_score'], reverse=True)
+        return results[:max_results]
+    
+    def _split_into_sentences(self, content: str) -> List[str]:
+        """Split content into sentences."""
+        # Simple sentence splitting
+        sentences = re.split(r'[.!?]+', content)
+        return [s.strip() for s in sentences if s.strip() and len(s.strip()) > 10]
+    
+    def _extract_words(self, text: str) -> List[str]:
+        """Extract words from text."""
+        words = re.findall(r'\b[a-zA-Z]+\b', text.lower())
+        # Filter out common stop words
+        stop_words = {'the', 'a', 'an', 'and', 'or', 'but', 'in', 'on', 'at', 'to', 'for', 'of', 'with', 'by', 'is', 'are', 'was', 'were', 'be', 'been', 'have', 'has', 'had', 'do', 'does', 'did', 'will', 'would', 'could', 'should', 'may', 'might', 'can', 'this', 'that', 'these', 'those', 'it', 'its', 'they', 'them', 'their'}
+        return [word for word in words if word not in stop_words and len(word) > 2]
+    
+    def _count_syllables(self, word: str) -> int:
+        """Estimate syllable count for a word."""
+        word = word.lower()
+        if len(word) <= 3:
+            return 1
+        
+        vowels = 'aeiouy'
+        syllable_count = 0
+        prev_was_vowel = False
+        
+        for char in word:
+            if char in vowels:
+                if not prev_was_vowel:
+                    syllable_count += 1
+                prev_was_vowel = True
+            else:
+                prev_was_vowel = False
+        
+        # Handle silent e
+        if word.endswith('e') and syllable_count > 1:
+            syllable_count -= 1
+        
+        return max(1, syllable_count)
+    
+    def _extract_sections(self, content: str) -> List[Dict[str, str]]:
+        """Extract sections from markdown content."""
+        sections = []
+        lines = content.split('\n')
+        current_section = None
+        current_content = []
+        
+        for line in lines:
+            if line.strip().startswith('#'):
+                if current_section:
+                    sections.append({
+                        'title': current_section,
+                        'content': '\n'.join(current_content).strip()
+                    })
+                current_section = line.strip()
+                current_content = []
+            else:
+                current_content.append(line)
+        
+        if current_section:
+            sections.append({
+                'title': current_section,
+                'content': '\n'.join(current_content).strip()
+            })
+        
+        return sections
+    
+    def _extract_qa_from_section(self, section_content: str) -> List[Dict[str, str]]:
+        """Extract Q&A pairs from a section."""
+        qa_pairs = []
+        lines = section_content.split('\n')
+        current_question = None
+        current_answer = []
+        
+        for line in lines:
+            line = line.strip()
+            if line.endswith('?') and not current_question:
+                current_question = line
+            elif current_question and line and not line.endswith('?'):
+                current_answer.append(line)
+            elif current_question and (line.endswith('?') or not line):
+                if current_answer:
+                    qa_pairs.append({
+                        "question": current_question,
+                        "answer": ' '.join(current_answer),
+                        "type": "faq"
+                    })
+                current_question = line if line.endswith('?') else None
+                current_answer = []
+        
+        # Don't forget the last Q&A pair
+        if current_question and current_answer:
+            qa_pairs.append({
+                "question": current_question,
+                "answer": ' '.join(current_answer),
+                "type": "faq"
+            })
+        
+        return qa_pairs
+    
+    def _extract_snippet(self, content: str, query_words: set, snippet_length: int = 150) -> str:
+        """Extract a relevant snippet containing query words."""
+        content_lower = content.lower()
+        
+        # Find the first occurrence of any query word
+        first_pos = len(content)
+        for word in query_words:
+            pos = content_lower.find(word)
+            if pos != -1:
+                first_pos = min(first_pos, pos)
+        
+        if first_pos == len(content):
+            # No query words found, return beginning
+            return content[:snippet_length] + "..." if len(content) > snippet_length else content
+        
+        # Extract snippet around the found position
+        start = max(0, first_pos - snippet_length // 2)
+        end = min(len(content), start + snippet_length)
+        snippet = content[start:end]
+        
+        if start > 0:
+            snippet = "..." + snippet
+        if end < len(content):
+            snippet = snippet + "..."
+        
+        return snippet.replace('\n', ' ')
+    
+    def _clean_pdf_content(self, content: str) -> str:
+        """Clean PDF content by removing page markers and fixing formatting."""
+        import re
+        
+        # Remove page markers like "--- Page 1 ---"
+        content = re.sub(r'\n--- Page \d+ ---\n', '\n\n', content)
+        content = re.sub(r'\n--- Page \d+ \(Error reading:.*?\) ---\n', '\n\n', content)
+        
+        # Fix common PDF extraction issues
+        # Remove excessive whitespace
+        content = re.sub(r'\n\s*\n\s*\n+', '\n\n', content)
+        
+        # Fix broken words (common in PDF extraction)
+        content = re.sub(r'(\w)-\s*\n\s*(\w)', r'\1\2', content)
+        
+        # Fix spacing issues
+        content = re.sub(r'([a-z])([A-Z])', r'\1 \2', content)
+        
+        # Remove extra spaces
+        content = re.sub(r' +', ' ', content)
+        
+        return content.strip()

guides/FIXES_APPLIED.md

@@ -0,0 +1,89 @@
+# Document Summarization Issues - Fixed
+
+## Problem Summary
+The docs-navigator agent was having issues with document summarization and content extraction. When users asked questions about content indirectly mentioned in documents, the agent would show error messages like:
+
+- "Hmm, it looks like there was an issue summarizing that document"
+- "still having issues with the summarization" 
+- "Oops, looks like I don't have a tool to directly extract a specific section"
+
+## Root Cause Analysis
+
+The issues were in the `server_docs.py` file, specifically in these functions:
+
+1. **`_generate_overview_summary`**: Was only taking the first 3 sections and limiting to 30 words each, causing truncated/incomplete summaries
+2. **`_extract_key_points`**: Was not properly processing bullet points from sections
+3. **`_generate_detailed_summary`**: Was limiting content to 200 characters per section
+4. **Missing functionality**: No way to extract specific sections by name
+
+## Fixes Implemented
+
+### 1. Improved Overview Summary Generation
+```python
+def _generate_overview_summary(content: str, sections: List[Dict[str, str]]) -> str:
+    """Generate a concise overview summary."""
+    # Now processes ALL meaningful sections (skip empty ones)
+    # Increased word limit to 50 words per section
+    # Added fallback handling for edge cases
+    # Limits to 5 sections to avoid excessive text
+```
+
+### 2. Enhanced Key Points Extraction
+```python
+def _extract_key_points(content: str, sections: List[Dict[str, str]]) -> str:
+    """Extract key points from content."""
+    # Now processes bullet points from ALL sections
+    # Better bullet point cleaning and formatting
+    # Enhanced fallback with more keywords
+    # Increased limit to 15 points
+```
+
+### 3. Improved Detailed Summary
+```python
+def _generate_detailed_summary(content: str, sections: List[Dict[str, str]]) -> str:
+    """Generate a detailed summary with all sections."""
+    # Increased content limit to 400 characters per section
+    # Skip empty sections properly
+    # Better fallback handling
+```
+
+### 4. New Section Extraction Tool
+Added a new MCP tool `extract_section` that allows:
+- Case-insensitive partial matching of section titles
+- Direct extraction of specific document sections
+- Helpful error messages with available sections listed
+- Support for multiple matching sections
+
+### 5. Enhanced Error Handling
+- Added try-catch blocks in `intelligent_summarize`
+- Improved error messages with fallback options
+- Better handling of edge cases in document intelligence module
+
+## Testing Results
+
+The fixes have been tested with various scenarios:
+
+✅ **Anti-patterns extraction**: Now correctly extracts and lists the 3 anti-patterns from prompting-guidelines.md
+✅ **Best practices analysis**: Properly summarizes the 4 best practices with full content
+✅ **Section-specific queries**: Can extract specific sections like "Anti-Patterns to Avoid"
+✅ **Complex analysis**: Handles multi-document searches and analysis requests
+✅ **Error recovery**: Graceful handling when sections are empty or missing
+
+## Key Improvements
+
+1. **Complete Content**: No more truncated summaries - users get full information
+2. **Better Structure**: Proper section detection and processing
+3. **Flexible Extraction**: New tool for extracting specific sections by name
+4. **Robust Error Handling**: Fallback mechanisms prevent tool failures
+5. **Enhanced Readability**: Better formatting and organization of extracted content
+
+## Impact
+
+Users can now ask complex questions about documentation content and receive complete, accurate responses instead of error messages. The agent can:
+
+- Extract specific sections by name (e.g., "What are the anti-patterns?")
+- Provide comprehensive summaries without truncation
+- Handle edge cases gracefully
+- Offer helpful suggestions when content isn't found
+
+The fixes maintain backward compatibility while significantly improving the reliability and usefulness of the documentation analysis tools.

guides/GETTING_STARTED.md

@@ -0,0 +1,355 @@
+# Getting Started with Docs Navigator MCP
+
+Welcome! This guide will walk you through setting up and using the Docs Navigator MCP system step by step. By the end, you'll have a working AI assistant that can answer questions about your documentation.
+
+## 📋 Prerequisites
+
+Before you begin, make sure you have:
+
+- **Python 3.10+** installed on your system
+- **An Anthropic API key** (sign up at [console.anthropic.com](https://console.anthropic.com))
+- **Command line access** (Terminal on macOS/Linux, Command Prompt on Windows)
+- **UV package manager** (recommended) or pip
+
+### Installing UV (Recommended)
+
+UV provides faster dependency management than pip:
+
+**macOS/Linux:**
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+**Windows:**
+```powershell
+powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
+```
+
+## 🛠️ Step-by-Step Setup
+
+### Step 1: Get the Code
+
+Clone or download this repository:
+
+```bash
+git clone <your-repo-url>
+cd docs-navigator
+```
+
+### Step 2: Set Up Python Environment
+
+**Using UV (recommended):**
+```bash
+uv sync
+```
+
+**Using pip:**
+```bash
+# Create virtual environment
+python -m venv .venv
+
+# Activate it
+# On Windows:
+.venv\Scripts\activate
+# On macOS/Linux:
+source .venv/bin/activate
+
+# Install dependencies
+pip install -r requirements.txt
+```
+
+### Step 3: Configure Your API Key
+
+Create a `.env` file in the project root:
+
+```bash
+# Create the file
+touch .env  # On macOS/Linux
+# Or just create the file manually on Windows
+```
+
+Add your Anthropic API key to the `.env` file:
+
+```
+ANTHROPIC_API_KEY= your-actual-api-key-here
+```
+
+**Important**: Never commit your `.env` file to version control!
+
+### Step 4: Verify Your API Key
+
+Test that your API key works:
+
+```bash
+# Using UV
+uv run test_anthropic.py
+
+# Using Python directly
+python test_anthropic.py
+```
+
+You should see output like:
+```
+Testing model: claude-3-haiku-20240307
+✅ claude-3-haiku-20240307: API working
+Done testing models.
+```
+
+### Step 5: Add Your Documentation
+
+Place your documentation files in the `docs/` folder. The system supports:
+
+- **Markdown files** (`.md`)
+- **Text files** (`.txt`) 
+- **reStructuredText files** (`.rst`)
+
+Example structure:
+```
+docs/
+├── getting-started.md
+├── api-reference.md
+├── troubleshooting.txt
+├── faq.md
+└── installation.rst
+```
+
+**Sample content to try**: The project already includes sample docs you can test with:
+- `overview.md`
+- `setup.md`
+- `troubleshooting.md`
+- `prompting-guidelines.md`
+- `auroraai_report.txt`
+
+### Step 6: Test the MCP Server
+
+Verify that the MCP server can read your docs:
+
+```bash
+# Using UV
+uv run test_mcp.py
+
+# Using Python directly
+python test_mcp.py
+```
+
+Expected output:
+```
+Connecting to MCP server...
+Listing available docs...
+Available tools: ['list_docs', 'search_docs']
+Available docs: [overview.md, setup.md, ...]
+Search results for 'setup': [{"path": "setup.md", "snippet": "..."}]
+✅ MCP connection and tools working correctly!
+```
+
+### Step 7: Test End-to-End Functionality
+
+Run a complete test:
+
+```bash
+# Using UV
+uv run test_complete.py
+
+# Using Python directly
+python test_complete.py
+```
+
+This will ask the AI a question about your docs and show you the response.
+
+### Step 8: Launch the Web Interface
+
+Start the Gradio app:
+
+```bash
+# Using UV
+uv run app_gradio.py
+
+# Using Python directly
+python app_gradio.py
+```
+
+You'll see:
+```
+* Running on local URL:  http://127.0.0.1:7860
+* To create a public link, set `share=True` in `launch()`.
+```
+
+Open http://127.0.0.1:7860 in your browser.
+
+## 💬 Using the Chat Interface
+
+Once the web interface opens, you can:
+
+### Example Questions to Try:
+
+1. **Discovery**: "What documentation do you have available?"
+
+2. **Specific lookup**: "How do I set up authentication?"
+
+3. **Troubleshooting**: "What should I do if I get connection errors?"
+
+4. **Summarization**: "Give me an overview of the main features"
+
+5. **Search**: "Find information about API endpoints"
+
+### How It Works:
+
+1. **You ask a question** in the chat interface
+2. **The AI agent** receives your question
+3. **MCP tools search** through your documentation files
+4. **Claude AI analyzes** the search results
+5. **You get an answer** with references to source files
+
+## 🔍 Understanding the Components
+
+### Files You'll Work With:
+
+- **`app_gradio.py`**: The web interface (you probably won't need to modify this)
+- **`client_agent.py`**: Connects to Claude AI and MCP server  
+- **`server_docs.py`**: Provides document search tools to the AI
+- **`docs/`**: Your documentation files go here
+- **`.env`**: Your API key and other secrets
+
+### What Happens When You Ask a Question:
+
+```
+Your Question → Gradio → Client Agent → Claude AI
+                                         ↓
+                                    "I need to search docs"
+                                         ↓
+                                    MCP Server → docs/ folder
+                                         ↓
+                                    Search Results
+                                         ↓
+                               Claude AI (generates answer)
+                                         ↓
+                              Gradio → Your Answer
+```
+
+## ⚙️ Customization Options
+
+### Change the AI Model
+
+Edit `client_agent.py` and modify the model name:
+
+```python
+model="claude-3-haiku-20240307"  # Current model
+model="claude-3-5-sonnet-20241022"  # Higher quality (requires API access)
+```
+
+### Change the Port
+
+Edit `app_gradio.py`:
+
+```python
+demo.launch()  # Default port 7860
+demo.launch(server_port=8080)  # Custom port
+```
+
+### Add More File Types
+
+Edit `server_docs.py`:
+
+```python
+exts = {".md", ".txt", ".rst"}  # Current formats
+exts = {".md", ".txt", ".rst", ".pdf", ".docx"}  # Add more (requires additional code)
+```
+
+## 🐛 Troubleshooting Common Issues
+
+### "Model not found" Error
+
+**Problem**: Your API key doesn't have access to the specified Claude model.
+
+**Solution**: The system will automatically test and find a working model. If this fails, check that your API key is valid.
+
+### "No such file or directory" Error
+
+**Problem**: Python path or virtual environment issues.
+
+**Solution**: 
+```bash
+# Make sure you're in the right directory
+pwd  # Should show /path/to/docs-navigator
+
+# Make sure virtual environment is activated
+which python  # Should show .venv path
+```
+
+### No Documents Found
+
+**Problem**: The system can't find your documentation files.
+
+**Solution**: 
+- Check that files are in the `docs/` folder
+- Verify file extensions (`.md`, `.txt`, `.rst`)
+- Check file permissions
+
+### Port Already in Use
+
+**Problem**: Port 7860 is already taken.
+
+**Solution**: 
+- Stop other applications using the port
+- Or change the port in `app_gradio.py`
+
+### Connection Refused
+
+**Problem**: MCP server can't start.
+
+**Solution**:
+- Check that `server_docs.py` is executable
+- Verify all dependencies are installed
+- Check for Python syntax errors
+
+## 📈 Next Steps
+
+Once you have the basic system working:
+
+1. **Add more documentation**: Populate the `docs/` folder with your content
+
+2. **Customize prompts**: Modify the system prompts in `client_agent.py` to better suit your use case
+
+3. **Improve search**: Enhance the search functionality in `server_docs.py`
+
+4. **Add more tools**: Create additional MCP tools for specific documentation tasks
+
+5. **Deploy**: Set up the system on a server for team access
+
+## 💡 Tips for Better Results
+
+### Organizing Your Docs:
+
+- Use clear, descriptive filenames
+- Include section headings in markdown
+- Keep related information in the same file
+- Use consistent terminology
+
+### Writing Good Questions:
+
+- Be specific about what you need
+- Reference topics from your documentation
+- Ask for examples when appropriate
+- Request sources for verification
+
+### Optimizing Performance:
+
+- Keep individual doc files reasonably sized
+- Use markdown headers for better structure
+- Remove irrelevant or outdated content
+- Test questions regularly to improve prompts
+
+## 🆘 Getting Help
+
+If you run into issues:
+
+1. **Check the test scripts**: Run `test_mcp.py` and `test_anthropic.py`
+2. **Review the logs**: Look for error messages in the terminal
+3. **Verify your setup**: Double-check API keys and file paths
+4. **Start fresh**: Create a new virtual environment if needed
+
+## 🎉 Success!
+
+You should now have a working documentation assistant! The AI can search through your docs and provide intelligent answers to your questions.
+
+Try asking: "What can you help me with?" to get started!

guides/INTELLIGENT_TOOLS_GUIDE.md

@@ -0,0 +1,236 @@
+# Intelligent Documentation Tools Guide
+
+## Overview
+
+Your docs-navigator project has been enhanced with powerful intelligent tools for document analysis, summarization, and knowledge extraction. These tools use advanced text processing algorithms to provide insights that go far beyond simple search and retrieval.
+
+## 🧠 New Intelligent Tools
+
+### 1. **Intelligent Summarization** (`intelligent_summarize`)
+Creates context-aware summaries using sentence scoring and key concept analysis.
+
+**Features:**
+- Multiple summary lengths (short, medium, long)
+- Key concept extraction
+- Readability analysis
+- Focus keyword highlighting
+
+**Example Usage:**
+```python
+# Through the chat interface:
+"Create a medium-length summary of the setup guide with focus on configuration"
+
+# Direct tool call:
+{
+    "relative_path": "setup.md",
+    "summary_type": "medium", 
+    "focus_keywords": "configuration, installation"
+}
+```
+
+### 2. **Document Structure Analysis** (`analyze_document_structure`)
+Provides comprehensive structural analysis of documents.
+
+**Features:**
+- Header hierarchy and outline generation
+- Content statistics (words, lines, sections)
+- Code block and link detection
+- Table and image identification
+
+### 3. **Q&A Extraction** (`extract_qa_pairs`)
+Automatically extracts question-answer pairs for FAQ generation.
+
+**Features:**
+- Pattern-based question detection
+- Context-aware answer extraction
+- Support for multiple Q&A formats
+- Bulk extraction from all documents
+
+### 4. **Semantic Document Search** (`semantic_search`)
+Advanced search using relevance scoring and context analysis.
+
+**Features:**
+- Keyword relevance scoring
+- Context snippet extraction
+- Document ranking by similarity
+- Word frequency analysis
+
+### 5. **Document Comparison** (`compare_documents`)
+Side-by-side analysis of document similarities and differences.
+
+**Features:**
+- Statistical comparison
+- Word overlap analysis
+- Structure comparison
+- Unique content identification
+
+### 6. **Definition Extraction** (`extract_definitions`)
+Identifies and extracts definitions, terms, and explanations.
+
+**Features:**
+- Multiple definition pattern recognition
+- Glossary section detection
+- Technical term identification
+- Definition density analysis
+
+### 7. **Table of Contents Generation** (`generate_table_of_contents`)
+Creates hierarchical TOCs for documents or entire documentation sets.
+
+**Features:**
+- Header-based outline generation
+- Multi-level hierarchy support
+- Cross-document TOC creation
+- Depth analysis
+
+### 8. **Related Document Discovery** (`find_related_documents`)
+Finds documents related to queries using TF-IDF-like scoring.
+
+**Features:**
+- Advanced similarity algorithms
+- Relevance scoring
+- Context snippet extraction
+- Cross-reference suggestions
+
+### 9. **Documentation Gap Analysis** (`analyze_document_gaps`)
+Identifies missing content and improvement opportunities.
+
+**Features:**
+- Content completeness analysis
+- Section coverage assessment
+- Readability evaluation
+- Improvement recommendations
+
+### 10. **Documentation Index Generation** (`generate_documentation_index`)
+Creates comprehensive searchable indexes of all content.
+
+**Features:**
+- Concept clustering
+- Cross-reference mapping
+- Topic categorization
+- Metadata extraction
+
+## 🚀 Advanced Features
+
+### Document Intelligence Engine
+The system includes a sophisticated `DocumentIntelligence` class that provides:
+
+- **Key Concept Extraction**: Identifies important terms and phrases
+- **Smart Summarization**: Uses sentence scoring for optimal summaries
+- **Readability Analysis**: Flesch reading ease scoring
+- **Question Detection**: Automatic Q&A pair extraction
+- **Content Similarity**: TF-IDF-based document comparison
+
+### Natural Language Processing
+Advanced text processing capabilities:
+
+- **Sentence Scoring**: Multi-factor sentence importance evaluation
+- **Phrase Extraction**: N-gram analysis for key phrases
+- **Syllable Counting**: For readability metrics
+- **Pattern Recognition**: Multiple definition and question patterns
+
+## 💡 Practical Use Cases
+
+### 1. **Documentation Quality Assurance**
+```
+"Analyze the quality and completeness of our documentation"
+"Which documents need improvement in readability?"
+"What sections are missing from our docs?"
+```
+
+### 2. **Content Discovery and Organization**
+```
+"Find all documents related to configuration and setup"
+"Generate a comprehensive table of contents"
+"Create an index of all concepts in the documentation"
+```
+
+### 3. **Automated FAQ Generation**
+```
+"Extract all questions and answers to create an FAQ"
+"What common questions are addressed in the docs?"
+```
+
+### 4. **Content Summarization**
+```
+"Create executive summaries of all technical documents"
+"Summarize the troubleshooting guide focusing on error handling"
+```
+
+### 5. **Documentation Maintenance**
+```
+"Compare the old and new versions of the setup guide"
+"Identify duplicate content across documents"
+"Find outdated or redundant information"
+```
+
+## 🔧 Integration Examples
+
+### Gradio Chat Interface
+The tools integrate seamlessly with your existing chat interface:
+
+```python
+# Users can ask natural language questions like:
+"What are the main topics covered in our documentation?"
+"Create a summary of all configuration-related content"
+"Find documents that need better organization"
+```
+
+### Direct API Usage
+For programmatic access:
+
+```python
+from client_agent import DocsNavigatorClient
+
+client = DocsNavigatorClient()
+await client.connect()
+
+# Intelligent analysis
+result = await client.session.call_tool("analyze_document_gaps", {})
+summary = await client.session.call_tool("intelligent_summarize", {
+    "relative_path": "overview.md",
+    "summary_type": "short"
+})
+```
+
+## 📈 Performance Benefits
+
+1. **Faster Content Discovery**: Semantic search finds relevant content quickly
+2. **Automated Insights**: Gap analysis identifies improvement areas automatically
+3. **Consistent Quality**: Readability analysis ensures content standards
+4. **User Experience**: Better organization and navigation
+5. **Maintenance Efficiency**: Automated detection of issues and duplicates
+
+## 🔮 Future Enhancement Ideas
+
+### Content Generation
+- **Auto-completion**: Suggest missing sections based on document type
+- **Template Generation**: Create document templates from existing patterns
+- **Content Recommendations**: Suggest related content to add
+
+### Advanced Analytics
+- **User Journey Mapping**: Track how users navigate documentation
+- **Content Performance**: Identify most/least accessed content
+- **Sentiment Analysis**: Analyze tone and user-friendliness
+
+### Integration Opportunities
+- **Version Control Integration**: Track documentation changes and improvements
+- **CI/CD Integration**: Automated quality checks in deployment pipeline
+- **Knowledge Base Sync**: Integration with external knowledge systems
+
+## 🛠️ Customization Options
+
+The system is designed to be easily extensible:
+
+1. **Custom Patterns**: Add domain-specific definition patterns
+2. **Scoring Algorithms**: Modify relevance scoring for your content type
+3. **Analysis Metrics**: Add custom quality metrics
+4. **Content Types**: Extend support for additional file formats
+
+## 📚 Getting Started
+
+1. **Test the tools**: Run `demo_intelligent_features.py` to see examples
+2. **Try the chat interface**: Ask natural language questions about your docs
+3. **Explore specific tools**: Use `test_intelligent_tools.py` for detailed testing
+4. **Customize for your needs**: Modify patterns and scoring in `document_intelligence.py`
+
+Your documentation system is now equipped with AI-powered intelligence that can understand, analyze, and improve your content automatically!

guides/UI_ENHANCEMENT_GUIDE.md

@@ -0,0 +1,227 @@
+# 🎨 Gradio UI/UX Enhancement Guide
+
+This guide covers the various options available to improve the UI/UX of your Docs Navigator Gradio interface.
+
+## 🚀 Quick Start
+
+### Option 1: Use the Enhanced Default
+```bash
+python app_gradio.py
+```
+The main `app_gradio.py` has been upgraded with professional styling, better error handling, and modern design.
+
+### Option 2: Try Different Styles
+```bash
+python launch_ui.py enhanced     # Modern professional (default)
+python launch_ui.py minimal      # Clean, simple
+python launch_ui.py corporate    # Business/enterprise 
+python launch_ui.py dark         # Dark mode
+python launch_ui.py glassmorphism # Modern glass effect
+```
+
+### Option 3: Explore All Options
+```bash
+python gradio_ui_showcase.py modern
+python gradio_ui_showcase.py dark
+python gradio_ui_showcase.py minimal
+python gradio_ui_showcase.py corporate
+python gradio_ui_showcase.py glassmorphism
+```
+
+## 🎭 Available UI Styles
+
+### 1. **Enhanced Professional** (Default)
+- **File**: `app_gradio.py` 
+- **Features**: Modern design, custom CSS, professional theme, avatars, examples
+- **Best for**: General use, professional presentations
+
+### 2. **Modern Animated**
+- **File**: `gradio_ui_showcase.py modern`
+- **Features**: Gradient backgrounds, animations, glassmorphism effects
+- **Best for**: Impressive demos, modern aesthetics
+
+### 3. **Dark Mode Professional** 
+- **File**: `gradio_ui_showcase.py dark` or `launch_ui.py dark`
+- **Features**: Dark theme, reduced eye strain, professional appearance
+- **Best for**: Long usage sessions, developer-focused environments
+
+### 4. **Minimal Clean**
+- **File**: `launch_ui.py minimal`
+- **Features**: Distraction-free, simple, fast loading
+- **Best for**: Focus on content, minimal resource usage
+
+### 5. **Corporate Enterprise**
+- **File**: `launch_ui.py corporate`
+- **Features**: Business-appropriate styling, professional colors
+- **Best for**: Enterprise environments, formal presentations
+
+### 6. **Glassmorphism Modern**
+- **File**: `gradio_ui_showcase.py glassmorphism`
+- **Features**: Glass effects, modern transparency, cutting-edge design
+- **Best for**: Showcasing modern design trends
+
+## 🛠️ Customization Options
+
+### Theme Customization
+You can easily customize themes in `ui_config.py`:
+
+```python
+from ui_config import create_theme, create_custom_css
+
+# Create custom theme
+my_theme = create_theme("professional", "purple_theme")
+
+# Create custom CSS
+my_css = create_custom_css(
+    components=["container", "modern_input", "animated_buttons"],
+    color_scheme="green_theme"
+)
+```
+
+### Available Color Schemes
+- `blue_gradient`: Blue to purple gradient (default)
+- `corporate_blue`: Professional blue tones
+- `purple_theme`: Purple-focused palette
+- `green_theme`: Green nature-inspired colors
+
+### CSS Components
+You can mix and match these CSS components:
+- `container`: Basic container styling
+- `glass_effect`: Glassmorphism background effects
+- `modern_input`: Enhanced input field styling
+- `animated_buttons`: Button hover animations
+- `chat_bubbles`: Enhanced chat message styling
+
+## 🎯 Advanced Customization
+
+### 1. Custom Avatars
+Replace the avatar URLs in any interface:
+```python
+avatar_images=(
+    "path/to/user-avatar.png",      # User avatar
+    "path/to/bot-avatar.png"        # Bot avatar
+)
+```
+
+### 2. Custom Fonts
+Add Google Fonts or system fonts:
+```python
+theme = gr.themes.Soft(
+    font=[
+        gr.themes.GoogleFont("Your-Font-Name"),
+        "fallback-font",
+        "sans-serif"
+    ]
+)
+```
+
+### 3. Custom CSS
+Add your own CSS for complete control:
+```python
+custom_css = """
+.your-custom-class {
+    /* Your styles here */
+}
+"""
+
+demo = gr.ChatInterface(
+    css=custom_css,
+    # ... other options
+)
+```
+
+### 4. Layout Modifications
+Customize the chat interface components:
+```python
+gr.ChatInterface(
+    chatbot=gr.Chatbot(
+        height=600,                    # Adjust height
+        show_label=False,             # Hide labels
+        bubble_full_width=False,      # Bubble styling
+        show_share_button=False       # Hide share button
+    ),
+    textbox=gr.Textbox(
+        placeholder="Custom placeholder...",
+        container=False,              # Remove container
+        scale=7                       # Adjust width ratio
+    ),
+    submit_btn=gr.Button("Send 🚀", variant="primary"),
+    examples=["Custom", "Examples", "Here"]
+)
+```
+
+## 🎨 Design Best Practices
+
+### 1. **Color Psychology**
+- **Blue**: Trust, professionalism, reliability
+- **Purple**: Creativity, innovation, luxury  
+- **Green**: Growth, harmony, freshness
+- **Dark themes**: Reduced eye strain, modern feel
+
+### 2. **Typography**
+- Use system fonts for fast loading: `system-ui`, `sans-serif`
+- Google Fonts for custom branding: `Inter`, `Poppins`, `Roboto`
+- Maintain good contrast ratios for accessibility
+
+### 3. **Layout**
+- Keep max-width around 1000-1200px for readability
+- Use consistent spacing and border-radius
+- Ensure responsive design for mobile devices
+
+### 4. **Animations**
+- Use subtle transitions (0.2-0.3s)
+- Avoid excessive animations that distract
+- Add hover effects for interactive feedback
+
+## 🔧 Performance Considerations
+
+### Fast Loading Options
+- **Minimal theme**: Fastest loading, least CSS
+- **System fonts**: No external font loading
+- **Reduced animations**: Better performance on slower devices
+
+### Rich Experience Options  
+- **Custom CSS**: More personalization, slightly slower
+- **Google Fonts**: Better typography, requires internet
+- **Complex animations**: Better UX, more CPU usage
+
+## 📱 Mobile Responsiveness
+
+All themes include mobile-responsive design with:
+- Adjusted padding and margins for small screens
+- Scalable text and components
+- Touch-friendly button sizes
+- Optimized chat bubble sizing
+
+## 🚀 Deployment Tips
+
+### For Production
+1. Use the **Corporate** or **Enhanced** themes for professional environments
+2. Test on different screen sizes and devices
+3. Consider loading times for your users
+4. Enable error handling and user feedback
+
+### For Demos
+1. Use **Modern** or **Glassmorphism** for visual impact
+2. Include engaging examples and clear descriptions
+3. Consider public sharing options with `share=True`
+
+### For Development
+1. Use **Dark** theme for reduced eye strain
+2. Enable detailed error messages
+3. Use **Minimal** theme for faster iteration
+
+## 🔗 Quick Reference
+
+| Style | Command | Best For |
+|-------|---------|----------|
+| Enhanced | `python app_gradio.py` | General use |
+| Modern | `python gradio_ui_showcase.py modern` | Demos |
+| Dark | `python launch_ui.py dark` | Development |
+| Minimal | `python launch_ui.py minimal` | Focus |
+| Corporate | `python launch_ui.py corporate` | Business |
+| Glass | `python gradio_ui_showcase.py glassmorphism` | Showcase |
+
+---
+
+🎨 **Pro Tip**: Mix and match elements from different themes to create your perfect UI! Use `ui_config.py` as a starting point for custom configurations.

pyproject.toml

@@ -0,0 +1,18 @@
+[project]
+name = "docs-navigator-mcp"
+version = "0.1.0"
+description = "Docs Navigator MCP — FastMCP server + agent + Gradio UI"
+readme = "README.md"
+requires-python = ">=3.10"
+
+dependencies = [
+    "mcp[cli]>=0.1.0",
+    "anthropic>=0.36.0",
+    "python-dotenv>=1.0.1",
+    "gradio>=5.0.0",
+    "PyPDF2>=3.0.0",
+]
+
+[tool.uv]
+# optional, good defaults
+package = true

requirements.txt

@@ -0,0 +1,5 @@
+mcp[cli]>=0.1.0
+anthropic>=0.36.0
+python-dotenv>=1.0.1
+gradio>=5.0.0
+PyPDF2>=3.0.0