kairo-code 0.1.0__py3-none-any.whl → 0.2.0__py3-none-any.whl

kairo/backend/services/few_shot_service.py

@@ -0,0 +1,223 @@
+"""Dynamic few-shot example injection for small models.
+
+Provides relevant examples based on query type to improve response
+quality for 14B parameter models like Nyx Lite.
+"""
+
+import logging
+
+logger = logging.getLogger(__name__)
+
+# Code examples for different languages/contexts
+_PYTHON_CODE_EXAMPLE = """
+<example>
+User: Write a function to validate email addresses
+Assistant: Here's a function to validate email addresses:
+
+```python
+import re
+
+def validate_email(email: str) -> bool:
+    \"\"\"Validate email address format.\"\"\"
+    pattern = r'^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$'
+    return bool(re.match(pattern, email))
+
+# Usage
+print(validate_email("test@example.com"))  # True
+print(validate_email("invalid"))           # False
+```
+
+The regex checks for: local part + @ + domain + TLD (2+ chars).
+</example>
+"""
+
+_JAVASCRIPT_CODE_EXAMPLE = """
+<example>
+User: Create a debounce function in JavaScript
+Assistant: Here's a debounce function:
+
+```javascript
+function debounce(func, delay) {
+    let timeoutId;
+    return function(...args) {
+        clearTimeout(timeoutId);
+        timeoutId = setTimeout(() => func.apply(this, args), delay);
+    };
+}
+
+// Usage
+const debouncedSearch = debounce((query) => {
+    console.log('Searching:', query);
+}, 300);
+```
+
+This delays execution until `delay` ms after the last call.
+</example>
+"""
+
+_API_USAGE_EXAMPLE = """
+<example>
+User: How do I fetch data from an API in Python?
+Assistant: [Uses deep_search to verify API documentation]
+
+Here's how to fetch data from an API:
+
+```python
+import requests
+
+response = requests.get(
+    "https://api.example.com/data",
+    headers={"Authorization": "Bearer YOUR_TOKEN"},
+    params={"limit": 10}
+)
+
+if response.status_code == 200:
+    data = response.json()
+    print(data)
+else:
+    print(f"Error: {response.status_code}")
+```
+
+Always check the status code before parsing the response.
+</example>
+"""
+
+_DEBUGGING_EXAMPLE = """
+<example>
+User: I get TypeError: 'NoneType' object is not subscriptable
+Assistant: This error occurs when you try to access an index or key on a `None` value.
+
+**Common causes:**
+1. Function returning `None` instead of expected value
+2. Dictionary key doesn't exist (`.get()` returns `None`)
+3. API returning empty response
+
+**Fix:** Add None checks:
+
+```python
+result = get_data()
+if result is not None:
+    value = result['key']
+else:
+    value = default_value
+
+# Or use .get() with default:
+value = data.get('key', default_value)
+```
+</example>
+"""
+
+_FACTUAL_EXAMPLE = """
+<example>
+User: What is the difference between REST and GraphQL?
+Assistant: **REST vs GraphQL:**
+
+| Aspect | REST | GraphQL |
+|--------|------|---------|
+| Endpoints | Multiple (one per resource) | Single endpoint |
+| Data fetching | Fixed response structure | Client specifies exact fields |
+| Over-fetching | Common problem | Avoided by design |
+| Versioning | URL versioning (v1, v2) | Schema evolution |
+
+**Use REST when:** Simple CRUD, caching is critical, team familiarity.
+**Use GraphQL when:** Complex data relationships, mobile apps need minimal data.
+</example>
+"""
+
+# Trigger words for each example type
+_EXAMPLE_TRIGGERS = {
+    "python": {
+        "triggers": ["python", "py", "django", "flask", "fastapi", "pip"],
+        "example": _PYTHON_CODE_EXAMPLE,
+    },
+    "javascript": {
+        "triggers": ["javascript", "js", "node", "react", "vue", "typescript", "npm"],
+        "example": _JAVASCRIPT_CODE_EXAMPLE,
+    },
+    "api": {
+        "triggers": ["api", "endpoint", "rest", "http", "fetch", "request", "curl"],
+        "example": _API_USAGE_EXAMPLE,
+    },
+    "debug": {
+        "triggers": ["error", "bug", "fix", "debug", "not working", "issue", "traceback", "exception"],
+        "example": _DEBUGGING_EXAMPLE,
+    },
+    "factual": {
+        "triggers": ["what is", "difference between", "compare", "vs", "versus", "explain"],
+        "example": _FACTUAL_EXAMPLE,
+    },
+}
+
+
+def get_few_shot_examples(message: str, model: str) -> str:
+    """Get relevant few-shot examples based on query type.
+
+    Args:
+        message: The user's message
+        model: The model being used (only injects for small models)
+
+    Returns:
+        Examples string to inject into system prompt, or empty string.
+    """
+    # Only inject for small models
+    if model not in ("nyx-lite",):
+        return ""
+
+    msg_lower = message.lower()
+    examples = []
+
+    for category, data in _EXAMPLE_TRIGGERS.items():
+        if any(trigger in msg_lower for trigger in data["triggers"]):
+            examples.append(data["example"])
+            if len(examples) >= 2:  # Max 2 examples to save context
+                break
+
+    if not examples:
+        return ""
+
+    result = "\n".join(examples)
+    logger.debug("Injecting %d few-shot examples for query type", len(examples))
+    return result
+
+
+def get_output_format_instructions(message: str, model: str) -> str:
+    """Get explicit output format instructions based on query type.
+
+    Args:
+        message: The user's message
+        model: The model being used
+
+    Returns:
+        Format instructions string, or empty string.
+    """
+    if model not in ("nyx-lite",):
+        return ""
+
+    msg_lower = message.lower()
+
+    # Code queries
+    if any(w in msg_lower for w in ["code", "function", "implement", "write", "create a"]):
+        return """
+[Output Format]
+1. Brief explanation (1-2 sentences)
+2. Code in fenced block with language tag
+3. Usage example
+Do NOT repeat code blocks."""
+
+    # Debugging queries
+    if any(w in msg_lower for w in ["error", "bug", "fix", "not working"]):
+        return """
+[Output Format]
+1. Identify the problem
+2. Explain the cause
+3. Provide the solution with code
+4. Explain why it works"""
+
+    # Comparison queries
+    if any(w in msg_lower for w in ["compare", "difference", "vs", "versus"]):
+        return """
+[Output Format]
+Use a comparison table when appropriate.
+Be concise and direct."""
+
+    return ""

kairo/backend/services/post_processor.py

@@ -0,0 +1,261 @@
+"""Post-processor for LLM responses.
+
+Validates generated code against tool results to catch hallucinated
+endpoints, parameters, and URLs. Runs after the model generates a
+response but before it's sent to the user.
+
+Enhanced with:
+- Code syntax validation (unclosed brackets, incomplete imports)
+- Duplicate code detection
+- Placeholder detection
+- Claims verification against sources
+"""
+
+import logging
+import re
+
+logger = logging.getLogger(__name__)
+
+
+def _extract_urls_from_text(text: str) -> set[str]:
+    """Extract all URLs from text."""
+    return set(re.findall(r'https?://[^\s\'"<>\)]+', text))
+
+
+def _extract_code_blocks(text: str) -> list[str]:
+    """Extract code from fenced code blocks."""
+    blocks = re.findall(r'```[\w]*\n(.*?)```', text, re.DOTALL)
+    return blocks
+
+
+def _extract_urls_from_code(code_blocks: list[str]) -> set[str]:
+    """Extract URLs used in code blocks."""
+    urls = set()
+    for block in code_blocks:
+        # Match string literals containing URLs
+        urls.update(re.findall(r'["\']+(https?://[^\s\'"<>\)]+)["\']', block))
+        # Match f-string URLs
+        urls.update(re.findall(r'f["\']+(https?://[^"\'{}]+)', block))
+    return urls
+
+
+def _extract_param_names(code_blocks: list[str]) -> set[str]:
+    """Extract parameter names from request params/dicts in code."""
+    params = set()
+    for block in code_blocks:
+        # Match dict keys in params-like structures: {'key': value} or {"key": value}
+        params.update(re.findall(r'["\'](\w+)["\']\s*:', block))
+    return params
+
+
+def _validate_code_syntax(code_blocks: list[str]) -> list[str]:
+    """Validate code block syntax and return issues.
+
+    Checks for common problems small models make:
+    - Unclosed brackets/parentheses/braces
+    - Incomplete import statements
+    - Placeholder values
+    - Unterminated strings
+    """
+    issues = []
+
+    for i, block in enumerate(code_blocks):
+        block_issues = []
+
+        # Check for unclosed brackets/parentheses/braces
+        open_parens = block.count('(') - block.count(')')
+        open_brackets = block.count('[') - block.count(']')
+        open_braces = block.count('{') - block.count('}')
+
+        if open_parens > 0:
+            block_issues.append(f"{open_parens} unclosed parenthesis")
+        elif open_parens < 0:
+            block_issues.append(f"{-open_parens} extra closing parenthesis")
+
+        if open_brackets > 0:
+            block_issues.append(f"{open_brackets} unclosed bracket")
+        elif open_brackets < 0:
+            block_issues.append(f"{-open_brackets} extra closing bracket")
+
+        if open_braces > 0:
+            block_issues.append(f"{open_braces} unclosed brace")
+        elif open_braces < 0:
+            block_issues.append(f"{-open_braces} extra closing brace")
+
+        # Check for incomplete imports (ending with comma or nothing after 'import')
+        lines = block.split('\n')
+        for line in lines:
+            stripped = line.strip()
+            if stripped.startswith('import ') and stripped.endswith(','):
+                block_issues.append("incomplete import statement")
+                break
+            if stripped == 'import' or stripped == 'from':
+                block_issues.append("incomplete import statement")
+                break
+
+        # Check for placeholder patterns that shouldn't be in final code
+        placeholders = re.findall(
+            r'YOUR_[A-Z_]+|<[A-Z_]+>|REPLACE_THIS|TODO:|FIXME:|XXX:',
+            block
+        )
+        if placeholders:
+            unique_placeholders = list(set(placeholders))[:3]  # Limit display
+            block_issues.append(f"placeholder values: {', '.join(unique_placeholders)}")
+
+        # Check for ellipsis used as placeholder (common in small model output)
+        if '...' in block and 'range(' not in block and 'slice' not in block:
+            # Check if ... is used as code placeholder vs legitimate use
+            ellipsis_lines = [l for l in lines if '...' in l and not l.strip().startswith('#')]
+            if ellipsis_lines:
+                # Check context - if it looks like placeholder code
+                for el in ellipsis_lines:
+                    if el.strip() == '...' or el.strip().endswith('...'):
+                        block_issues.append("incomplete code (ellipsis placeholder)")
+                        break
+
+        if block_issues:
+            issues.extend(block_issues)
+
+    return issues[:5]  # Limit to 5 issues
+
+
+def _detect_duplicate_code(code_blocks: list[str]) -> bool:
+    """Detect if there are duplicate code blocks."""
+    if len(code_blocks) < 2:
+        return False
+
+    seen_normalized = set()
+    for block in code_blocks:
+        # Normalize: collapse whitespace, lowercase
+        normalized = ' '.join(block.lower().split())
+        if len(normalized) < 50:
+            continue  # Skip very short blocks
+
+        if normalized in seen_normalized:
+            return True
+
+        # Also check for substantial overlap (80%+)
+        for seen in seen_normalized:
+            shorter = min(len(normalized), len(seen))
+            if shorter > 100:
+                # Compare first N chars
+                if normalized[:shorter] == seen[:shorter]:
+                    return True
+
+        seen_normalized.add(normalized)
+
+    return False
+
+
+def _verify_claims_against_sources(response: str, tool_results: str) -> list[str]:
+    """Identify claims in response that aren't supported by sources."""
+    warnings = []
+    response_lower = response.lower()
+    tool_lower = tool_results.lower()
+
+    # Check for statistics/numbers that should come from sources
+    stat_patterns = [
+        (r'(\d{1,3}(?:,\d{3})*)\s*(?:users?|customers?|downloads?|stars?)', "user/download count"),
+        (r'(?:costs?|pricing?|price)\s*(?:is\s*)?\$(\d+)', "pricing"),
+        (r'(\d+)%\s*(?:faster|slower|better|improvement)', "performance claim"),
+    ]
+
+    for pattern, claim_type in stat_patterns:
+        matches = re.findall(pattern, response_lower)
+        for match in matches:
+            # Check if this number appears in the sources
+            if match not in tool_lower:
+                warnings.append(f"{claim_type} ({match}) not found in sources")
+
+    # Check for requirement claims
+    if 'require' in response_lower or 'must have' in response_lower or 'need to' in response_lower:
+        # Check if sources mention it's free/no signup
+        if 'free' in tool_lower and 'no' in tool_lower and ('signup' in tool_lower or 'registration' in tool_lower):
+            if 'sign up' in response_lower or 'register' in response_lower:
+                warnings.append("response mentions signup but sources indicate it may be free/no signup required")
+
+    return warnings[:3]  # Limit warnings
+
+
+def validate_response(response: str, tool_results: str | None) -> str:
+    """Validate a model response against tool results.
+
+    If the response contains code with API calls that contradict
+    the tool results, append a correction note.
+
+    Args:
+        response: The model's generated response
+        tool_results: The raw tool result text (from deep_search/web_search), or None
+
+    Returns:
+        The response, potentially with a correction appended.
+    """
+    if not response:
+        return response
+
+    code_blocks = _extract_code_blocks(response)
+    corrections = []
+
+    # CODE SYNTAX VALIDATION (always run, even without tool results)
+    if code_blocks:
+        syntax_issues = _validate_code_syntax(code_blocks)
+        for issue in syntax_issues:
+            corrections.append(f"**Code issue:** {issue}")
+
+        # Duplicate detection
+        if _detect_duplicate_code(code_blocks):
+            corrections.append("**Note:** Duplicate code block detected - please use only the final version")
+
+    # TOOL RESULT VALIDATION (only if we have tool results)
+    if tool_results and code_blocks:
+        # Extract URLs from tool results and code
+        tool_urls = _extract_urls_from_text(tool_results)
+        code_urls = _extract_urls_from_code(code_blocks)
+
+        # Check for fabricated base URLs in code that don't appear in tool results
+        if code_urls and tool_urls:
+            # Normalize to base domains for comparison
+            def base_domain(url: str) -> str:
+                match = re.match(r'https?://([^/]+)', url)
+                return match.group(1) if match else url
+
+            tool_domains = {base_domain(u) for u in tool_urls}
+            for url in code_urls:
+                domain = base_domain(url)
+                # Skip common/known domains
+                if domain in ('api.openweathermap.org', 'api.github.com', 'jsonplaceholder.typicode.com',
+                              'api.example.com', 'example.com', 'localhost'):
+                    continue
+                if domain not in tool_domains and not any(domain in td or td in domain for td in tool_domains):
+                    # Check if the full URL path was fabricated
+                    url_base = url.split('?')[0]
+                    if not any(url_base in tr for tr in tool_urls):
+                        corrections.append(
+                            f"**Verify:** The URL `{url}` was not found in the documentation. "
+                            f"Please confirm this endpoint exists."
+                        )
+
+        # Verify claims against sources
+        claim_warnings = _verify_claims_against_sources(response, tool_results)
+        for warning in claim_warnings:
+            corrections.append(f"**Verify:** {warning}")
+
+    # Check date format patterns in code
+    if tool_results:
+        for block in code_blocks:
+            # Wrong date format: %Y%m%d when docs show YYYY-MM-DD
+            if '%Y%m%d' in block and 'YYYY-MM-DD' in tool_results:
+                corrections.append(
+                    "**Correction:** The date format should be `YYYY-MM-DD` (use `strftime('%Y-%m-%d')`), "
+                    "not `YYYYMMDD`, according to the API documentation."
+                )
+                break
+
+    if corrections:
+        # Deduplicate corrections
+        unique_corrections = list(dict.fromkeys(corrections))
+        correction_text = "\n\n---\n**Review Notes:**\n" + "\n".join(f"- {c}" for c in unique_corrections)
+        logger.info("Post-processor added %d corrections", len(unique_corrections))
+        return response + correction_text
+
+    return response

kairo/backend/services/rag_service.py

@@ -0,0 +1,150 @@
+"""RAG service for looking up internal documentation.
+
+Loads curated JSON knowledge bases and returns relevant docs
+when the model calls the lookup_kairo_docs tool.
+"""
+
+import json
+import logging
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+_DATA_DIR = Path(__file__).resolve().parent.parent.parent / "data"
+_DOCS_CACHE: dict | None = None
+
+
+def _load_docs() -> dict:
+    """Load and cache the API docs JSON."""
+    global _DOCS_CACHE
+    if _DOCS_CACHE is not None:
+        return _DOCS_CACHE
+
+    docs_path = _DATA_DIR / "kairo_docs.json"
+    if not docs_path.exists():
+        logger.warning("kairo_docs.json not found at %s", docs_path)
+        return {}
+
+    with open(docs_path) as f:
+        _DOCS_CACHE = json.load(f)
+    logger.info("Loaded RAG docs from %s", docs_path)
+    return _DOCS_CACHE
+
+
+def lookup_kairo_docs(topic: str) -> str:
+    """Look up Kairo API documentation by topic.
+
+    Args:
+        topic: What the user is asking about (e.g. "chat completions",
+               "authentication", "models", "streaming", "python sdk")
+
+    Returns:
+        Formatted documentation string with all relevant Kairo API info.
+    """
+    docs = _load_docs()
+    if not docs:
+        return "No internal documentation available."
+
+    kairo = docs.get("kairo", {})
+    auth = kairo.get("auth", {})
+    endpoints = kairo.get("endpoints", [])
+    models = kairo.get("models", [])
+    notes = kairo.get("notes", [])
+
+    topic_lower = topic.lower()
+
+    # Determine if user wants streaming or specific language examples
+    want_streaming = any(w in topic_lower for w in ("stream", "sse", "realtime"))
+    want_js = any(w in topic_lower for w in ("javascript", "js", "node", "typescript"))
+    want_curl = any(w in topic_lower for w in ("curl", "bash", "shell", "http"))
+
+    parts = []
+
+    # Strong instruction header so the model uses this data
+    parts.append(
+        "IMPORTANT: The following is OFFICIAL Kairo API documentation. "
+        "You MUST use ONLY the information below when answering about the Kairo API. "
+        "Do NOT use your training data for Kairo API details. The code examples below "
+        "are verified and correct — use them as-is or adapt them to the user's request."
+    )
+    parts.append("")
+    parts.append("=== KAIRO API DOCUMENTATION ===")
+    parts.append(f"Query: {topic}")
+    parts.append("")
+
+    # Auth
+    parts.append("## Authentication")
+    parts.append(f"- Method: {auth.get('method', 'N/A')}")
+    parts.append(f"- Header: {auth.get('header', 'N/A')}")
+    parts.append(f"- Key format: {auth.get('key_format', 'N/A')}")
+    parts.append(f"- How to get a key: {auth.get('how_to_get_key', 'N/A')}")
+    rl = kairo.get("rate_limits", {})
+    parts.append(f"- Rate limit: {rl.get('requests_per_minute', 'N/A')} requests/min per key")
+    parts.append("")
+
+    # Models
+    parts.append("## Available Models")
+    for m in models:
+        parts.append(f"- {m['id']} ({m['name']}): {m['description']} | Context: {m['context_window']} tokens")
+    parts.append("")
+
+    # Chat completions endpoint (always include — it's the main endpoint)
+    for ep in endpoints:
+        if ep["path"] == "/v1/chat/completions":
+            parts.append(f"## {ep['method']} {ep['path']}")
+            parts.append(ep["description"])
+            parts.append("")
+            parts.append("Request body parameters:")
+            for param, desc in ep["request_body"].items():
+                parts.append(f"  - {param}: {desc}")
+            parts.append("")
+
+            # Always include Python example (primary use case)
+            if not want_curl or want_js:
+                parts.append("### Python Example (CORRECT — use this pattern)")
+                parts.append("```python")
+                parts.append(ep["example_python"])
+                parts.append("```")
+                parts.append("")
+
+            if want_streaming:
+                parts.append("### Python Streaming Example")
+                parts.append("```python")
+                parts.append(ep["example_streaming"])
+                parts.append("```")
+                parts.append("")
+
+            if want_js:
+                parts.append("### JavaScript/Node.js Example")
+                parts.append("```javascript")
+                parts.append(ep["example_javascript"])
+                parts.append("```")
+                parts.append("")
+
+            if want_curl:
+                parts.append("### cURL Example")
+                parts.append("```bash")
+                parts.append(ep["example_curl"])
+                parts.append("```")
+                parts.append("")
+
+    # Other endpoints
+    for ep in endpoints:
+        if ep["path"] != "/v1/chat/completions":
+            parts.append(f"## {ep['method']} {ep['path']}")
+            parts.append(ep["description"])
+            if "example_curl" in ep:
+                parts.append(f"Example: {ep['example_curl']}")
+            parts.append("")
+
+    # Notes
+    parts.append("## Important Notes")
+    for note in notes:
+        parts.append(f"- {note}")
+
+    parts.append("")
+    parts.append("=== END KAIRO API DOCUMENTATION ===")
+
+    result = "\n".join(parts)
+    logger.info("lookup_kairo_docs(%s) returned %d chars", topic, len(result))
+    return result