steer-sdk 0.1.8__py3-none-any.whl

steer/__init__.py

@@ -0,0 +1,13 @@
+from .core import capture
+from .storage import rulebook
+from .utils import wait_for_rules
+from .mock import MockLLM  # <--- NEW
+
+__version__ = "0.1.3"
+
+def get_context(agent_name: str) -> str:
+    rules = rulebook.get_rules_text(agent_name)
+    if not rules: return ""
+    return f"\n\n### STEER RELIABILITY RULES:\n{rules}\n"
+
+__all__ = ["capture", "get_context", "wait_for_rules", "MockLLM"]

steer/cli.py

@@ -0,0 +1,149 @@
+import sys
+import uvicorn
+import webbrowser
+import argparse
+import os
+from rich.console import Console
+from steer.server import app
+
+console = Console()
+
+# --- DEMO 1: USER PROFILE AGENT ---
+DEMO_1_CONTENT = """import json
+from steer import capture, MockLLM
+from steer.verifiers import JsonVerifier
+
+# Scenario: An agent generating data for a frontend.
+json_guard = JsonVerifier(name="Strict JSON")
+
+@capture(tags=["profile_generator"], verifiers=[json_guard])
+def generate_profile(request: str, steer_rules: str = ""):
+    print(f"🤖 Processing request: '{request}'...")
+    
+    # 1. Steer automatically injects rules into 'steer_rules'
+    # 2. We inject them into the System Prompt (Standard RAG/Agent pattern)
+    system_prompt = f"You are a backend API. Output data based on the request.\\nReliability Rules: {steer_rules}"
+    
+    print(f"   🧠 System Prompt: {system_prompt.strip()}")
+
+    # 3. Call Model (Mocked for demo, replace with OpenAI in prod)
+    return MockLLM.call(system_prompt, request)
+
+if __name__ == "__main__":
+    print("--- ⚡ Steer Demo: Profile Generator ---")
+    try:
+        generate_profile("Create active admin profile for Alice")
+        print("\\n✅ SUCCESS: Valid JSON returned.")
+    except Exception as e:
+        print(f"\\n🚨 BLOCKED BY STEER: {e}")
+        print("👉 Run 'steer ui' to fix the 'profile_generator'.")
+"""
+
+# --- DEMO 2: SUPPORT BOT ---
+DEMO_2_CONTENT = """from steer import capture, MockLLM
+from steer.verifiers import RegexVerifier
+
+# Scenario: A support bot summarizing tickets.
+email_guard = RegexVerifier(
+    name="PII Shield",
+    pattern=r"[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}",
+    fail_message="Output contains visible email address."
+)
+
+@capture(tags=["support_bot"], verifiers=[email_guard])
+def analyze_ticket(ticket_content: str, steer_rules: str = ""):
+    print(f"🤖 Analyzing: '{ticket_content}'...")
+    
+    # Inject rules into context
+    system_prompt = f"You are a helpful support agent.\\nSecurity Protocols: {steer_rules}"
+    print(f"   🧠 System Prompt: {system_prompt.strip()}")
+    
+    return MockLLM.call(system_prompt, ticket_content)
+
+if __name__ == "__main__":
+    print("--- ⚡ Steer Demo: Support Bot ---")
+    try:
+        analyze_ticket("Ticket #994: Refund request from Alice")
+        print("\\n✅ SUCCESS: PII was redacted.")
+    except Exception as e:
+        print(f"\\n🚨 BLOCKED BY STEER: {e}")
+        print("👉 Run 'steer ui' to fix the 'support_bot'.")
+"""
+
+# --- DEMO 3: WEATHER BOT ---
+DEMO_3_CONTENT = """from steer import capture, MockLLM
+from steer.verifiers import AmbiguityVerifier
+
+# Scenario: A weather bot checking forecasts.
+logic_guard = AmbiguityVerifier(
+    name="Ambiguity Check",
+    tool_result_key="results",
+    answer_key="message",
+    threshold=3, 
+    required_phrase="which state"
+)
+
+@capture(tags=["weather_bot"], verifiers=[logic_guard])
+def check_forecast(location: str, steer_rules: str = ""):
+    print(f"🤖 Checking: '{location}'...")
+    
+    system_prompt = f"You are a weather bot.\\nPolicy: {steer_rules}"
+    print(f"   🧠 System Prompt: {system_prompt.strip()}")
+    
+    return MockLLM.call(system_prompt, location)
+
+if __name__ == "__main__":
+    print("--- ⚡ Steer Demo: Weather Bot ---")
+    try:
+        check_forecast("What is the weather in Springfield?")
+        print("\\n✅ SUCCESS: Bot asked for clarification.")
+    except Exception as e:
+        print(f"\\n🚨 BLOCKED BY STEER: {e}")
+        print("👉 Run 'steer ui' to fix the 'weather_bot'.")
+"""
+
+def generate_demos():
+    files = {
+        "01_structure_guard.py": DEMO_1_CONTENT,
+        "02_safety_guard.py": DEMO_2_CONTENT,
+        "03_logic_guard.py": DEMO_3_CONTENT
+    }
+    
+    console.print("\n[bold green]📦 Generating Steer Demos...[/bold green]")
+    for filename, content in files.items():
+        if not os.path.exists(filename):
+            with open(filename, "w") as f:
+                f.write(content)
+            console.print(f"   Created [bold]{filename}[/bold]")
+        else:
+            console.print(f"   [dim]Skipped {filename} (exists)[/dim]")
+            
+    console.print("\n[bold]🚀 Ready![/bold] Run [green]python 01_structure_guard.py[/green] to start.")
+
+def start_server(port=8000):
+    url = f"http://localhost:{port}"
+    console.print(f"\n[bold green]🚀 Steer Mission Control active at {url}[/bold green]")
+    console.print("[dim]Press Ctrl+C to stop[/dim]\n")
+    try:
+        webbrowser.open(url)
+    except:
+        pass
+    uvicorn.run(app, host="0.0.0.0", port=port, log_level="error")
+
+def main():
+    parser = argparse.ArgumentParser(description="Steer AI - Active Reliability")
+    parser.add_argument("command", nargs="?", help="Command to run ('ui' or 'init')")
+    
+    args = parser.parse_args()
+    
+    if args.command == "ui":
+        start_server()
+    elif args.command == "init":
+        generate_demos()
+    else:
+        console.print("[bold]Steer AI[/bold] - The Active Reliability Layer")
+        console.print("Run [green]steer init[/green] to generate examples.")
+        console.print("Run [green]steer ui[/green] to start the dashboard.")
+
+if __name__ == "__main__":
+    main()

steer/config.py

@@ -0,0 +1,23 @@
+import os
+from pathlib import Path
+from typing import Optional
+from dotenv import load_dotenv
+
+load_dotenv()
+
+class SteerConfig:
+    def __init__(self):
+        self.project_root = Path(os.getcwd())
+        self.steer_dir = self.project_root / ".steer"
+        self.log_file = self.steer_dir / "runs.jsonl"
+        self.rules_file = self.project_root / "steer_rules.yaml"
+        self.steer_dir.mkdir(parents=True, exist_ok=True)
+
+        # Keys
+        self.openai_api_key = os.getenv("OPENAI_API_KEY")
+        self.gemini_api_key = os.getenv("GEMINI_API_KEY") # <--- NEW
+        
+        # Judge Defaults
+        self.judge_model = os.getenv("Steer_JUDGE_MODEL", "gemini/gemini-1.5-flash")
+
+settings = SteerConfig()

steer/core.py

@@ -0,0 +1,125 @@
+import functools
+import inspect
+from datetime import datetime, timezone
+from typing import Callable, List, Any
+
+from .schemas import Incident, TraceStep, TeachingOption
+from .worker import get_worker
+from .verifiers import BaseVerifier
+from .storage import rulebook 
+
+class VerificationError(Exception):
+    def __init__(self, message, result):
+        super().__init__(message)
+        self.result = result
+
+def capture(
+    name: str = "Agent Workflow", 
+    verifiers: List[BaseVerifier] = None,
+    severity: str = "Medium",
+    tags: List[str] = None,
+    halt_on_failure: bool = True 
+):
+    def decorator(func: Callable):
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            start_time = datetime.now(timezone.utc)
+            current_agent = tags[0] if tags and len(tags) > 0 else "default_agent"
+            
+            # 1. Dependency Injection
+            sig = inspect.signature(func)
+            if "steer_rules" in sig.parameters:
+                if "steer_rules" not in kwargs:
+                    active_rules = rulebook.get_rules_text(current_agent)
+                    kwargs["steer_rules"] = active_rules
+
+            # 2. Capture Input (Raw String)
+            display_input = "-"
+            if args:
+                display_input = str(args[0])
+            elif kwargs:
+                clean_kwargs = [str(v) for k, v in kwargs.items() if k != 'steer_rules']
+                display_input = ", ".join(clean_kwargs)
+
+            trace_steps: List[TraceStep] = []
+            trace_steps.append(TraceStep(type="user", title="User Input", content=display_input))
+            trace_steps.append(TraceStep(type="agent", title="Reasoning", content=f"Executing {func.__name__}..."))
+
+            # 3. Execution
+            error_msg = None
+            result = None
+            try:
+                result = func(*args, **kwargs)
+                display_output = str(result)
+                if isinstance(result, dict):
+                    display_output = result.get("final_answer") or result.get("answer") or result.get("response") or str(result)
+                trace_steps.append(TraceStep(type="success", title="Output Generated", content=display_output))
+            except Exception as e:
+                error_msg = str(e)
+                trace_steps.append(TraceStep(type="error", title="Runtime Exception", content=f"❌ {error_msg}"))
+            
+            # 4. Verification
+            detected_failure = None
+            verification_label = "Runtime Monitor"
+            smart_fixes = [] 
+
+            if verifiers and error_msg is None:
+                flat_inputs = {}
+                if kwargs: flat_inputs.update(kwargs)
+                flat_inputs['__active_rules__'] = rulebook.get_rules_text(current_agent)
+                
+                for v in verifiers:
+                    v_result = v.verify(flat_inputs, result)
+                    if not v_result.passed:
+                        # CRITICAL FIX: We set content=str(result) to show the raw bad output
+                        trace_steps.append(TraceStep(
+                            type="error",
+                            title=f"BLOCKED: {v_result.reason}", 
+                            content=str(result) 
+                        ))
+                        detected_failure = v_result
+                        verification_label = v_result.verifier_name
+                        smart_fixes = v_result.suggested_fixes 
+                        break 
+            
+            # 5. Logging
+            is_failure = error_msg is not None or detected_failure is not None
+            
+            if is_failure:
+                log_status = "Active"
+                log_title = f"{verification_label} Failure" if detected_failure else "Runtime Error"
+                if not smart_fixes:
+                    smart_fixes = [TeachingOption(title="Suppress", description="Ignore rule.", logic_change="None")]
+            else:
+                log_status = "Resolved"
+                log_title = "Execution Success"
+                smart_fixes = []
+
+            safe_args = [str(a) for a in args]
+            safe_kwargs = {k:str(v) for k,v in kwargs.items() if k != 'steer_rules'}
+
+            incident = Incident(
+                title=log_title,
+                agent_name=current_agent, 
+                status=log_status,
+                detection_source="FAST_PATH",
+                detection_label=verification_label if detected_failure else "System",
+                severity=severity if is_failure else "Low",
+                timestamp=start_time,
+                trace=trace_steps,
+                raw_inputs={'args': safe_args, 'kwargs': safe_kwargs},
+                raw_outputs=str(result),
+                teaching_options=smart_fixes 
+            )
+            
+            get_worker().submit(incident.model_dump(mode='json'))
+
+            if detected_failure and halt_on_failure:
+                raise VerificationError(f"Blocked by {verification_label}: {detected_failure.reason}", result)
+
+            if error_msg:
+                raise Exception(error_msg)
+            return result
+
+        return wrapper
+    return decorator

steer/llm.py

@@ -0,0 +1,55 @@
+import json
+import litellm
+from typing import Any, Dict
+from .config import settings
+
+litellm.suppress_instrumentation = True
+
+class Judge:
+    @staticmethod
+    def is_configured() -> bool:
+        return bool(settings.openai_api_key or settings.gemini_api_key)
+
+    @staticmethod
+    def evaluate(system_prompt: str, user_context: str) -> Dict[str, Any]:
+        if not Judge.is_configured():
+            return {"passed": True, "reason": "Skipped: No Key"}
+
+        # Use Gemini Flash by default for speed
+        target_model = settings.judge_model
+        api_key = None
+
+        # Route key based on model
+        if "gemini" in target_model:
+            api_key = settings.gemini_api_key
+            # Ensure prefix exists
+            if not target_model.startswith("gemini/"):
+                target_model = f"gemini/{target_model}"
+        else:
+            api_key = settings.openai_api_key
+
+        try:
+            # print(f"      [Judge] Thinking ({target_model})...")
+            response = litellm.completion(
+                model=target_model,
+                api_key=api_key,
+                messages=[
+                    {"role": "system", "content": system_prompt},
+                    {"role": "user", "content": user_context}
+                ],
+                response_format={"type": "json_object"}, 
+                temperature=0,
+                timeout=5 # Fast timeout
+            )
+            
+            content = response.choices[0].message.content
+            # Gemini Markdown Cleanup
+            if "```" in content:
+                content = content.replace("```json", "").replace("```", "").strip()
+                
+            return json.loads(content)
+
+        except Exception as e:
+            print(f"      [Judge Error] {str(e)[:50]}...")
+            # Fail open on error so we don't crash the user's app
+            return {"passed": True, "reason": "Judge Error"}

steer/mock.py

@@ -0,0 +1,65 @@
+import json
+import time
+import random
+
+class MockLLM:
+    """
+    A Simulation Engine that mimics an LLM's behavior for Steer demos.
+    It reacts to specific keywords in the System Prompt to simulate "Learning".
+    """
+    @staticmethod
+    def call(system_prompt: str, user_prompt: str):
+        # Simulate network latency
+        time.sleep(0.3)
+        
+        system_lower = system_prompt.lower()
+        user_lower = user_prompt.lower()
+        
+        # --- DEMO 1: JSON STRUCTURE GUARD ---
+        if "profile" in user_lower or "u-8821" in user_lower:
+            # TRIGGER KEYWORDS
+            if any(k in system_lower for k in ["format critical", "valid json", "strict json", "no backticks"]):
+                return json.dumps({
+                    "id": "u-8821", 
+                    "name": "Alice", 
+                    "role": "admin", 
+                    "status": "active"
+                }, indent=2)
+            
+            # Default Failure
+            return """```json
+{
+    "id": "u-8821",
+    "name": "Alice",
+    "role": "admin",
+    "status": "active"
+}
+```"""
+
+        # --- DEMO 2: PRIVACY GUARD ---
+        if "ticket" in user_lower:
+            # TRIGGER KEYWORDS
+            if any(k in system_lower for k in ["security override", "redact", "pii"]):
+                return "I have contacted [REDACTED] regarding their refund request."
+            
+            # Default Failure
+            return "I have contacted alice@example.com regarding their refund request."
+
+        # --- DEMO 3: LOGIC GUARD ---
+        if "weather" in user_lower or "springfield" in user_lower:
+            results = ["Springfield, IL", "Springfield, MA", "Springfield, MO", "Springfield, OR"]
+            
+            # TRIGGER KEYWORDS (Fixed: Removed 'policy' to avoid false positives)
+            if any(k in system_lower for k in ["ask", "clarify", "multiple results"]):
+                return {
+                    "message": "I found multiple Springfields. Which state do you mean?", 
+                    "results": results
+                }
+            
+            # Default Failure
+            return {
+                "message": "The weather in Springfield, IL is 72°F.", 
+                "results": results
+            }
+
+        return "I am a simulated model. I didn't understand the prompt context."

steer/schemas.py

@@ -0,0 +1,75 @@
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional, Literal
+from pydantic import BaseModel, Field, ConfigDict
+import uuid
+
+# --- SHARED TYPES ---
+
+class TeachingOption(BaseModel):
+    """A proposed fix for a failure."""
+    id: str = Field(default_factory=lambda: str(uuid.uuid4()))
+    title: str
+    description: str
+    recommended: bool = False
+    logic_change: Optional[str] = None # The "Why?" tooltip
+
+# --- LEGACY / INTERNAL TYPES (Needed for Verifiers) ---
+
+class VerificationResult(BaseModel):
+    """The result of a single deterministic check."""
+    verifier_name: str
+    passed: bool
+    severity: str = "error"
+    reason: Optional[str] = None
+    # Allow verifiers to propose specific fixes
+    suggested_fixes: List[TeachingOption] = Field(default_factory=list)
+
+
+# --- V4.1 ARCHITECTURE TYPES (Needed for Dashboard) ---
+
+class TraceStep(BaseModel):
+    """Represents a single node in the visual timeline."""
+    id: str = Field(default_factory=lambda: str(uuid.uuid4()))
+    type: Literal['user', 'agent', 'tool', 'error', 'success']
+    title: str
+    content: Optional[str] = None
+    metadata: Dict[str, str] = Field(default_factory=dict)
+    timestamp: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+
+class DiagnosticMetrics(BaseModel):
+    """The scorecard (Health Metrics)."""
+    faithfulness: Optional[int] = None
+    relevance: Optional[int] = None
+    context_precision: Optional[int] = None
+
+class Incident(BaseModel):
+    """
+    The Master Schema. 
+    This maps 1:1 to the 'Incident' type in the Next.js Dashboard.
+    """
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    id: str = Field(default_factory=lambda: f"INC-{uuid.uuid4().hex[:6].upper()}")
+    title: str
+    
+    # NEW: Track which agent this belongs to
+    agent_name: str = "default_agent"
+    
+    status: Literal['Active', 'Resolved'] = 'Active'
+    
+    # The "Badge" Logic
+    detection_source: Literal['FAST_PATH', 'SLOW_PATH'] = 'FAST_PATH'
+    detection_label: str # e.g. "Programmatic Verifier"
+    
+    severity: Literal['High', 'Medium', 'Low'] = 'Medium'
+    timestamp: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+    
+    metrics: Optional[DiagnosticMetrics] = None
+    
+    # The Visuals
+    trace: List[TraceStep] = Field(default_factory=list)
+    teaching_options: List[TeachingOption] = Field(default_factory=list)
+    
+    # Raw Metadata (hidden from UI but useful for debug)
+    raw_inputs: Dict[str, Any] = Field(default_factory=dict)
+    raw_outputs: Optional[Any] = None

steer/server.py

@@ -0,0 +1,122 @@
+import json
+import os
+import yaml
+from typing import List, Dict, Optional
+from pathlib import Path
+from fastapi import FastAPI, HTTPException
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.staticfiles import StaticFiles
+from fastapi.responses import FileResponse
+from pydantic import BaseModel
+
+from .config import settings
+from .storage import rulebook
+
+app = FastAPI(title="Steer Mission Control")
+
+# CORS (Useful if you ever develop frontend separately again)
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# --- DATA MODELS ---
+
+class TeachRequest(BaseModel):
+    agent_name: str = "default_agent"
+    rule_content: str
+    category: str = "general"
+    incident_id: Optional[str] = None
+
+# --- API ROUTES ---
+
+@app.get("/api/incidents")
+def get_incidents():
+    if not settings.log_file.exists():
+        return {"incidents": []}
+    
+    incidents = []
+    resolutions_path = settings.steer_dir / "resolutions.json"
+    resolved_ids = []
+    if resolutions_path.exists():
+        try:
+            resolved_ids = json.loads(resolutions_path.read_text())
+        except: pass
+
+    try:
+        with open(settings.log_file, "r") as f:
+            for line in f:
+                try:
+                    inc = json.loads(line)
+                    if inc.get("id") in resolved_ids:
+                        inc["status"] = "Resolved"
+                    incidents.append(inc)
+                except:
+                    continue
+    except Exception as e:
+        print(f"Error reading logs: {e}")
+        return {"incidents": []}
+    
+    return {"incidents": incidents[::-1]}
+
+@app.get("/api/rules")
+def get_rules():
+    try:
+        if not settings.rules_file.exists():
+            return {"rules": {}}
+        with open(settings.rules_file, "r") as f:
+            data = yaml.safe_load(f) or {}
+        return {"rules": data}
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+@app.post("/api/teach")
+def teach_agent(payload: TeachRequest):
+    try:
+        # 1. Save Rule
+        rulebook.add_rule(
+            agent_name=payload.agent_name,
+            rule_content=payload.rule_content,
+            category=payload.category
+        )
+        
+        # 2. Resolve Incident
+        if payload.incident_id:
+            resolutions_path = settings.steer_dir / "resolutions.json"
+            current_resolutions = []
+            if resolutions_path.exists():
+                try:
+                    current_resolutions = json.loads(resolutions_path.read_text())
+                except: pass
+            
+            if payload.incident_id not in current_resolutions:
+                current_resolutions.append(payload.incident_id)
+                with open(resolutions_path, "w") as f:
+                    json.dump(current_resolutions, f, indent=2)
+        
+        return {"success": True}
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+# --- STATIC FILE SERVING (The Bundle) ---
+
+# Calculate path to the bundled UI folder
+UI_DIR = Path(__file__).parent / "ui"
+
+if UI_DIR.exists():
+    # 1. Serve Next.js static assets (_next folder)
+    app.mount("/_next", StaticFiles(directory=UI_DIR / "_next"), name="next_assets")
+    
+    # 2. Catch-all for HTML (Single Page App routing)
+    # We explicitly match "/" to serve index.html
+    @app.get("/")
+    async def read_index():
+        return FileResponse(UI_DIR / "index.html")
+        
+    # Optional: Handle favicon if it exists
+    if (UI_DIR / "favicon.ico").exists():
+        @app.get("/favicon.ico")
+        async def read_favicon():
+            return FileResponse(UI_DIR / "favicon.ico")