Skip to main content

​
synth_ai.sdk.optimization.policy.mipro_online_session

MIPRO online session SDK wrapper. This module provides the MiproOnlineSession class for managing online MIPRO optimization sessions. In online mode, you drive rollouts locally while the backend provides prompt candidates through proxy URLs. Online MIPRO workflow:
  1. Create a session with your MIPRO configuration
  2. Get proxy URLs for prompt selection
  3. Run rollouts locally, calling the proxy URL for each LLM call
  4. Report rewards back to the session
  5. Backend generates new prompt proposals based on rewards
Example: 
>>> from synth_ai.sdk.optimization.policy import MiproOnlineSession
>>>
>>> # Create session
>>> session = MiproOnlineSession.create(
...     config_path="mipro_config.toml",
...     api_key=os.environ["SYNTH_API_KEY"]
... )
>>>
>>> # Get proxy URL for prompt selection
>>> urls = session.get_prompt_urls()
>>> proxy_url = urls["online_url"]
>>>
>>> # Run rollout: call proxy_url with your task input
>>> # Proxy selects best prompt candidate and returns LLM response
>>>
>>> # Report reward
>>> session.update_reward(reward_info={"score": 0.85})

​
Lever/Sensor Integration

Online MIPRO sessions emit canonical lever/sensor outputs through status and result APIs:
  • lever_summary: prompt lever id + per-candidate lever version lineage.
  • lever_versions: resolved lever versions for the selected/best candidate.
  • best_lever_version: scalar best lever version.
  • sensor_frames: summarized rollout telemetry grouped into sensor frames.
These fields are normalized into SDK result models (PolicyOptimizationResult and PromptLearningResult), including typed helpers:
  • lever_summary_typed
  • sensor_frame_summaries_typed

​
Classes

​
MiproOnlineSession

Client wrapper for online MIPRO optimization sessions. Manages a single MIPRO online optimization session. In online mode, you control the rollout loop locally while the backend provides prompt candidates through proxy URLs. This allows real-time prompt evolution as you report rewards. Key features:
  • Proxy URLs: Backend provides URLs that select prompt candidates
  • Reward reporting: Report rewards after each rollout
  • Session management: Pause, resume, or cancel optimization
  • Real-time evolution: Prompts evolve as rewards are reported
Attributes:
  • session_id: Unique session identifier
  • backend_url: Backend API base URL
  • api_key: Synth API key for authentication
  • correlation_id: Optional correlation ID for tracking
  • proxy_url: Proxy URL for prompt selection (deprecated, use online_url)
  • online_url: Stable proxy URL for prompt selection
  • chat_completions_url: URL for chat completions endpoint
  • timeout: HTTP request timeout in seconds
Methods:

​
create_async

create_async(cls) -> MiproOnlineSession
Create a new online MIPRO session (async). Creates a new MIPRO online optimization session. The session provides proxy URLs that select prompt candidates for your rollouts. Args:
  • backend_url: Backend API URL (defaults to production)
  • api_key: Synth API key (defaults to SYNTH_API_KEY env var)
  • config: MIPRO config dict, file path, or Path object
  • config_name: Name of config to load from backend
  • config_path: Path to TOML config file
  • config_body: Config dictionary
  • overrides: Config overrides to apply
  • metadata: Optional session metadata
  • session_id: Optional session ID (for resuming)
  • correlation_id: Optional correlation ID for tracking
  • agent_id: Optional agent ID (used as correlation_id if provided)
  • timeout: HTTP request timeout in seconds
Returns:
  • MiproOnlineSession instance with proxy URLs populated
Raises:
  • ValueError: If config is invalid or response is malformed
  • FileNotFoundError: If config_path doesn’t exist

​
create

create(cls) -> MiproOnlineSession
Create a new online MIPRO session (synchronous wrapper). Synchronous wrapper around create_async. See create_async for detailed parameter documentation. Returns:
  • MiproOnlineSession instance

​
get_online_url_async

get_online_url_async(cls, session_id: str) -> str
Fetch the stable online URL for a session (async). Retrieves the proxy URL for prompt selection without creating a full session object. Useful for resuming sessions or getting URLs independently. Args:
  • session_id: Existing session ID
  • backend_url: Backend API URL (defaults to production)
  • api_key: Synth API key (defaults to SYNTH_API_KEY env var)
  • correlation_id: Optional correlation ID
  • timeout: HTTP request timeout in seconds
Returns:
  • Proxy URL string for prompt selection
Raises:
  • ValueError: If response is invalid or missing online_url

​
get_online_url

get_online_url(cls, session_id: str) -> str
Fetch the stable online URL for a session (synchronous wrapper). Synchronous wrapper around get_online_url_async. See that method for detailed parameter documentation. Returns:
  • Proxy URL string for prompt selection

​
status_async

status_async(self) -> Dict[str, Any]
Get current session status (async). Retrieves the current status of the MIPRO session including optimization progress, current candidates, and session metadata. Returns:
  • Dictionary with session status information

​
status

status(self) -> Dict[str, Any]
Get current session status (synchronous wrapper). Synchronous wrapper around status_async. Returns:
  • Dictionary with session status information

​
pause

pause(self) -> Dict[str, Any]
Pause the optimization session. Temporarily pauses prompt proposal generation. Rollouts can continue but no new proposals will be generated until resumed. Returns:
  • Dictionary with pause status

​
resume

resume(self) -> Dict[str, Any]
Resume a paused optimization session. Resumes prompt proposal generation after a pause. Returns:
  • Dictionary with resume status

​
cancel

cancel(self) -> Dict[str, Any]
Cancel the optimization session. Permanently cancels the session. No further proposals will be generated and the session cannot be resumed. Returns:
  • Dictionary with cancellation status

​
update_reward_async

update_reward_async(self) -> Dict[str, Any]
Report reward for a rollout (async). Reports the reward/score for a completed rollout. This feedback is used by the backend to generate new prompt proposals. Call this after each rollout completes. Args:
  • reward_info: Reward information (must include “score” key)
  • artifact: Optional artifact data from the rollout
  • metadata: Optional metadata about the rollout
  • correlation_id: Optional correlation ID (overrides session default)
  • rollout_id: Optional rollout identifier
  • candidate_id: Optional candidate prompt identifier
  • trace_ref: Optional trace reference
  • stop: Optional flag to stop optimization
Returns:
  • Dictionary with reward acknowledgment

​
update_reward

update_reward(self) -> Dict[str, Any]
Report reward for a rollout (synchronous wrapper). Synchronous wrapper around update_reward_async. See that method for detailed parameter documentation. Returns:
  • Dictionary with reward acknowledgment

​
get_prompt_urls_async

get_prompt_urls_async(self) -> Dict[str, Any]
Get proxy URLs for prompt selection (async). Retrieves the proxy URLs that select prompt candidates for your rollouts. These URLs should be called with your task inputs - the backend will select the best prompt candidate and return the LLM response. Args:
  • correlation_id: Optional correlation ID (overrides session default)
Returns:
  • Dictionary with “online_url” and optionally “chat_completions_url”

​
get_prompt_urls

get_prompt_urls(self) -> Dict[str, Any]
Get proxy URLs for prompt selection (synchronous wrapper). Synchronous wrapper around get_prompt_urls_async. See that method for detailed parameter documentation. Returns:
  • Dictionary with proxy URLs