Skip to main content

answer.generate

Submits a query to a text namespace to get a conversational answer generated by an LLM.

Parameters

namespace
str
required
The single text namespace to search for context, or empty string "" for Direct AI Mode.
query
str
required
The user’s question or prompt.
top_k
int
default:"10"
Number of top relevant chunks for your query across given namespace. Default is 10.
threshold
Optional[float]
Minimum relevance score threshold (0-1) to filter out chunks below this relevance level. Required when kiosk_mode is true. Only used in Search Mode.
kiosk_mode
bool
default:"False"
Enable kiosk mode to filter chunks below certain relevance. When kiosk mode is on, threshold is required. Only used in Search Mode.
ai_model
str
default:"anthropic.claude-v2:1"
The identifier for the LLM to use.
chat_history
Optional[List[Dict]]
A list of previous conversation turns to maintain context.
temperature
float
default:"0.7"
The sampling temperature for the LLM (0-1). Defaults to 0.7.
header_prompt
Optional[str]
Custom instruction for AI behavior.
Custom instruction to append.
Returns: Dict[str, Any] - A dictionary containing the answer, model, and other metadata. Raises: NamespaceNotFound, InvalidInputError.

Search Mode Example (with namespace)

Generate Answer Example
from moorcheh_sdk import MoorchehClient

with MoorchehClient() as client:
    response = client.answer.generate(
        namespace="my-faq-documents",
        query="What is your return policy?",
        top_k=2
    )
    
    print(f"AI Answer: {response['answer']}")
    print(f"Model Used: {response['model']}")
    print(f"Context Count: {response['contextCount']}")

Direct AI Mode Example (empty namespace)

Direct AI Mode Example
from moorcheh_sdk import MoorchehClient

with MoorchehClient() as client:
    response = client.answer.generate(
        namespace="",  # Empty string for direct AI mode
        query="Explain quantum computing in simple terms",
        ai_model="anthropic.claude-sonnet-4-20250514-v1:0",
        temperature=0.7,
        chat_history=[
            {"role": "user", "content": "What is AI?"},
            {"role": "assistant", "content": "AI is artificial intelligence..."}
        ],
        header_prompt="You are a science teacher.",
        footer_prompt="Use simple language and examples."
    )
    
    print(f"Answer: {response['answer']}")

Conversational AI with History

Conversational AI with History
from moorcheh_sdk import MoorchehClient

with MoorchehClient() as client:
    chat_history = [
        {"role": "user", "content": "What are your business hours?"},
        {"role": "assistant", "content": "Our business hours are Monday to Friday, 9 AM to 5 PM EST."}
    ]
    
    response = client.answer.generate(
        namespace="customer-support",
        query="What about weekends?",
        chat_history=chat_history,
        temperature=0.5,
        ai_model="anthropic.claude-sonnet-4-5-20250929-v1:0"
    )
    
    print(f"AI Answer: {response['answer']}")
    print(f"Model Used: {response['model']}")
    print(f"Context Count: {response['contextCount']}")

Complete Example

Complete Search and AI Workflow
from moorcheh_sdk import MoorchehClient
import time

with MoorchehClient() as client:
    namespace = "customer-support"
    
    # 1. Create namespace and upload support documents
    client.namespaces.create(namespace, type="text")
    
    support_docs = [
        {
            "id": "policy-1",
            "text": "Our return policy allows returns within 30 days of purchase with original receipt.",
            "category": "returns"
        },
        {
            "id": "policy-2",
            "text": "We offer free shipping on orders over $50. Standard shipping takes 3-5 business days.",
            "category": "shipping"
        },
        {
            "id": "hours-1",
            "text": "Our customer service is available Monday-Friday 9AM-5PM EST. We're closed on weekends.",
            "category": "hours"
        }
    ]
    
    client.documents.upload(namespace, support_docs)
    print("Documents uploaded, waiting for processing...")
    time.sleep(5)
    
    # 2. Get AI-generated answers
    print("\n=== AI ANSWERS ===")
    questions = [
        "What is your return policy?",
        "How long does shipping take?",
        "Are you open on weekends?"
    ]
    
    for question in questions:
        response = client.answer.generate(
            namespace=namespace,
            query=question,
            top_k=1
        )
        print(f"Q: {question}")
        print(f"A: {response['answer']}")
        print()

AI Response Structure

AI generation responses contain:
AI Response Format
{
    'answer': 'Generated answer text...',
    'model': 'anthropic.claude-sonnet-4-5-20250929-v1:0',
    'contextCount': 3,  # Number of documents used as context
    'query': 'Original user query'
}

API Modes

Search Mode (with namespace)

When you provide a namespace, the API searches your data for relevant context and uses it to generate contextual answers.

Direct AI Mode (empty namespace)

When you pass an empty string "" as namespace, the API makes a direct call to the AI model without searching your data.
Field Restrictions:
  • Empty Namespace Mode: Only these fields are allowed: namespace, query, temperature, chatHistory, footerPrompt, headerPrompt, aiModel
  • Provided Namespace Mode: All fields are allowed: namespace, query, top_k, threshold, type, kiosk_mode, aiModel, chatHistory, headerPrompt, footerPrompt, temperature

Available Models

Model IDNameProviderDescriptionCredits
anthropic.claude-sonnet-4-20250514-v1:0Claude Sonnet 4AnthropicHybrid reasoning, extended thinking, efficient code generation3
anthropic.claude-sonnet-4-5-20250929-v1:0Claude Sonnet 4.5AnthropicLatest Claude model with enhanced capabilities and agentic search3
anthropic.claude-opus-4-5-20251101-v1:0Claude Opus 4.5AnthropicMost advanced Claude model with superior reasoning and extended thinking capabilities3
meta.llama4-maverick-17b-instruct-v1:0Llama 4 Maverick 17BMeta1M token context, fine tuning, text summarization, function calling3
meta.llama3-3-70b-instruct-v1:0Llama 3.3 70BMetaAdvanced reasoning and decision making capabilities1
amazon.nova-pro-v1:0Amazon Nova ProAmazon300K context, chat optimized, complex reasoning, math2
deepseek.r1-v1:0DeepSeek R1DeepSeekAdvanced reasoning and code generation1

Temperature Guide

  • 0.0-0.5: Conservative, factual responses - best for technical documentation
  • 0.5-1.0: Balanced creativity - good for general Q&A
  • 1.0-2.0: More creative and varied responses - use carefully for factual content

Relevance Score Threshold

Results are scored using Information Theoretic Similarity (ITS), providing nuanced relevance measurements:
LabelScore RangeDescription
Close Matchscore ≥ 0.894Near-perfect relevance to the query
Very High Relevance0.632 ≤ score < 0.894Strongly related content
High Relevance0.447 ≤ score < 0.632Significantly related content
Good Relevance0.316 ≤ score < 0.447Moderately related content
Low Relevance0.224 ≤ score < 0.316Minimally related content
Very Low Relevance0.1 ≤ score < 0.224Barely related content
Irrelevantscore < 0.1No meaningful relation to the query

Best Practices

  • Provide clear, specific questions
  • Use chat history for conversational experiences
  • Adjust temperature based on creativity needs
  • Choose appropriate AI models for your use case
  • For Search Mode: Higher top_k values provide more context but may increase response time
  • For Search Mode: The threshold parameter can be used to filter low-relevance results

Use Cases

  • Customer Support: Answer customer questions using your documentation
  • Internal Q&A: Help employees find answers in company knowledge bases
  • Educational Tools: Create AI tutors using educational content
  • Research Assistance: Get insights from research papers and publications
  • Technical Support: Provide technical answers based on documentation
  • Content Creation: Generate content based on existing materials