Chat completions

Chat completions are the core of SAGEA Studio — send a list of messages, get back a model reply you can render, speak, or pipe into tools.

In this guide

• Use system, user, assistant, and tool roles to steer behavior
• Choose between sage-2-4-actus, sage-2-5-celer, and sage-oss
• Tune temperature and max_tokens for factual vs creative tasks
• Trim multi-turn history without losing context

Shape conversations with roles

Every request is a list of messages. The system message sets the persona and ground rules, user messages carry new input, assistant messages preserve history, and tool messages return function results.

Use a Nepali-first system prompt for support bots so the model defaults to ne-NP while still handling English or Nepali-English code-switching.

curl -X POST https://api.sagea.space/v1/chat/completions \
  -H "Authorization: Bearer $SAGEA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sage-2-4-actus",
    "temperature": 0.2,
    "messages": [
      {"role": "system", "content": "तपाईं SAGEA का सहयोगी हौं। छोटो, विनम्र नेपालीमा उत्तर दिनुहोस्। ठेगाना सोधिएमा Kathmandu भित्रका शाखा सुझाव गर्नुहोस्।"},
      {"role": "user", "content": "मेरो पार्सल Baneshwor मा कहिले आइपुग्छ?"},
      {"role": "assistant", "content": "तपाईंको ट्र्याकिङ नम्बर दिनुहोस्, म जाँच गरिदिन्छु।"},
      {"role": "user", "content": "TRK-48291, भोलि चाहियो।"}
    ]
  }'

Keep the system prompt stable across turns. Put per-request facts — order IDs, branch names, user locale — in the latest user message or a tool message instead.

For full field schemas, see the Chat Completions reference.

Pick the right model

All three chat models share the same API shape, so you can switch with one string change.

Start with sage-2-4-actus for customer-facing Nepali bots. Move high-volume, simple turns to sage-2-5-celer once prompts are stable. Reach for sage-oss when you need a self-hostable fallback with the same message format.

Compare trade-offs in Choosing a model.

Tune temperature for the task

temperature controls randomness. Low values stick to the source material; high values explore phrasing and ideas.

# Factual lookup: keep it deterministic
response = client.chat.completions.create(
    model="sage-2-4-actus",
    temperature=0.2,
    max_tokens=300,
    messages=[{"role": "user", "content": "TRK-48291 कहाँ छ?"}],
)

Pair low temperature with retrieved context for RAG. Raise it only for explicitly creative endpoints or UI modes labeled "creative".

Budget tokens and trim history

max_tokens caps the reply, not the whole request. Input history plus max_tokens must fit the context window above. A Kathmandu support turn averages 400–800 tokens; set max_tokens to 300–600 for chat bubbles and higher only for summaries or letters.

Never grow messages forever. Keep the system prompt plus a sliding window of recent turns, and summarize anything evicted.

MAX_TURNS = 12
 
def trim_history(messages):
    # Always keep index 0 (system), keep last MAX_TURNS exchanges
    system, rest = messages[0], messages[1:]
    if len(rest) <= MAX_TURNS * 2:
        return messages
    summarized = {
        "role": "user",
        "content": "अघिल्लो कुराकानीको सार: प्रयोगकर्ताले TRK-48291 को डेलिभरी सोधे।",
    }
    return [system, summarized] + rest[-(MAX_TURNS * 2):]

Count tokens client-side before sending, and fall back from sage-2-4-actus to a summary call on sage-2-5-celer when a session runs long.

Best practices

• Write the system prompt in the language you want answered — Nepali in, Nepali out.
• Pin temperature to 0.2 for money, dates, and NPR amounts; use 0.9 only for creative modes.
• Set explicit max_tokens per surface: 300 for chat, 800 for email-length replies.
• Persist messages server-side so refreshes and retries keep continuity.
• Log model ID, token usage, and latency per turn to guide Actus vs Celer splits.

What's next

• Chat Completions reference
• Build an agent
• Choosing a model