> ## Documentation Index
> Fetch the complete documentation index at: https://docs.moorcheh.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Generate AI Answer

> Generate AI-powered answers using your data as context or direct LLM calls.

## Overview

Generate AI-powered answers with two modes:

* **Search Mode** — provide a `namespace` name; Moorcheh searches your text namespace and uses retrieved chunks as RAG context
* **Direct AI Mode** — set `namespace` to `""` (empty string) for a direct LLM call without retrieval

<Info>
  LLM providers: **Ollama**, **OpenAI**, or **Cohere**. Configure once with `moorcheh configure` (saved under `llm` in `~/.moorcheh/config.json`). Override the model per request with `ai_model`.
</Info>

<Note>
  After changing LLM (or embedding) settings, run **`moorcheh down`** then **`moorcheh up`** so the running server loads the new config. `moorcheh configure` does not restart Docker. Check `GET /health` for `llm_provider` and `llm_model`.
</Note>

<Warning>
  If you change the **embedding** provider or model while you already have text data under `~/.moorcheh/data`, RAG answers for existing namespaces may be wrong until you re-upload with the new embeddings. Changing only the answer (LLM) model does not require re-uploading.
</Warning>

## Headers

<ParamField header="Content-Type" type="string" required>
  Must be `application/json`
</ParamField>

## Body Parameters

<ParamField body="query" type="string" required>
  The user's question or query to be answered
</ParamField>

<ParamField body="namespace" type="string" required>
  Namespace name for Search Mode, or empty string `""` for Direct AI Mode
</ParamField>

<ParamField body="top_k" type="number" default="10">
  Number of top relevant chunks for your query (Search Mode only). Clamped to **1–100**.
</ParamField>

<ParamField body="threshold" type="number">
  Minimum relevance score threshold (**0–1**). Required when `kiosk_mode` is `true`.
</ParamField>

<ParamField body="temperature" type="number" default="0.7">
  AI creativity level (**0.0–2.0**). Higher = more creative.
</ParamField>

<ParamField body="type" type="string" default="text">
  Search type for RAG. Only `"text"` is supported on-prem.
</ParamField>

<ParamField body="ai_model" type="string">
  Override the configured LLM model for this request
</ParamField>

<ParamField body="kiosk_mode" type="boolean" default="false">
  When `true`, `threshold` is **required** and chunks below the threshold are filtered out (Search Mode).
</ParamField>

<ParamField body="chat_history" type="array" default="[]">
  Previous conversation turns: `[{"role":"user"|"assistant","content":"..."}]`
</ParamField>

<ParamField body="header_prompt" type="string">
  Custom system instruction prepended to the prompt
</ParamField>

<ParamField body="footer_prompt" type="string" default="Provide a clear and concise answer.">
  Custom instruction appended before the user query
</ParamField>

<ParamField body="structured_response" type="object">
  When set with `enabled: true`, the API parses JSON from the model into `structured_data`. Optional: `schema` (JSON Schema object).
</ParamField>

## Available LLM models (configure defaults)

| Provider   | Example model IDs                                                       | Notes                      |
| ---------- | ----------------------------------------------------------------------- | -------------------------- |
| **ollama** | `qwen2.5`, `llama3.2`, `mistral`                                        | Local; no API key          |
| **openai** | `gpt-5.5`, `gpt-5`, `gpt-4o-mini`                                       | Requires API key in config |
| **cohere** | `command-a-plus-05-2026`, `command-r-plus-08-2024`, `command-r-08-2024` | Requires API key in config |

<RequestExample>
  ```bash Search Mode (with namespace) theme={null}
  curl -X POST "http://localhost:8080/answer" \
    -H "Content-Type: application/json" \
    -d '{
      "namespace": "my-documents",
      "query": "What are the main benefits of Moorcheh?",
      "top_k": 5
    }'
  ```

  ```bash Direct AI Mode (empty namespace) theme={null}
  curl -X POST "http://localhost:8080/answer" \
    -H "Content-Type: application/json" \
    -d '{
      "namespace": "",
      "query": "Explain quantum computing in simple terms",
      "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."
    }'
  ```

  ```json Structured output (default schema) theme={null}
  {
    "namespace": "my-namespace",
    "query": "What are the system requirements?",
    "structured_response": { "enabled": true }
  }
  ```
</RequestExample>

<ResponseExample>
  ```json 200 - Success theme={null}
  {
    "answer": "Serverless architecture offers several benefits...",
    "model": "gpt-4o-mini",
    "context_count": 3,
    "query": "What are the main benefits of using serverless architecture?"
  }
  ```

  ```json 200 - Structured output theme={null}
  {
    "answer": "{ \"answer\": \"...\", \"confidence\": 0.92 }",
    "model": "llama3.2",
    "context_count": 2,
    "query": "What are the system requirements?",
    "used_context": true,
    "structured_data": {
      "answer": "The main answer",
      "confidence": 0.92,
      "topics": ["requirements", "hardware"]
    }
  }
  ```

  ```json 400 - Bad Request theme={null}
  {
    "status": "error",
    "message": "query field is required"
  }
  ```

  ```json 400 - Namespace not found theme={null}
  {
    "status": "error",
    "message": "namespace 'my-namespace' not found"
  }
  ```

  ```json 500 - Server Error theme={null}
  {
    "status": "failure",
    "message": "Internal Server Error generating answer.: ..."
  }
  ```
</ResponseExample>

## Response Fields

<ResponseField name="answer" type="string">
  The AI-generated answer text
</ResponseField>

<ResponseField name="model" type="string">
  The LLM model ID used for generation
</ResponseField>

<ResponseField name="context_count" type="number">
  Number of context chunks retrieved (Search Mode). `0` in Direct AI Mode.
</ResponseField>

<ResponseField name="query" type="string">
  The original query submitted
</ResponseField>

<ResponseField name="used_context" type="boolean">
  Present when `structured_response` is enabled: whether RAG context was used.
</ResponseField>

<ResponseField name="structured_data" type="object">
  Parsed JSON when `structured_response.enabled` is `true`.
</ResponseField>

## Important Notes

* Search Mode requires a **text** namespace with indexed documents
* Direct AI Mode uses only LLM fields (`namespace`, `query`, `temperature`, `chat_history`, prompts, `ai_model`, `structured_response`)
* Configure LLM provider and default model with `moorcheh configure` or edit `~/.moorcheh/config.json`
* `/health` reports `llm_provider` and `llm_model` alongside embedding settings

## Related

* [Search](/on-prem/api-references/search/query)
* [Embedding providers](/on-prem/guides/embedding-providers)
* [CLI: moorcheh answer](/on-prem/cli/ai/generate)
* [Python: answer.generate()](/on-prem/python-client/ai/generate)