Configuration Guide

This guide explains all configuration options available in Reflexio. Configuration controls how profiles are extracted, playbooks are generated, and agent performance is evaluated.

Overview

Reflexio uses a centralized Config object that contains settings for:

• Storage - Where data is stored (local, Supabase, or PostgreSQL)
• LLM - API keys and model selection for LLM providers
• Profile Extraction, Playbooks & Evaluation - How user profiles are generated, playbooks are collected, and agent performance is measured

Getting and Setting Configuration

Configure Reflexio programmatically using the client when you want to override defaults. There are two ways to write config, depending on what you're changing:

• update_config — a partial (PATCH-style) update of one or more top-level fields. The server merges your changes into the existing config atomically, so you only send the fields you're changing. This is the recommended way to override a single default.
• get_config → set_config — fetch the full config, modify it, and send it back. Use this when you need to replace a nested object (e.g. an extractor config) wholesale.

Partial update (recommended)

Send only the top-level fields you want to change:

from reflexio import ReflexioClient

client = ReflexioClient()  # uses REFLEXIO_API_KEY env var
# Self-hosted: client = ReflexioClient(url_endpoint="http://localhost:8081")

# Override one or more top-level fields — no need to re-send the full config
client.update_config({"window_size": 20, "stride_size": 10})

curl -X POST "http://localhost:8081/api/update_config" \
  -H "User-Agent: my-agent-reflexio" \
  -H "Authorization: Bearer $REFLEXIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"window_size": 20, "stride_size": 10}'

Full / nested edits

Fetch the config, modify a nested object, and send the whole thing back:

from reflexio import ReflexioClient

client = ReflexioClient()  # uses REFLEXIO_API_KEY env var
# Self-hosted: client = ReflexioClient(url_endpoint="http://localhost:8081")

# Get current configuration
config = client.get_config()

# Modify a nested config object
config.profile_extractor_config = ...

# Save the full configuration
client.set_config(config)

curl -X GET "http://localhost:8081/api/get_config" \
  -H "User-Agent: my-agent-reflexio" \
  -H "Authorization: Bearer $REFLEXIO_API_KEY"

curl -X POST "http://localhost:8081/api/set_config" \
  -H "User-Agent: my-agent-reflexio" \
  -H "Authorization: Bearer $REFLEXIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "...": "updated full config object"
}
JSON

General Settings

Agent Context

Optionally provide global context about the agent's environment that should be shared across all extractors and evaluations.

config.agent_context_prompt = """
This agent is a customer service representative for an e-commerce platform.
The agent helps customers with:
- Product inquiries and recommendations
- Order tracking and status updates
- Returns and refunds
- Technical support for the website
"""

Extraction Window Configuration

Reflexio uses a sliding window to group interactions for extraction. This controls how many interactions are processed together and how frequently extraction runs.

config.window_size = 10  # Number of interactions per extraction
config.stride_size = 5  # New interactions before next extraction

Example: With window_size=10 and stride_size=5:

• First extraction processes interactions 1-10
• After 5 new interactions arrive, next extraction processes interactions 6-15
• After 5 more, next extraction processes interactions 11-20

Windows follow server admission order, independent of publish request boundaries and client timestamps. Hundreds of small publishes and one large publish produce the same windows for the same admitted interaction order and configuration. Each completed window advances a durable cursor; overlap supplies context without repeating an already completed window.

Eligible sources are combined within each project/user stream. Profile and playbook have independent cursors. Only one extraction runs for an organization/user at once, while other users and organizations run concurrently up to available worker capacity. Queued work stays in storage until capacity is available.

A first window requires window_size eligible interactions; later windows require stride_size new interactions, with 1 <= stride_size <= window_size. An incomplete tail waits for more input. force_extraction=True drains earlier full windows and flushes a partial window through that request's boundary. It does not absorb later requests. A window uses the extraction configuration captured when its first new interaction was admitted.

Temporary provider failures retain the existing fallback providers and retry with capped backoff. Saved successful output is reused after a storage failure. Catch-up requires sufficient sustained worker/provider capacity; a permanently failing provider cannot make progress.

Complete Configuration Example

from reflexio import ReflexioClient
from reflexio.models.config_schema import (
    Config,
    ProfileExtractorConfig,
    UserPlaybookExtractorConfig,
    PlaybookAggregatorConfig,
    AgentSuccessConfig,
    ToolUseConfig
)

client = ReflexioClient()  # see Quickstart for connection options

# Get current config (storage defaults to SQLite — no configuration needed)
config = client.get_config()

# Configure agent context
config.agent_context_prompt = """
Customer service agent for an online booking platform.
Helps users book hotels, flights, and activities.
"""

# Optional: customize profile extraction
config.profile_extractor_config = ProfileExtractorConfig(
    extraction_definition_prompt="""
    Extract: name, travel preferences, budget range,
    frequent destinations, loyalty program status
    """,
    context_prompt="Travel booking conversation",
    tagging_definition_prompt="category: 'traveler_profile'"
)

# Optional: customize playbook collection
config.user_playbook_extractor_config = UserPlaybookExtractorConfig(
    extraction_definition_prompt="""
    Was the booking process smooth? Any pain points?
    Did the agent provide helpful recommendations?
    """,
    aggregation_config=PlaybookAggregatorConfig(
        min_cluster_size=10,
        reaggregation_trigger_count=5
    )
)

# Configure tools the agent can use (shared across evaluation and extraction)
config.tool_can_use = [
    ToolUseConfig(
        tool_name="search_availability",
        tool_description="Search available options"
    ),
    ToolUseConfig(
        tool_name="create_reservation",
        tool_description="Create a new reservation"
    )
]

# Configure success evaluation (enabled by default at 5% sampling)
config.agent_success_config = AgentSuccessConfig(
    success_definition_prompt="""
    Success: Customer completed a booking or has clear next steps.
    Failure: Customer left confused, frustrated, or without resolution.
    """,
    sampling_rate=1.0
)

# Configure extraction windows
config.window_size = 20
config.stride_size = 10

# Save configuration
client.set_config(config)

curl -X GET "${REFLEXIO_URL:-https://www.reflexio.ai}/api/get_config" \
  -H "User-Agent: my-agent-reflexio" \
  -H "Authorization: Bearer $REFLEXIO_API_KEY"

curl -X POST "${REFLEXIO_URL:-https://www.reflexio.ai}/api/set_config" \
  -H "User-Agent: my-agent-reflexio" \
  -H "Authorization: Bearer $REFLEXIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "...": "updated full config object"
}
JSON

Best Practices

1. Start with the defaults - Publish real interactions before tuning profile_extractor_config or user_playbook_extractor_config

2. Customize prompts after review - Once you see real extracted profiles and playbooks, make prompt overrides specific. Vague prompts lead to inconsistent results

3. Review evaluation samples - Agent success evaluation is enabled by default with sampling_rate=0.05. Increase it for launches or audits, and lower it if you need tighter cost control

4. Monitor playbook thresholds - Set min_cluster_size high enough to get meaningful aggregations

5. Filter by source - Use request_sources_enabled to process only relevant interaction types

6. Iterate on definitions - Review extracted profiles and adjust prompts based on results

Next Steps

• Hosted Enterprise Get Started - connect to Reflexio at reflexio.ai
• Local OSS Get Started - run Reflexio on your machine
• API Reference - Complete method documentation