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

# Chat

> Chat completions with the Python SDK — basic, streaming, tools, structured output, vision, reasoning, and RAG.

`client.chat.create(...)` maps to [`POST /chat/request`](/api-reference/endpoint/chat/request). Non-streaming calls return the API JSON as a `dict`. Streaming calls return a `ChatCompletionStream` context manager.

## Basic chat (non-streaming)

```python theme={null}
from pawa_ai import PawaAI

client = PawaAI()

response = client.chat.create(
    model="pawa-v1-ember-20240924",
    messages=[
        {
            "role": "system",
            "content": [
                {
                    "type": "text",
                    "text": "You are a helpful assistant for developers in Africa.",
                }
            ],
        },
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Hello! How can I use AI in my app?"}
            ],
        },
    ],
    temperature=0.2,
    top_p=0.95,
    max_tokens=1024,
    stream=False,
)

print(response["success"])
print(response["data"]["request"][0]["message"]["content"])
print(response["data"].get("usage"))
```

`client.chat.completions(...)` is an alias for `create`.

## Streaming chat

Set `stream=True` and iterate token deltas as they arrive:

```python theme={null}
from pawa_ai import PawaAI

client = PawaAI()

with client.chat.create(
    model="pawa-v1-ember-20240924",
    messages=[
        {
            "role": "user",
            "content": [{"type": "text", "text": "Explain RAG in simple terms"}],
        }
    ],
    stream=True,
) as stream:
    for delta in stream.text_deltas():
        print(delta, end="", flush=True)

    completion = stream.collect()
    print(completion["data"]["request"][0]["message"]["content"])
```

## Vision (multimodal)

```python theme={null}
from pawa_ai import PawaAI

client = PawaAI()

response = client.chat.create(
    model="pawa-v1-blaze-20250318",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "What is in this image?"},
                {
                    "type": "image_url",
                    "image_url": {"url": "https://example.com/photo.jpg"},
                },
            ],
        }
    ],
    stream=False,
)

print(response["data"]["request"][0]["message"]["content"])
```

## Tools calling

### Built-in tools

```python theme={null}
from pawa_ai import PawaAI

client = PawaAI()

response = client.chat.create(
    model="pawa-v1-blaze-20250318",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Find the latest news about Pawa AI and summarize it.",
                }
            ],
        }
    ],
    tools=[
        {"type": "pawa_tool", "name": "web_search_tool"},
    ],
    stream=False,
)

print(response["data"]["request"][0]["message"]["content"])
```

### Custom tools (non-streaming)

```python theme={null}
from pawa_ai import PawaAI

client = PawaAI()

tools = [
    {
        "type": "function",
        "function": {
            "name": "convert_usd_to_tsh",
            "description": "Converts an amount in USD to Tanzanian Shillings.",
            "strict": True,
            "parameters": {
                "type": "object",
                "properties": {
                    "amount_usd": {
                        "type": "number",
                        "description": "Amount in USD",
                    }
                },
                "required": ["amount_usd"],
                "additionalProperties": False,
            },
        },
    }
]

messages = [
    {
        "role": "user",
        "content": [{"type": "text", "text": "Convert 45 USD to TSH"}],
    }
]

response = client.chat.create(
    model="pawa-v1-blaze-20250318",
    messages=messages,
    tools=tools,
    stream=False,
)

# Inspect tool_calls on the assistant message, run your function,
# then append a tool role message and call create() again for the final answer.
print(response)
```

<Note>
  When the model returns a tool call, the API does not stream the tool-call payload even if `stream=True`. Handle the tool result, then continue the conversation.
</Note>

## Structured output

Request JSON that matches a schema with `response_format`:

```python theme={null}
from pawa_ai import PawaAI

client = PawaAI()

response = client.chat.create(
    model="pawa-v1-ember-20240924",
    messages=[
        {
            "role": "system",
            "content": [
                {
                    "type": "text",
                    "text": "Extract resume information into structured JSON.",
                }
            ],
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": (
                        "Name: Jane Doe, Email: jane.doe@example.com, "
                        "Phone: +255 688067709, Education: B.Sc. Computer Science, UDSM, 2020, "
                        "Experience: Software Engineer at TechCorp (Jan 2021 – Dec 2023), "
                        "Skills: Python, JavaScript, AWS, Docker"
                    ),
                }
            ],
        },
    ],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "resume_schema",
            "strict": True,
            "schema": {
                "type": "object",
                "properties": {
                    "full_name": {"type": "string"},
                    "email": {"type": "string"},
                    "phone": {"type": "string"},
                    "education": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "institution": {"type": "string"},
                                "degree": {"type": "string"},
                                "graduation_year": {"type": "integer"},
                            },
                            "required": ["institution", "degree", "graduation_year"],
                        },
                    },
                    "experience": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "company": {"type": "string"},
                                "role": {"type": "string"},
                                "start_date": {"type": "string", "format": "date"},
                                "end_date": {"type": "string", "format": "date"},
                                "responsibilities": {
                                    "type": "array",
                                    "items": {"type": "string"},
                                },
                            },
                            "required": ["company", "role", "start_date", "end_date"],
                        },
                    },
                    "skills": {"type": "array", "items": {"type": "string"}},
                },
                "required": [
                    "full_name",
                    "email",
                    "phone",
                    "education",
                    "experience",
                    "skills",
                ],
                "additionalProperties": False,
            },
        },
    },
    stream=False,
)

import json

content = response["data"]["request"][0]["message"]["content"]
print(json.loads(content) if isinstance(content, str) else content)
```

### Structured output with streaming

```python theme={null}
from pawa_ai import PawaAI

client = PawaAI()

with client.chat.create(
    model="pawa-v1-ember-20240924",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Return a JSON object with keys city and country for Dar es Salaam.",
                }
            ],
        }
    ],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "place",
            "strict": True,
            "schema": {
                "type": "object",
                "properties": {
                    "city": {"type": "string"},
                    "country": {"type": "string"},
                },
                "required": ["city", "country"],
                "additionalProperties": False,
            },
        },
    },
    stream=True,
) as stream:
    for delta in stream.text_deltas():
        print(delta, end="", flush=True)
    print()
    print(stream.collect())
```

## Reasoning

```python theme={null}
from pawa_ai import PawaAI

client = PawaAI()

response = client.chat.create(
    model="pawa-v1-blaze-20250318",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Plan a 3-step approach to digitize receipts for a small shop.",
                }
            ],
        }
    ],
    reasoning={"effort": "medium"},
    stream=False,
)

print(response["data"]["request"][0]["message"]["content"])
```

## RAG with a knowledge base

```python theme={null}
from pawa_ai import PawaAI

client = PawaAI()

response = client.chat.create(
    model="pawa-v1-ember-20240924",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "What does our returns policy say about refunds?"}
            ],
        }
    ],
    rag={"knowledgeBaseId": 159, "topK": 5},
    stream=False,
)

print(response["data"]["request"][0]["message"]["content"])
```

## In-memory chat

Pass prior turns with `memoryChat` so the model has conversation context:

```python theme={null}
from pawa_ai import PawaAI

client = PawaAI()

response = client.chat.create(
    model="pawa-v1-ember-20240924",
    messages=[
        {
            "role": "user",
            "content": [{"type": "text", "text": "Remind me what I asked earlier."}],
        }
    ],
    memoryChat=[
        {
            "role": "user",
            "content": [{"type": "text", "text": "My shop is in Arusha."}],
        },
        {
            "role": "assistant",
            "content": [{"type": "text", "text": "Got it — your shop is in Arusha."}],
        },
    ],
    stream=False,
)

print(response["data"]["request"][0]["message"]["content"])
```