Skip to main content

​
TL;DR

  • Artifacts CLI: Unified command suite for managing all Synth AI artifacts
  • In-Process Task App Utility: Automatic server and tunnel management
  • Experiment Queue System: Redis-based queue with Celery workers
  • Task App Discovery: Multi-method discovery and health checking via synth-ai scan
  • Session-Based Pricing: Comprehensive usage tracking and budget enforcement
  • Cloudflare Tunnel Support: Quick tunnels and managed tunnels for task app deployment
  • First-Class Codex Support: Synth models now work seamlessly with Codex CLI workflows

​
Artifacts CLI

New synth-ai artifacts command suite for managing and inspecting all Synth AI artifacts.

​
Key Features

  • List Artifacts: artifacts list displays all fine-tuned models, RL models, and optimized prompts with filtering options
  • Show Details: artifacts show provides detailed information about specific artifacts, with intelligent prompt extraction
  • Export Models: artifacts export exports models to HuggingFace Hub (private or public)
  • Download Prompts: artifacts download downloads optimized prompts in JSON, YAML, or text formats
  • Smart ID Parsing: Centralized parsing logic handles all artifact ID formats (ft:, rl:, peft:, pl_)
  • Best Prompt Display: Default view shows job summary + best optimized prompt with syntax highlighting
  • Verbose Mode: --verbose flag shows full metadata and snapshot details for prompts
  • JSON Export: --format json enables easy scripting and data export

​
Prompt Extraction Intelligence

  • Multi-Structure Support: Automatically extracts prompt messages from various snapshot structures
  • Syntax Highlighting: Rich formatting with role-based colors (system/user/assistant)
  • Default View: Shows only the most important information (summary + best prompt)
  • Verbose View: Full metadata and snapshot details when needed

​
In-Process Task App Utility

New InProcessTaskApp utility enables running task apps entirely within your Python script.

​
Features

  • Automatic Server & Tunnel Management: Automatically starts uvicorn server in background thread
  • Automatic Tunnel Creation: Opens Cloudflare quick tunnel automatically and provides tunnel URL
  • Port Conflict Handling: Automatically finds available ports if requested port is busy
  • Multiple Input Methods: Supports FastAPI app instance, TaskAppConfig object, config factory function, or task app file path
  • Signal Handling: Graceful shutdown on SIGINT/SIGTERM prevents orphaned processes
  • Observability: Structured logging and optional on_start/on_stop callbacks

​
Experiment Queue System

New experiment queue system with Redis backend and Celery workers.

​
Queue Worker Management (synth-ai queue)

  • Start Worker: synth-ai queue start launches a background Celery worker with Beat scheduler
  • Stop Worker: synth-ai queue stop terminates all running experiment queue workers
  • Status Check: synth-ai queue status displays current worker status and configuration
  • Single Worker Enforcement: Automatically kills existing workers before starting new ones
  • Beat Scheduler: Integrated Celery Beat runs periodic queue checks every 5 seconds

​
Experiment Submission (synth-ai experiment)

  • Submit Experiments: synth-ai experiment submit accepts JSON payloads to create new experiments
  • Job Validation: Validates config files and environment files before submission
  • Automatic Dispatch: Initial jobs are dispatched immediately upon submission
  • Parallelism Control: Configure how many jobs run concurrently per experiment
  • Watch Mode: Continuous refresh with --watch flag for real-time monitoring

​
Redis-Based Queue Backend

  • Migrated from SQLite: Eliminates SQLite locking conflicts that prevented job dispatch
  • Concurrent Access: Supports multiple workers and concurrent job processing
  • Default Configuration: Uses redis://localhost:6379/0 for broker and redis://localhost:6379/1 for result backend

​
Task App Discovery (synth-ai scan)

New command to discover and health-check running task applications.

​
Discovery Methods

  • Port Scanning: Scans ports 8000-8100 by default
  • Service Records: Automatically discovers apps deployed via synth-ai deploy --runtime local
  • Tunnel Discovery: Discovers Cloudflare tunnels deployed via synth-ai deploy --runtime tunnel
  • Process Scanning: Inspects running cloudflared processes to find tunnel URLs
  • Backend API: Queries backend API for managed tunnels
  • Registry Queries: Checks environment registry for registered apps

​
Health Checks

  • Performs HTTP health checks on /health endpoints
  • Extracts metadata from /info endpoints
  • Supports both human-readable table format and machine-readable JSON format
  • API key authentication support via X-API-Key header

​
Session-Based Pricing & Budget Enforcement

Comprehensive session-based usage tracking and budget enforcement for cost-incurring API requests.

​
Session Management

  • Single Active Session: Only one active session per organization/user at a time, automatically managed
  • Automatic Session Attachment: All cost-incurring requests automatically attach to the active session unless explicitly opted out
  • Budget Enforcement: Requests are rejected with 429 when session limits are exceeded (tokens, cost, GPU hours)
  • Opt-Out Support: Set X-No-Session: true header to skip session tracking for specific requests
  • Session Lifecycle: Sessions have explicit beginning, active period, and end states
  • TOML Configuration: CLI commands (codex, opencode) support TOML config files with session limits (default: $20 cost limit)

​
Protected Routes

All cost-incurring routes enforce session budgets:
  • /api/v1/responses (all variants)
  • /api/synth-research/chat/completions
  • /api/v1/responses/{resp_id}/submit_tool_outputs

​
Cloudflare Tunnel Support

Added support for deploying task apps via Cloudflare Tunnel.

​
Quick Tunnels

  • Free, ephemeral tunnels (no account required) perfect for development and testing
  • Background mode by default, returns immediately after deployment
  • Automatic health check polling ensures task app is ready before tunnel opens

​
Managed Tunnels

  • Stable tunnels with custom subdomains (e.g., my-company.usesynth.ai) for production use
  • Requires SYNTH_API_KEY and backend provisioning (coming soon)
  • Seamless integration with RL training and prompt optimization (GEPA/MIPRO)

​
First-Class Codex Support for Synth Models

Added first-class support for synth-small, synth-medium, and synth-experimental models in Codex CLI workflows.

​
Responses API Integration

  • Full Responses API format support with proper conversion to/from Chat Completions format
  • Complete tool call processing with proper event sequencing, argument streaming, and output handling
  • Stop Tool: Added __internal_stop tool to signal completion and prevent infinite loops
  • Stream Completion: Reliable stream completion signals with proper response.completed events

​
Technical Improvements

  • Responses API Bridge: Comprehensive Responses API → Chat Completions → Responses API conversion layer
  • Event Translation: Full SSE event translation between Responses and Chat formats
  • Comprehensive Testing: Added 32 integration tests covering all critical Responses API behavior

​
Documentation

  • CLI Documentation: Complete documentation for synth-ai artifacts, synth-ai queue, synth-ai experiment, and synth-ai scan commands
  • SDK Documentation: Complete SDK reference page at /sdk/in-process-task-app
  • Deployment Guide: Updated CLI documentation with Cloudflare Tunnel deployment examples

​
Use Cases

  • Artifact Discovery: Quickly find and inspect all your trained models and optimized prompts
  • Local Development: Run prompt optimization without separate terminal processes
  • Batch Processing: Submit multiple experiments and let the queue process them automatically
  • Budget Control: Enforce spending limits per session to prevent unexpected costs
  • Development Workflows: Use quick tunnels for local testing without production infrastructure