{
  "model": "gpt-4o",
  "messages": [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "What is the capital of France?"}
  ],
  "temperature": 0.7,
  "max_tokens": 256,
  "stream": false
}

{"model": "anthropic/claude-sonnet-4-6", ...}

{
  "model": "gpt-4o",
  "messages": [{
    "role": "user",
    "content": [
      {"type": "text", "text": "What is in this image?"},
      {"type": "image_url", "image_url": {"url": "data:image/png;base64,..."}}
    ]
  }]
}

{
  "type": "input_audio",
  "input_audio": {"data": "<base64>", "format": "mp3"}
}

{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "model": "gpt-4o",
  "choices": [{
    "index": 0,
    "message": {"role": "assistant", "content": "Paris."},
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 24,
    "completion_tokens": 3,
    "total_tokens": 27
  }
}

{
  "model": "claude-sonnet-4-6",
  "max_tokens": 1024,
  "system": "You are a helpful assistant.",
  "messages": [
    {"role": "user", "content": "Hello, Claude."}
  ]
}

{
  "role": "user",
  "content": [
    {"type": "image", "source": {"type": "base64", "media_type": "image/png", "data": "..."}},
    {"type": "text", "text": "Describe this image."}
  ]
}

{
  "type": "document",
  "source": {"type": "base64", "media_type": "application/pdf", "data": "..."}
}

{
  "model": "text-embedding-3-small",
  "input": "Your text here"
}

{
  "model": "text-embedding-3-small",
  "input": ["First sentence", "Second sentence"]
}

{
  "model": "tts-1",
  "input": "Hello, world.",
  "voice": "nova",
  "response_format": "mp3"
}

{
  "model": "dall-e-3",
  "prompt": "A futuristic city at sunrise",
  "n": 1,
  "size": "1024x1024",
  "quality": "hd",
  "style": "vivid",
  "response_format": "url"
}

{
  "model": "rerank-english-v3.0",
  "query": "What is the return policy?",
  "documents": ["Document one text.", "Document two text."],
  "top_n": 3
}

{
  "name": "production-chain",
  "targets": [
    {"provider": "openai",    "model": "gpt-4o",              "weight": 1},
    {"provider": "anthropic", "model": "claude-sonnet-4-6", "weight": 1},
    {"provider": "google",    "model": "gemini-1.5-pro",      "weight": 1}
  ],
  "retry_on": ["429", "500", "502", "503"],
  "max_retries": 2,
  "backoff_ms": 500
}

{
  "provider": "openai",
  "daily_budget_usd": 50.00
}

{
  "id": "github-tools",
  "name": "GitHub MCP Server",
  "base_url": "https://mcp.github.example.com",
  "auth_type": "bearer",
  "allowed_tools": ["list_repos", "create_issue"],
  "disallowed_tools": [],
  "cost_info": {"per_call_usd": 0.001},
  "guardrail_mode": "strict"
}

{
  "server_id": "github-tools",
  "user_id": "user-123",
  "justification": "Need to create issues for incident tracking.",
  "tools_requested": ["create_issue"]
}

{
  "spec": "<OpenAPI JSON or YAML string>",
  "server_id": "my-api",
  "server_name": "My REST API",
  "base_url": "https://api.example.com",
  "include_methods": ["GET", "POST"]
}

{
  "id": "task-uuid",
  "message": {
    "role": "user",
    "parts": [{"type": "text", "text": "Summarize the latest earnings report."}]
  }
}

{
  "name": "product-documentation",
  "description": "Internal product docs",
  "metadata": {"team": "engineering"}
}

{
  "id": "vs_abc123",
  "name": "product-documentation",
  "description": "Internal product docs",
  "file_count": 0,
  "created_at": 1740000000
}

{
  "content": "Full document text goes here...",
  "filename": "architecture.md",
  "metadata": {"version": "3.0"}
}

{
  "id": "vf_xyz789",
  "store_id": "vs_abc123",
  "filename": "architecture.md",
  "bytes": 4096,
  "status": "completed",
  "created_at": 1740000000
}

{
  "query": "How does the caching layer work?",
  "max_results": 5,
  "score_threshold": 0.7
}

{
  "results": [
    {
      "file_id": "vf_xyz789",
      "filename": "architecture.md",
      "content": "...relevant chunk text...",
      "score": 0.91
    }
  ],
  "total": 1
}

{
  "content": "Full document text...",
  "vector_store_id": "vs_abc123",
  "filename": "report-q4.txt",
  "chunk_size": 512,
  "chunk_overlap": 64,
  "metadata": {"source": "internal"}
}

{
  "store_id": "vs_abc123",
  "file_id": "vf_xyz789",
  "chunks_created": 12,
  "status": "completed"
}

{
  "query": "What were the Q4 revenue figures?",
  "vector_store_id": "vs_abc123",
  "max_results": 5,
  "score_threshold": 0.0,
  "include_context": true
}

{
  "chunks": [
    {"content": "...relevant chunk...", "score": 0.88, "file_id": "vf_xyz789", "filename": "report-q4.txt"}
  ],
  "context": "...relevant chunk... [additional chunks concatenated]",
  "total": 3
}

{
  "alias": "team-alpha",
  "budget_period": "monthly",
  "max_budget_usd": 100.00,
  "model_restrictions": ["gpt-4o", "claude-sonnet-4-6"],
  "rpm_limit": 60,
  "tpm_limit": 100000
}

{
  "provider": "openai",
  "duration_seconds": 600
}

{
  "success": true,
  "total": 50,
  "limit": 50,
  "offset": 0,
  "data": [
    {
      "request_id": "a1b2c3d4-...",
      "timestamp": "2026-03-13T20:12:51Z",
      "provider": "openai",
      "model": "gpt-4.1-mini-2025-04-14",
      "model_provider": "openai",
      "tokens_used": 29,
      "cost": 0.0000058,
      "latency_ms": 971,
      "processing_time_ms": 971,
      "content_type": "chat",
      "user_id": "user@example.com",
      "conversation_id": "conv-session-abc",
      "conversation_stage": "initial",
      "routing_strategy": "direct",
      "routing_reason": "provider:openai",
      "compliance_status": "compliant",
      "compliance_violations": null,
      "metacache": {
        "hit": false,
        "query": null,
        "tokens_saved": 0
      },
      "compliance": {
        "data_classification": "standard",
        "compliance_score": 1.0,
        "has_violations": false,
        "violations": [],
        "regulatory_frameworks": []
      },
      "metrics": {
        "prompt_tokens": 22,
        "completion_tokens": 7,
        "total_tokens": 29,
        "processing_time_ms": 971,
        "success": true
      }
    }
  ]
}

{
  "model": "gpt-4.1-mini",
  "latency_ms": 5,
  "routing_strategy": "cache",
  "routing_reason": "cache_hit:tier=L1",
  "metacache": {
    "hit": true,
    "query": "Explain TLS handshake",
    "tokens_saved": 209
  }
}

{
  "total_requests": 368,
  "success_rate": 100.0,
  "avg_latency_ms": 535,
  "total_tokens": 18240,
  "providers": ["openai", "anthropic"],
  "models": ["gpt-4.1-mini-2025-04-14", "claude-3-5-haiku-20241022"]
}

{
  "provider": "openai",
  "api_key": "sk-..."
}

{
  "content": "Text to scan",
  "policy": "enterprise_standard",
  "user_id": "user-123",
  "org_id": "acme"
}

{
  "has_violations": false,
  "compliance_score": 0.97,
  "risk_level": "low",
  "recommended_action": "Allow",
  "violations": [],
  "pii_detected": [],
  "redacted_content": null
}

{
  "risk_score": 0.12,
  "risk_level": "low",
  "recommended_action": "Allow",
  "violations": [],
  "explanation": "Content is within organizational policy."
}

{
  "scan_id": "scan-xyz",
  "correct_action": "Allow",
  "correct_risk_level": "low",
  "notes": "False positive — internal terminology"
}

{"content": "Call me at 555-867-5309, email john@example.com"}

{
  "total_policies": 42,
  "total_presets": 8,
  "total_applications": 1204,
  "compliance_violations": 3
}

{
  "name": "HIPAA PHI Protection",
  "description": "Prevent transmission of protected health information",
  "policy_type": "compliance",
  "content": "Do not include patient names, diagnoses, medical record numbers, or any PHI in AI responses.",
  "priority": 90,
  "applicable_providers": ["all"],
  "applicable_models": ["all"],
  "regulatory_framework": "HIPAA",
  "severity": "critical",
  "metadata": {
    "departments": ["clinical", "billing"],
    "ad_groups": ["clinicians", "admins"]
  }
}

{
  "name": "Healthcare Standard",
  "description": "Default policy set for all clinical staff",
  "use_case": "Clinical AI assistant",
  "policy_ids": ["pol_hipaa_phi", "pol_brand_tone", "pol_no_diagnosis"]
}

{
  "success": true,
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "message": "Document processing started."
}

{
  "success": true,
  "job": {
    "id": "550e8400-...",
    "filename": "hipaa-policy-handbook.pdf",
    "status": "processing",
    "progress_pct": 62,
    "created_at": "2026-02-19T10:00:00Z"
  }
}

{
  "success": true,
  "job_id": "550e8400-...",
  "filename": "hipaa-policy-handbook.pdf",
  "total_policies": 7,
  "suggested_policies": [
    {
      "id": "sugg_abc",
      "name": "Minimum Necessary Standard",
      "type": "compliance",
      "content": "Limit PHI access and disclosure to the minimum necessary...",
      "priority": 85,
      "regulatory_framework": "HIPAA",
      "confidence": 0.94
    }
  ]
}

pip install smartflow-sdk

pip install git+https://github.com/SRAGroupTX/SmartflowV3.git#subdirectory=sdk/python

class SmartflowClient(
    base_url: str,
    api_key: Optional[str] = None,
    timeout: float = 30.0,
    management_port: int = 7778,
    compliance_port: int = 7777,
    bridge_port: int = 3500,
)

from smartflow import SmartflowClient

async with SmartflowClient("https://smartflow.example.com", api_key="sk-sf-...") as sf:
    reply = await sf.chat("What is the capital of France?")
    print(reply)

sf = SmartflowClient("https://smartflow.example.com")
await sf._ensure_client()
reply = await sf.chat("Hello!")
await sf.close()

async def chat(
    message: str,
    model: str = "gpt-4o",
    system_prompt: Optional[str] = None,
    temperature: float = 0.7,
    max_tokens: Optional[int] = None,
    **kwargs,
) -> str

reply = await sf.chat("Summarise this in one sentence.", model="claude-sonnet-4-6")

async def chat_completions(
    messages: List[Dict[str, str]],
    model: str = "gpt-4o",
    temperature: float = 0.7,
    max_tokens: Optional[int] = None,
    stream: bool = False,
    **kwargs,
) -> AIResponse

response = await sf.chat_completions(
    messages=[
        {"role": "system", "content": "You are a concise assistant."},
        {"role": "user", "content": "What is 2 + 2?"},
    ],
    model="gpt-4o-mini",
    max_tokens=50,
)
print(response.content)
print(response.usage.total_tokens)

async def stream_chat(
    message: str,
    model: str = "gpt-4o",
    system_prompt: Optional[str] = None,
    temperature: float = 0.7,
    max_tokens: Optional[int] = None,
    **kwargs,
) -> AsyncIterator[str]

async for chunk in sf.stream_chat("Tell me a story about a robot"):
    print(chunk, end="", flush=True)

async def embeddings(
    input: Union[str, List[str]],
    model: str = "text-embedding-3-small",
    encoding_format: str = "float",
    dimensions: Optional[int] = None,
    input_type: Optional[str] = None,
    **kwargs,
) -> Dict[str, Any]

result = await sf.embeddings("Hello world", model="text-embedding-3-small")
vector = result["data"][0]["embedding"]

# Cohere
result = await sf.embeddings(
    ["doc one", "doc two"],
    model="cohere/embed-english-v3.0",
    input_type="search_document",
)

# Reduce dimensions
result = await sf.embeddings("Hello", model="text-embedding-3-large", dimensions=256)

async def image_generation(
    prompt: str,
    model: str = "dall-e-3",
    n: int = 1,
    size: str = "1024x1024",
    quality: Optional[str] = None,
    response_format: str = "url",
    style: Optional[str] = None,
    **kwargs,
) -> Dict[str, Any]

result = await sf.image_generation(
    "A mountain landscape at dawn",
    model="dall-e-3",
    size="1792x1024",
    quality="hd",
)
print(result["data"][0]["url"])

async def audio_transcription(
    file: BinaryIO,
    model: str = "whisper-1",
    language: Optional[str] = None,
    prompt: Optional[str] = None,
    response_format: str = "json",
    temperature: float = 0.0,
    **kwargs,
) -> Dict[str, Any]

with open("recording.mp3", "rb") as f:
    result = await sf.audio_transcription(f, model="whisper-1")
print(result["text"])

# Groq Whisper (faster, same format)
with open("recording.mp3", "rb") as f:
    result = await sf.audio_transcription(f, model="groq/whisper-large-v3")

async def text_to_speech(
    input: str,
    model: str = "tts-1",
    voice: str = "alloy",
    response_format: str = "mp3",
    speed: float = 1.0,
    **kwargs,
) -> bytes

audio = await sf.text_to_speech("Hello, this is Smartflow.", voice="nova")
with open("output.mp3", "wb") as f:
    f.write(audio)

async def rerank(
    query: str,
    documents: List[str],
    model: str = "rerank-english-v3.0",
    top_n: Optional[int] = None,
    **kwargs,
) -> Dict[str, Any]

result = await sf.rerank(
    "What is the return policy?",
    ["We accept returns within 30 days.", "Contact us at support@example.com."],
    top_n=1,
)

async def list_models() -> List[Dict[str, Any]]

async def claude_message(
    message: str,
    model: str = "claude-sonnet-4-6",
    max_tokens: int = 1024,
    system: Optional[str] = None,
    anthropic_key: Optional[str] = None,
) -> str

reply = await sf.claude_message(
    "Summarise this contract in three bullet points.",
    model="claude-sonnet-4-6",
    system="You are a legal assistant.",
    max_tokens=512,
)

async def chatbot_query(query: str) -> Dict[str, Any]

result = await sf.chatbot_query("show me today's cache stats")
print(result["response"])

result = await sf.chatbot_query("which provider had the most errors this week?")

# OpenAI
reply = await sf.chat("Hello", model="gpt-4o")
reply = await sf.chat("Hello", model="gpt-4o-mini")
reply = await sf.chat("Hello", model="o3-mini")

# Anthropic — via model-name heuristic (no prefix needed)
reply = await sf.chat("Hello", model="claude-sonnet-4-6")
reply = await sf.chat("Hello", model="claude-3-opus-20240229")

# Google Gemini — via model-name heuristic
reply = await sf.chat("Hello", model="gemini-1.5-pro")
reply = await sf.chat("Hello", model="gemini-2.0-flash")

# xAI Grok — explicit prefix required
reply = await sf.chat("Hello", model="xai/grok-2-latest")

# Mistral — explicit prefix
reply = await sf.chat("Hello", model="mistral/mistral-large-latest")

# Cohere — explicit prefix
reply = await sf.chat("Hello", model="cohere/command-r-plus")

# Groq (fast Llama inference)
reply = await sf.chat("Hello", model="groq/llama-3.1-70b-versatile")

# OpenRouter (access 200+ models through one key)
reply = await sf.chat("Hello", model="openrouter/meta-llama/llama-3.1-405b")

# Local Ollama
reply = await sf.chat("Hello", model="ollama/llama3.2")

# Azure OpenAI — deployment name as suffix
reply = await sf.chat("Hello", model="azure/my-gpt4o-deployment")

# Force native Anthropic path (uses /anthropic/v1/messages)
reply = await sf.claude_message("Hello", model="claude-sonnet-4-6")

import httpx

# Call an MCP tool via the proxy
async with httpx.AsyncClient() as client:
    response = await client.post(
        "https://smartflow.example.com/github-tools/mcp/",
        headers={
            "Authorization": "Bearer sk-sf-...",
            "Content-Type": "application/json",
        },
        json={
            "jsonrpc": "2.0",
            "id": 1,
            "method": "tools/call",
            "params": {
                "name": "create_issue",
                "arguments": {
                    "repo": "my-org/my-repo",
                    "title": "Bug: login fails on mobile",
                    "body": "Steps to reproduce..."
                }
            }
        }
    )
    result = response.json()
    print(result["result"]["content"])

import httpx

async with httpx.AsyncClient() as client:
    # Find tools matching a natural-language query
    r = await client.get(
        "https://smartflow.example.com/api/mcp/tools/search",
        params={"q": "create github issue", "k": 3},
        headers={"Authorization": "Bearer sk-sf-..."},
    )
    tools = r.json()["results"]
    for t in tools:
        print(f"{t['server_id']}.{t['name']}: {t['description']}")

import httpx

# Send a task to a registered A2A agent
async with httpx.AsyncClient() as client:
    response = await client.post(
        "https://smartflow.example.com/a2a/summarizer-agent",
        headers={
            "Authorization": "Bearer sk-sf-...",
            "Content-Type": "application/json",
            "x-a2a-trace-id": "trace-abc-123",   # optional: for cross-agent correlation
        },
        json={
            "id": "task-uuid-001",
            "message": {
                "role": "user",
                "parts": [{"type": "text", "text": "Summarise the attached earnings report."}]
            }
        }
    )
    result = response.json()
    print(result["result"]["parts"][0]["text"])

r = await client.get(
    "https://smartflow.example.com/a2a/summarizer-agent/.well-known/agent.json",
    headers={"Authorization": "Bearer sk-sf-..."},
)
card = r.json()
print(card["capabilities"])

async def check_compliance(
    content: str,
    policy: str = "enterprise_standard",
    user_id: Optional[str] = None,
    org_id: Optional[str] = None,
) -> ComplianceResult

result = await sf.check_compliance("User message text", policy="hipaa")
if result.has_violations:
    print(result.violations)

async def intelligent_scan(
    content: str,
    user_id: Optional[str] = None,
    org_id: Optional[str] = None,
    context: Optional[str] = None,
) -> IntelligentScanResult

result = await sf.intelligent_scan(
    "My SSN is 123-45-6789",
    user_id="user-123",
    org_id="acme-corp",
    context="customer_support",
)
print(f"{result.risk_level}: {result.recommended_action}")
# "high: Block"

async def redact_pii(content: str) -> str

clean = await sf.redact_pii("My SSN is 123-45-6789, email me at john@example.com")
# "My SSN is [SSN], email me at [EMAIL]"

async def submit_compliance_feedback(
    scan_id: str,
    is_false_positive: bool,
    user_id: Optional[str] = None,
    notes: Optional[str] = None,
) -> Dict[str, Any]

await sf.submit_compliance_feedback(
    scan_id="scan-xyz",
    is_false_positive=True,
    notes="This was a test phone number, not real PII",
)

async def get_learning_status(user_id: str) -> LearningStatus

async def get_learning_summary() -> LearningSummary

async def get_ml_stats() -> MLStats

async def get_org_summary() -> Dict[str, Any]

async def get_org_baseline(org_id: str) -> OrgBaseline

baseline = await sf.get_org_baseline("acme-corp")

async def get_persistence_stats() -> PersistenceStats

async def save_compliance_data() -> Dict[str, Any]

async def get_intelligent_health() -> Dict[str, Any]

async def health() -> Dict[str, Any]

async def health_comprehensive() -> SystemHealth

h = await sf.health_comprehensive()
print(h.overall_status)          # "healthy"
print(h.redis_connected)         # True
print(h.providers_available)     # ["openai", "anthropic", "google"]

async def get_provider_health() -> List[ProviderHealth]

async def get_cache_stats() -> CacheStats

stats = await sf.get_cache_stats()
print(f"Hit rate:     {stats.hit_rate:.1%}")
print(f"Tokens saved: {stats.tokens_saved:,}")
print(f"Cost saved:   ${stats.cost_saved_usd:.4f}")
print(f"L1/L2/L3:     {stats.l1_hits} / {stats.l2_hits} / {stats.l3_hits}")

async def get_logs(
    limit: int = 50,
    provider: Optional[str] = None,
) -> List[VASLog]

async def get_logs_hybrid(limit: int = 100) -> List[Dict[str, Any]]

all_logs = await sf.get_logs_hybrid(limit=500)
for log in all_logs:
    print(f"{log['timestamp']} | {log['provider']} | {log['model']}")

async def get_analytics(period: str = "7d") -> Dict[str, Any]

async def get_routing_status() -> Dict[str, Any]

async def force_provider(
    provider: str,
    duration_seconds: int = 300,
) -> Dict[str, Any]

class SmartflowAgent(
    client: SmartflowClient,
    name: str = "SmartflowAgent",
    model: str = "gpt-4o",
    system_prompt: Optional[str] = None,
    temperature: float = 0.7,
    max_tokens: Optional[int] = None,
    compliance_policy: str = "enterprise_standard",
    enable_compliance_scan: bool = True,
    user_id: Optional[str] = None,
    org_id: Optional[str] = None,
    tools: Optional[List[Dict]] = None,
)

async with SmartflowClient("https://smartflow.example.com", api_key="sk-...") as sf:
    agent = SmartflowAgent(
        client=sf,
        name="SupportBot",
        model="gpt-4o",
        system_prompt="You are a helpful customer support agent.",
        user_id="user-123",
        org_id="acme",
    )
    r1 = await agent.chat("How do I reset my password?")
    r2 = await agent.chat("What if I forgot my email too?")

    print(agent.message_count)
    agent.clear_history()

workflow = SmartflowWorkflow(client, name="TicketFlow")

workflow \
    .add_step("classify", action="chat",
              config={"prompt": "Classify this ticket: {input}", "model": "gpt-4o-mini"}) \
    .add_step("check", action="compliance_check",
              config={"content": "{output}"}) \
    .add_step("route", action="condition",
              config={"field": "output", "cases": {"billing": "billing_step"}, "default": "general_step"})

result = await workflow.execute({"input": ticket_text})
print(result.output)
print(result.steps_executed)
print(result.execution_time_ms)

from smartflow import SyncSmartflowClient

sf = SyncSmartflowClient("https://smartflow.example.com", api_key="sk-...")

reply      = sf.chat("Hello!")
emb        = sf.embeddings("Hello", model="text-embedding-3-small")
img        = sf.image_generation("A sunset", model="dall-e-3")
transcript = sf.audio_transcription(open("audio.mp3", "rb"), model="whisper-1")
audio      = sf.text_to_speech("Hello!", voice="nova")
ranked     = sf.rerank("What is the return policy?", ["doc1", "doc2"])

pip install nest_asyncio

import nest_asyncio
nest_asyncio.apply()

from openai import OpenAI

client = OpenAI(
    api_key="sk-sf-your-virtual-key",
    base_url="https://smartflow.example.com/v1"
)

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello!"}]
)

from smartflow import ComplianceError, RateLimitError
import asyncio

try:
    result = await sf.chat("sensitive message")
except ComplianceError as e:
    print(f"Blocked by policy: {e}")
except RateLimitError:
    await asyncio.sleep(60)
    # retry