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
Chat + response_format	Structured JSON (scores, arrays) for ranking/filtering	~1–5 per call	Structured Outputs
Chat + tools	Agentic loops; model calls your APIs	~1–5 per call + tools	Tool Calling
Focus Groups	N=25+ simulated respondents, Likert, NPS	~50–200 per run	Focus Groups
Video Analysis	Emotional, cognitive, behavioral metrics on video	Per analysis	Video Analysis
News Intelligence	Trending stories, persona sentiment on news	Per story/analysis	News Intelligence
Mave	Research, fact-check, multi-source, citations	Per request	Mave Agent
Chat + image	Vision scoring (images only)	~1–5 per call	Responses

---

Chat + Personas

Use when: You need persona-aware feedback on copy, messaging, or content. Single or short multi-turn.

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.

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.

# 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 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.

# 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.

# 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.

# 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.

# 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.

---

Responses API

Personas, structured outputs, tools

Video Analysis

Video metrics, chunk analysis

News Intelligence

Trending, persona analysis

Mave Agent

Research, fact-check, citations

Focus Groups

N=25+ simulated respondents

Persona Selection

Choose the right persona