> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mavera.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Mavera Surfaces & Patterns
> Reference for Chat, Focus Groups, Video Analysis, News Intelligence, Mave, structured outputs, and tool calling — choose the right surface for your use case
## Overview
Mavera offers **multiple surfaces** beyond Chat + personas. Each surface fits different use cases. Use this guide to pick the right one—and to combine them in agentic workflows.
**Don't default to Chat.** For video content, use Video Analysis. For news/PR, use News or Mave. For structured programmatic output, use `response_format`. For multi-step agentic flows, use tool calling.
***
## Surface Comparison
| Surface | Best For | Credits | Docs |
| --------------------------- | ------------------------------------------------------ | ---------------------- | ----------------------------------------------------------------- |
| **Chat + persona** | Single-turn copy scoring, persona POV | \~1–5 per call | [Responses](/features/responses) |
| **Chat + response\_format** | Structured JSON (scores, arrays) for ranking/filtering | \~1–5 per call | [Structured Outputs](/features/responses#structured-outputs) |
| **Chat + tools** | Agentic loops; model calls your APIs | \~1–5 per call + tools | [Tool Calling](/features/responses#tool-calling-function-calling) |
| **Focus Groups** | N=25+ simulated respondents, Likert, NPS | \~50–200 per run | [Focus Groups](/features/focus-groups) |
| **Video Analysis** | Emotional, cognitive, behavioral metrics on video | Per analysis | [Video Analysis](/features/video-analysis) |
| **News Intelligence** | Trending stories, persona sentiment on news | Per story/analysis | [News Intelligence](/features/news-intelligence) |
| **Mave** | Research, fact-check, multi-source, citations | Per request | [Mave Agent](/features/mave-agent) |
| **Chat + image** | Vision scoring (images only) | \~1–5 per call | [Responses](/features/responses) |
***
## Chat + Personas
**Use when:** You need persona-aware feedback on copy, messaging, or content. Single or short multi-turn.
```python theme={"dark"}
response = client.responses.create(
model="mavera-1",
input=[{"role": "user", "content": "Rate this headline 1-10"}],
extra_body={"persona_id": "YOUR_PERSONA_ID"},
)
```
***
## Chat + Structured Outputs (`response_format`)
**Use when:** You need **programmatic** output—scores, arrays, ranked items. Enables filtering, sorting, and downstream automation.
```python theme={"dark"}
response = client.responses.create(
model="mavera-1",
input=[{"role": "user", "content": "Score this email. Return JSON: score, issues[], clarity"}],
extra_body={
"persona_id": "YOUR_PERSONA_ID",
"response_format": {
"type": "json_schema",
"json_schema": {
"name": "email_score",
"strict": True,
"schema": {
"type": "object",
"properties": {
"score": {"type": "number"},
"issues": {"type": "array", "items": {"type": "string"}},
"clarity": {"type": "number"},
},
"required": ["score", "issues", "clarity"],
},
},
},
},
)
# Parse response.output[0].content[0].text or .parsed
```
***
## Chat + Tool Calling (Agentic Loops)
**Use when:** The workflow requires **multiple steps**—e.g. search CRM → enrich → score with persona. The model decides when to call tools.
```python theme={"dark"}
# 1. Define tools
tools = [
{
"type": "function",
"function": {
"name": "search_crm",
"description": "Search CRM for lead/account data",
"parameters": {"type": "object", "properties": {"query": {"type": "string"}}, "required": ["query"]},
},
},
{
"type": "function",
"function": {
"name": "score_messaging",
"description": "Score messaging with persona",
"parameters": {"type": "object", "properties": {"message": {"type": "string"}}, "required": ["message"]},
},
},
]
# 2. Call; if finish_reason == "tool_calls", execute tools and feed back
response = client.responses.create(
model="mavera-1",
input=[{"role": "user", "content": "Find our lead for Acme and score our last outreach"}],
extra_body={"persona_id": "YOUR_PERSONA_ID", "tools": tools},
)
# Loop: execute tool_calls, append results, call again until done
```
See [Tool Calling](/features/responses#tool-calling-function-calling) for the full loop pattern (execute tool → append result → call again until `finish_reason != "tool_calls"`).
***
## Focus Groups
**Use when:** You need **N=25+ simulated respondents**—feature naming, ad creative A/B, survey pre-test, ballot language. Returns aggregate scores and open-ended feedback.
```python theme={"dark"}
# POST /focus-groups or use SDK
# Run Likert: "Rate 1-10: How clear is this feature name?"
# Run open-ended: "What does this name make you think of?"
```
***
## Video Analysis
**Use when:** You're analyzing **video content**—ads, product demos, training videos. Returns emotional, cognitive, behavioral metrics and chunk-level breakdown. Supports chat about the analysis.
```python theme={"dark"}
# 1. Upload video via Files API
# 2. POST /video-analyses with asset_id, goal, brand
# 3. Poll until COMPLETED
# 4. Use results.chunks, results.full_video_metrics
# 5. Optional: POST /video-analyses/{id}/chat for Q&A about the analysis
```
***
## News Intelligence
**Use when:** You need **news monitoring** or **persona-based sentiment** on stories—competitive monitoring, PR impact, market sentiment.
```python theme={"dark"}
# GET /news/stories/trending?topics=technology,ai
# POST /news/stories/{id}/analyze with persona_ids → sentiment, key takeaways
# POST /news/stories/{id}/chat for natural-language Q&A
```
***
## Mave (Research Agent)
**Use when:** You need **multi-source research**, **fact-checking**, or **cited answers**—competitive landscape, press release validation, market research. Mave orchestrates search, news, and persona perspectives.
```python theme={"dark"}
# POST /mave/chat with message
# Returns: content, sources, thread_id for follow-up
```
***
## Combining Surfaces
**Example: Press release validation**
1. **Mave** — Fact-check claims against sources.
2. **Chat + persona** — Score tone with Journalist persona; `response_format` for structured feedback.
**Example: Ad creative pipeline**
1. **GPT/Image API** — Generate ad variants.
2. **Video Analysis** (if video) or **Chat + image** (if static) — Score emotional/behavioral metrics.
3. **Focus Group** — Run N=25 on top 5 for final ranking.
**Example: Agentic lead enrichment**
1. **Chat + tools** — Model calls `search_salesforce`, `mave_research`, `score_messaging` in a loop.
2. **response\_format** on final turn — Structured next-best-action.
***
Personas, structured outputs, tools
Video metrics, chunk analysis
Trending, persona analysis
Research, fact-check, citations
N=25+ simulated respondents
Choose the right persona