README.md

metadata

title: meeTARA - Empathetic AI Assistant
emoji: 💝
colorFrom: pink
colorTo: purple
sdk: docker
app_file: app.py
pinned: false
license: mit
startup_duration_timeout: 30m

💝 meeTARA - Empathetic AI Assistant for your Life

meeTARA is a revolutionary empathetic AI assistant that combines advanced language models with emotional intelligence to provide caring, domain-specific responses across 16+ specialized categories.

🌟 Features

• 🧠 Domain Expertise: Specialized knowledge across healthcare, business, education, creative, technology, and more
• 💝 Emotional Intelligence: Caring, empathetic responses that understand context and emotion
• ⚡ Local Processing: Powered by GGUF models running locally (no external API calls)
• 🔒 Privacy-First: All processing happens on-device
• 🎯 Smart Routing: Automatically selects the best model based on query complexity and domain
• 🤖 Agent Mode: Tool-use capabilities with web search and calculator (Simple Direct Agent)

🤖 Models

meeTARA uses optimized GGUF models from meeTARA-lab:

• 4B Instruct (Default): Fast, efficient responses for most queries
• 4B Thinking: Deep reasoning for complex problems
• 8B Universal: Fallback for uncategorized domains
• 1.7B Lightweight: Quick responses for simple queries

🔧 Agent Mode (Simple Direct Agent)

meeTARA supports Agent Mode - an intelligent tool-use system that enables your local models to use external tools dynamically. Our Simple Direct Agent approach is lightweight, fast, and perfectly tailored for GGUF models.

How meeTARA Agent Works

The Simple Direct Agent approach:

1. 🎯 Detection: Uses pattern matching (regex) to detect tool needs from user queries
2. ⚡ Execution: Tools execute FIRST (calculator/web search) before model involvement
3. 📝 Synthesis: Tool results are fed to the meeTARA model for structured response generation
4. 🎨 Formatting: Model automatically formats responses using built-in structured format (🎯, 📊, ⚡, 💡)

Agent Flow Diagram

flowchart TD
    Start([User Query]) --> AgentMode{Agent Mode<br/>Enabled?}
    
    AgentMode -->|No| DirectModel[Direct Model Generation]
    AgentMode -->|Yes| Detect[Agent Detection Layer<br/>Pattern Matching]
    
    Detect --> LoadConfig[Load Config from<br/>config/agent_config.json]
    LoadConfig --> CheckCalc{Calculator<br/>Needed?}
    LoadConfig --> CheckWeb{Web Search<br/>Needed?}
    
    CheckCalc -->|Yes| CalcTool[Calculator Tool<br/>calculator expression]
    CheckCalc -->|No| NoCalc[Skip Calculator]
    
    CheckWeb -->|Yes| WebTool[Web Search Tool<br/>DuckDuckGo Search]
    CheckWeb -->|No| NoWeb[Skip Web Search]
    
    CalcTool --> CalcResult[Tool Result:<br/>"25 * 48 = 1200"]
    WebTool --> WebResult[Tool Results:<br/>Latest search data]
    
    NoCalc --> BuildPrompt
    NoWeb --> BuildPrompt
    CalcResult --> BuildPrompt[Build Enhanced Prompt<br/>Query + Tool Results]
    WebResult --> BuildPrompt
    
    BuildPrompt --> Model[MeeTARACore.generate<br/>Enhanced Prompt]
    DirectModel --> Model
    
    Model --> GGUF[GGUF Model<br/>Qwen3/Qwen2.5/Phi3]
    GGUF --> Structured[Structured Response<br/>🎯 Answer<br/>📊 Details<br/>⚡ Steps<br/>💡 Note]
    
    Structured --> Response([Final Response])
    
    style Start fill:#e1f5ff
    style Detect fill:#fff4e6
    style CalcTool fill:#ffe6f2
    style WebTool fill:#ffe6f2
    style Model fill:#fff4e6
    style GGUF fill:#e6ffe6
    style Structured fill:#e6ffe6
    style Response fill:#d4edda

Available Tools

• 🔢 Calculator Tool: Accurate mathematical calculations using Python eval() (safe expression evaluation)
• 🌐 Web Search Tool: DuckDuckGo search for current information, trends, news, stock prices, etc.

Configuration-Driven Detection

Tool detection is fully configurable via config/agent_config.json:

{
  "web_search": {
    "keywords": ["current", "today", "latest", "trend", "stock market", ...],
    "search_patterns": [...],
    "max_results": 5
  },
  "calculator": {
    "keywords": ["calculate", "compute", "what is", ...],
    "math_patterns": [...]
  }
}

Benefits:

• ✅ Easy Updates: Add/modify keywords without code changes
• ✅ Version Controlled: Config changes tracked in git
• ✅ Maintainable: All detection logic in one place

Example Flow

User Query: "What's 25 * 48? Also search for latest AI trends in 2025"

1. Detection: Agent detects calculator needed (matches "25 * 48") and web_search needed (matches "latest" + "trends")
2. Tool Execution:
   • calculator("25 * 48") → Returns "25 * 48 = 1200"
   • web_search("latest AI trends in 2025") → Returns search results from DuckDuckGo
3. Enhanced Prompt: Agent builds prompt with query + tool results
4. Model Generation: meeTARA model receives enhanced prompt and generates structured response
5. Final Response:

   🎯 Answer: 25 × 48 = 1200. Based on recent search results...
   📊 Details: Latest AI trends in 2025 include...
   ⚡ Steps: [Calculation steps + key findings]
   💡 Note: [Additional insights]
   

Benefits

• ✅ Fast & Lightweight: No heavy orchestration framework - direct tool execution
• ✅ Optimized Performance: ~80% faster web searches, ~40% faster calculator queries (see Performance Docs)
• ✅ Configurable: All detection keywords/patterns in config file
• ✅ Accurate Math: Calculator ensures precise calculations (no hallucinated math)
• ✅ Current Information: Web search provides up-to-date data beyond training cutoff
• ✅ Structured Responses: Model automatically formats responses with emoji sections
• ✅ Fallback Graceful: If tools unavailable or not needed, sends directly to model

Search Providers (AI-Powered Search)

meeTARA Agent supports multiple search providers for web searches:

1. DuckDuckGo (Default - Free, No API Key Required)

• ✅ Free: No API key needed
• ✅ No Limits: Unlimited searches
• ✅ Private: Privacy-focused search
• Use Case: Default for all users, works out of the box

2. Google Custom Search API (Optional - Better Results)

• ✅ Free Tier: 100 queries/day (no credit card required)
• ✅ Better Results: More accurate, AI-enhanced search results
• ✅ Easy Setup: Requires API key (see setup below)
• Use Case: For better search quality when free tier is sufficient

Search Flow:

1. Agent detects web search needed (e.g., "current US stock trends")
2. Tries Google Custom Search API first (if API key configured)
3. Falls back to DuckDuckGo (free) if Google unavailable
4. Search results are fed to AI model for intelligent processing and structured response

Setup Google Custom Search API (Optional):

1. Get Google API Key (free):

   • Go to Google Cloud Console
   • Create a new project or select existing
   • Enable "Custom Search API"
   • Create credentials → API Key
   • (Optional) Restrict API key to "Custom Search API" for security

2. Create Custom Search Engine (free):

   • Go to Programmable Search Engine
   • Create a new search engine
   • Search the entire web (or specific sites)
   • Copy the Search Engine ID

3. Set Environment Variables:

   For Local Development (using .env file):

   # Create .env file in project root (already in .gitignore - safe)
   GOOGLE_CUSTOM_SEARCH_API_KEY=your_api_key_here
   GOOGLE_CUSTOM_SEARCH_ENGINE_ID=your_engine_id_here
   

   The app will automatically load .env file if it exists (via python-dotenv).

   For HuggingFace Spaces (use Secrets, NOT .env files):

   • Go to your Space → Settings → Secrets
   • Add two secrets:
     • GOOGLE_CUSTOM_SEARCH_API_KEY = your API key
     • GOOGLE_CUSTOM_SEARCH_ENGINE_ID = your Search Engine ID (from embed code cx=YOUR_ID)
   • Secrets are encrypted and never exposed in git
   • Restart the Space after adding secrets

4. Verify Setup:

   • Agent will automatically detect environment variables (from .env locally or Secrets in HF Spaces)
   • Logs will show: ✅ Google Custom Search API configured (will use for web search)
   • Web searches will use Google API (better results)

Note:

• .env file is in .gitignore - safe from git commits
• For HuggingFace Spaces, always use Secrets, not .env files (Secrets are encrypted)
• If Google API key is not configured, agent automatically uses DuckDuckGo (free, unlimited)

🔒 Security Best Practices

HuggingFace Spaces Secrets are Secure:

• ✅ Encrypted at rest - Secrets are stored encrypted in HuggingFace's secure vault
• ✅ Only accessible at runtime - Secrets are injected as environment variables when your Space runs
• ✅ Never exposed in code or logs - Secrets don't appear in git, code, or public logs
• ✅ Private to your Space - Only you and Space collaborators can access Secrets
• ✅ Hackers cannot access - Secrets are not exposed via your Space URL or public API

Google API Key Security (Recommended):

1. Restrict API Key in Google Cloud Console:

   • Go to API Credentials
   • Click on your API key → "Restrict key"
   • Application restrictions: Restrict to "HTTP referrers" → Add your Space URL:
     • https://YOUR-USERNAME-YOUR-SPACE-NAME.hf.space/*
   • API restrictions: Restrict to "Custom Search API" only
   • Save restrictions

2. Monitor Usage:

   • Check Google Cloud Console → "APIs & Services" → "Dashboard"
   • Monitor API usage and costs
   • Set up billing alerts (free tier: 100 queries/day)

3. Search Engine ID Safety:

   • The Search Engine ID (cx=...) is not sensitive - it's just an identifier
   • It's designed to be public (used in embed codes on websites)
   • Cannot be used without the API key - so even if exposed, it's harmless
   • No need to hide or restrict it

What's Safe vs What to Watch:

• ✅ Safe: Search Engine ID (public identifier, harmless without API key)
• ✅ Safe: HuggingFace Spaces Secrets (encrypted, never exposed)
• ⚠️ Protect: API Key (restrict in Google Cloud Console)
• ⚠️ Never commit: .env files, API keys in code, hardcoded credentials

Bottom Line:

• Your API key in HuggingFace Spaces Secrets is secure - encrypted and private
• Add API key restrictions in Google Cloud Console for extra security
• Search Engine ID is not sensitive (designed to be public)
• No risk of hackers accessing your credentials through the Space URL

💰 Google Custom Search API - Cost Information

Free Tier:

• ✅ 100 queries per day - FREE (no credit card needed initially, but billing account required)
• ⚠️ Billing account required even for free tier (you won't be charged for first 100/day)

Automatic Fallback (When Quota Exceeded):

• 🔄 Automatic fallback to DuckDuckGo when Google quota is exceeded (429 or quota-related 403 errors)
• DuckDuckGo is free and unlimited (no API key required)
• Seamless transition - users won't notice interruption
• Logs will indicate: ⚠️ Google Search quota exceeded → Auto-fallback to DuckDuckGo
• No code changes needed - fallback happens automatically
• No paid subscription required - system gracefully handles quota limits

Paid Tier (Optional - Beyond 100 queries/day):

• 💵 $5 per 1,000 queries (after free tier)
• 📊 Maximum: 10,000 queries per day (requires billing enabled)
• Note: If you don't set up paid billing, the system automatically falls back to DuckDuckGo after 100 queries/day

Cost Examples:

• 100 queries/day (3,000/month): FREE ✅ (auto-fallback after quota)
• 500 queries/day (15,000/month): ~$70/month (14,000 additional queries × $5/1,000 = $70) OR use DuckDuckGo (free)
• 1,000 queries/day (30,000/month): ~$145/month (29,000 additional queries × $5/1,000 = $145) OR use DuckDuckGo (free)
• 10,000 queries/day (300,000/month): ~$1,485/month (299,000 additional queries × $5/1,000 = $1,485) OR use DuckDuckGo (free)

Comparison with DuckDuckGo:

• DuckDuckGo: ✅ FREE, unlimited queries (automatic fallback - excellent results!)
• Google Custom Search: Free for 100/day, then $5 per 1,000 queries (optional upgrade)

Recommendation:

• ✅ For Development/Testing: DuckDuckGo is perfect (free, unlimited, good results)
• 💰 For Production: Use Google API only if you need better results AND can afford $5 per 1,000 queries
• ✅ Current Setup: Hybrid approach - tries Google first, automatically falls back to DuckDuckGo when quota exceeded (best of both worlds!)
• 🎯 Best Practice: Let the system automatically fallback to DuckDuckGo - no paid subscription needed unless you specifically need Google's superior results

Enabling Agent Mode

Agent Mode is always enabled by default. Just select your preferred model from the dropdown and ask questions:

• Math: "Calculate the surface area of a 6×4×5 cm rectangular prism"
• Current Events: "What are today's stock market trends?"
• Combined: "What's 2^10 and search for news about quantum computing in 2025"
• Real-time: "Tell me current US stock trends and present day crypto prices"

📝 Sample Test Questions

For comprehensive test questions covering all areas (Math, Web Search, Current Events, Stock Market, Technology, etc.), see docs/testing/test-questions.md.

The test questions file includes:

• 🧮 Math & Calculator queries (basic, geometry, advanced)
• 📰 Current Events & News (today's news, specific topics, global news)
• 💼 Stock Market & Financial (market trends, specific markets, combined queries)
• 💻 Technology & AI (AI trends, tech news, emerging technologies)
• 🎓 Educational & Research (science, academic topics, general knowledge)
• 🔄 Combined Queries (Math + Search in one question)
• 🌍 Real-time Information (time-sensitive queries, specific dates/years)
• 🎯 Edge Cases (complex multi-part questions, natural language variations)

Quick Start Examples:

• "Calculate 25 * 48" - Tests calculator tool
• "Search for latest AI trends" - Tests web search tool
• "What's 2^10 and also search for current stock market trends" - Tests combined tool usage

🚀 Usage

1. Click "Initialize" to load meeTARA (first time may take a few minutes to download models)
2. Type your message and press Enter or click "Send"
3. meeTARA will analyze your query and provide an empathetic, domain-specific response

📚 Domains Supported

• 🏥 Healthcare & Medical
• 💼 Business & Professional
• 🎓 Education & Academic
• 🎨 Creative & Writing
• 💻 Technology & Programming
• 🧘 Psychology & Wellness
• 🏃 Sports & Recreation
• ⚖️ Legal & Financial
• 🚨 Emergency & Crisis
• ✈️ Travel & Tourism
• 🏭 Industrial & Manufacturing
• 🍳 Food & Cooking
• 🎬 Entertainment & Media
• And more...

⚙️ Configuration

Model Configuration (config/agent_config.json)

All model and agent behavior is configurable via the config/agent_config.json file:

System Prompt Configuration

The system prompt (meeTARA's identity and response format) can be customized in config/agent_config.json:

{
  "model": {
    "system_prompt": {
      "enabled": true,
      "prompt": "You are meeTARA, an accurate AI assistant.\nIMPORTANT: For math/calculations, always verify your answer before responding.\nRespond in this format:\n🎯 **Answer**: Direct answer (must be correct)\n📊 **Details**: Key facts (2-3 bullets)\n⚡ **Steps**: Show your work/calculation\n💡 **Note**: Any warnings (1 sentence)\nBe accurate first, concise second."
    },
    "generation_settings": {
      "temperature": 0.2,
      "top_k": 40,
      "top_p": 0.9,
      "repeat_penalty": 1.1
    }
  }
}

Benefits:

• ✅ Customizable Personality: Change meeTARA's identity and instructions without code changes
• ✅ Response Format Control: Modify the structured format (🎯📊⚡💡) or create your own
• ✅ Generation Parameters: Adjust temperature, top_p, etc. for different response styles
• ✅ Easy Updates: Modify config file and restart - no code changes needed
• ✅ Fallback Safe: If config not available or invalid, uses default hardcoded values

Default Behavior:

• If config/agent_config.json is not available → Uses hardcoded default system prompt
• If system prompt is disabled (enabled: false) → Uses default system prompt
• If system prompt is empty → Uses default system prompt

Agent Configuration (config/agent_config.json)

The agent tool detection behavior is fully configurable:

• Web Search Keywords: Add terms like "today", "current", "present day", "stock market", etc.
• Search Patterns: Regex patterns to extract search queries from natural language
• Calculator Keywords: Terms that trigger calculator tool (e.g., "calculate", "compute", "what is")
• Math Patterns: Regex patterns to detect mathematical expressions
• Settings: Default max_tokens, tool timeouts, etc.

Example: Adding a new keyword

{
  "web_search": {
    "keywords": [
      "current",
      "today",
      "latest",
      "your-new-keyword"  // Add here
    ]
  }
}

No code changes needed - just edit the JSON file and restart!

🔧 Technical Details

• Framework: Gradio 4.44.1
• Backend: Python with llama-cpp-python
• Models: GGUF quantized models (Qwen3, Qwen2.5, Phi3.5)
• Inference: llama.cpp with optimized parameters
• Agent System: Simple Direct Agent (pattern-based tool detection)
• Config System: Centralized JSON-based configuration via config/config_loader.py
• Tools: DuckDuckGo search (duckduckgo-search), Python calculator (built-in eval)

📖 Documentation

Project Documentation

Document	Description
Architecture: Core vs Agent	Detailed analysis of MeeTARA's two-layer architecture
Deployment: HuggingFace Spaces	Guide for deploying to HF Spaces
Feature: Domain Prompts	Domain-specific system prompts documentation
Feature: Word Problems	How MeeTARA handles different types of word problems
Feature: Agent Performance	Performance optimizations and improvements
Testing: Test Questions	Comprehensive test questions for all capabilities

External Links

• GitHub Repository
• Model Repository

⚠️ Resource Requirements

• CPU: Recommended 4+ cores
• RAM: 4-8GB (model dependent)
• Storage: ~10GB for all models
• First Load: Models download automatically on first initialization

📄 License

MIT License - See LICENSE file for details

---

meeTARA - Where AI meets empathy 💝