synth-ai 0.2.9.dev0__py3-none-any.whl → 0.2.23.dev3__py3-none-any.whl

synth_ai/session/models.py

@@ -0,0 +1,89 @@
+"""Agent session data models for SDK."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from decimal import Decimal
+from typing import Any, Optional
+from uuid import UUID
+
+
+@dataclass
+class AgentSessionLimit:
+    """Limit configuration for an agent session."""
+
+    limit_type: str  # 'hard', 'soft', 'rolling_window'
+    metric_type: str  # 'tokens', 'cost_usd', 'gpu_hours', 'api_calls'
+    limit_value: Decimal
+    current_usage: Decimal = Decimal("0")
+    warning_threshold: Optional[Decimal] = None
+    window_seconds: Optional[int] = None
+    limit_id: Optional[UUID] = None
+    exceeded_at: Optional[datetime] = None
+    exceeded_reason: Optional[str] = None
+    created_at: Optional[datetime] = None
+    expires_at: Optional[datetime] = None
+
+    @property
+    def remaining(self) -> Decimal:
+        """Calculate remaining limit."""
+        return self.limit_value - self.current_usage
+
+
+@dataclass
+class AgentSessionUsage:
+    """Current usage summary for a session."""
+
+    tokens: Decimal = Decimal("0")
+    cost_usd: Decimal = Decimal("0")
+    gpu_hours: Decimal = Decimal("0")
+    api_calls: int = 0
+
+
+@dataclass
+class LimitCheckResult:
+    """Result of a limit check."""
+
+    allowed: bool
+    limit_value: Decimal
+    current_usage: Decimal
+    remaining: Decimal
+    reason: Optional[str] = None
+
+
+@dataclass
+class AgentSession:
+    """Agent session representation."""
+
+    session_id: str
+    org_id: UUID
+    created_at: datetime
+    user_id: Optional[UUID] = None
+    api_key_id: Optional[UUID] = None
+    expires_at: Optional[datetime] = None
+    ended_at: Optional[datetime] = None
+    status: str = "active"  # 'active', 'ended', 'limit_exceeded', 'expired'
+    limit_exceeded_reason: Optional[str] = None
+    usage: AgentSessionUsage = field(default_factory=AgentSessionUsage)
+    limits: list[AgentSessionLimit] = field(default_factory=list)
+    tracing_session_id: Optional[str] = None
+    session_type: str = "api_call"  # 'api_call', 'job', 'tracing_session'
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class SessionUsageRecord:
+    """Individual usage event within a session."""
+
+    id: UUID
+    session_id: str
+    metric_type: str
+    metric_value: Decimal
+    org_id: UUID
+    created_at: datetime
+    reference_type: Optional[str] = None
+    reference_id: Optional[str] = None
+    user_id: Optional[UUID] = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+

synth_ai/session/query.py

@@ -0,0 +1,110 @@
+"""Query builder for agent sessions (SDK)."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any, Optional
+from uuid import UUID
+
+from synth_ai.session.client import AgentSessionClient
+from synth_ai.session.models import AgentSession
+
+
+class AgentSessionQuery:
+    """Fluent query builder for agent sessions."""
+
+    def __init__(self, client: AgentSessionClient):
+        self._client = client
+        self._filters: dict[str, Any] = {}
+        self._order_by: Optional[str] = None
+        self._limit: Optional[int] = None
+        self._offset: int = 0
+
+    def org_id(self, org_id: UUID) -> AgentSessionQuery:
+        """Filter by organization ID."""
+        self._filters["org_id"] = org_id
+        return self
+
+    def user_id(self, user_id: UUID) -> AgentSessionQuery:
+        """Filter by user ID."""
+        self._filters["user_id"] = user_id
+        return self
+
+    def status(self, status: str) -> AgentSessionQuery:
+        """Filter by status."""
+        self._filters["status"] = status
+        return self
+
+    def created_after(self, after: datetime) -> AgentSessionQuery:
+        """Filter sessions created after date."""
+        self._filters["created_after"] = after
+        return self
+
+    def created_before(self, before: datetime) -> AgentSessionQuery:
+        """Filter sessions created before date."""
+        self._filters["created_before"] = before
+        return self
+
+    def has_limit_exceeded(self) -> AgentSessionQuery:
+        """Filter sessions that exceeded limits."""
+        self._filters["limit_exceeded"] = True
+        return self
+
+    def tracing_session_id(self, tracing_session_id: str) -> AgentSessionQuery:
+        """Filter by tracing session ID."""
+        self._filters["tracing_session_id"] = tracing_session_id
+        return self
+
+    def order_by(self, field: str, desc: bool = True) -> AgentSessionQuery:
+        """Order results."""
+        self._order_by = f"{field} {'DESC' if desc else 'ASC'}"
+        return self
+
+    def limit(self, limit: int) -> AgentSessionQuery:
+        """Limit number of results."""
+        self._limit = limit
+        return self
+
+    def offset(self, offset: int) -> AgentSessionQuery:
+        """Offset for pagination."""
+        self._offset = offset
+        return self
+
+    async def execute(self) -> list[AgentSession]:
+        """Execute query and return results."""
+        params: dict[str, Any] = {}
+        
+        if "org_id" in self._filters:
+            # org_id is implicit from API key, so we don't need to pass it
+            pass
+        if "user_id" in self._filters:
+            params["user_id"] = str(self._filters["user_id"])
+        if "status" in self._filters:
+            params["status"] = self._filters["status"]
+        if "created_after" in self._filters:
+            params["created_after"] = self._filters["created_after"].isoformat()
+        if "created_before" in self._filters:
+            params["created_before"] = self._filters["created_before"].isoformat()
+        if "limit_exceeded" in self._filters and self._filters["limit_exceeded"]:
+            params["status"] = "limit_exceeded"
+        if "tracing_session_id" in self._filters:
+            params["tracing_session_id"] = self._filters["tracing_session_id"]
+        
+        if self._limit:
+            params["limit"] = self._limit
+        if self._offset:
+            params["offset"] = self._offset
+        
+        # Use client's list method
+        return await self._client.list(**params)
+
+    async def count(self) -> int:
+        """Get count of matching sessions."""
+        results = await self.execute()
+        return len(results)
+
+    async def first(self) -> Optional[AgentSession]:
+        """Get first matching session."""
+        results = await self.limit(1).execute()
+        return results[0] if results else None
+

synth_ai/spec/__init__.py

@@ -0,0 +1,46 @@
+"""System specification abstractions for synth-ai.
+
+Provides hierarchical specification format inspired by Sean Grove's "spec as code" pattern.
+Specs encode intent, policies, and rules as versioned, testable artifacts.
+"""
+
+from synth_ai.spec.dataclasses import (
+    Constraints,
+    Example,
+    GlossaryItem,
+    Interfaces,
+    Metadata,
+    Principle,
+    Rule,
+    Spec,
+    TestCase,
+)
+from synth_ai.spec.loader import load_spec_from_dict, load_spec_from_file
+from synth_ai.spec.serializer import spec_to_compact_context, spec_to_prompt_context
+from synth_ai.spec.validation import (
+    SpecValidationError,
+    SpecValidator,
+    validate_spec_dict,
+    validate_spec_file,
+)
+
+__all__ = [
+    "Spec",
+    "Metadata",
+    "Principle",
+    "Rule",
+    "Constraints",
+    "Example",
+    "TestCase",
+    "Interfaces",
+    "GlossaryItem",
+    "load_spec_from_file",
+    "load_spec_from_dict",
+    "spec_to_prompt_context",
+    "spec_to_compact_context",
+    "SpecValidator",
+    "SpecValidationError",
+    "validate_spec_dict",
+    "validate_spec_file",
+]
+

synth_ai/spec/dataclasses.py

@@ -0,0 +1,149 @@
+"""Dataclasses for hierarchical system specifications.
+
+Based on Sean Grove's "spec as code" pattern from AI Engineer World's Fair.
+Specs are the source of truth that encode intent, policies, and rules.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+
+@dataclass
+class Principle:
+    """A high-level principle or value that guides behavior."""
+
+    id: str
+    text: str
+    rationale: Optional[str] = None
+
+
+@dataclass
+class Example:
+    """An example demonstrating good or bad behavior."""
+
+    kind: str  # "good" | "bad"
+    prompt: str
+    response: str
+    description: Optional[str] = None
+
+
+@dataclass
+class TestCase:
+    """A test case to verify adherence to a rule."""
+
+    id: str
+    challenge: str
+    asserts: List[str] = field(default_factory=list)
+    expected_behavior: Optional[str] = None
+
+
+@dataclass
+class Constraints:
+    """Positive and negative constraints for a rule."""
+
+    must: List[str] = field(default_factory=list)
+    must_not: List[str] = field(default_factory=list)
+    should: List[str] = field(default_factory=list)
+    should_not: List[str] = field(default_factory=list)
+
+
+@dataclass
+class Rule:
+    """A specific policy or rule with constraints, examples, and tests."""
+
+    id: str
+    title: str
+    rationale: Optional[str] = None
+    constraints: Constraints = field(default_factory=Constraints)
+    examples: List[Example] = field(default_factory=list)
+    tests: List[TestCase] = field(default_factory=list)
+    priority: Optional[int] = None  # Higher = more important
+
+
+@dataclass
+class Metadata:
+    """Metadata about the specification."""
+
+    id: str
+    title: str
+    version: str
+    owner: Optional[str] = None
+    created_at: Optional[str] = None
+    updated_at: Optional[str] = None
+    imports: List[str] = field(default_factory=list)
+    scope: Optional[str] = None
+    description: Optional[str] = None
+
+
+@dataclass
+class Interfaces:
+    """Interface definitions for the system."""
+
+    io_modes: List[str] = field(default_factory=list)
+    capabilities: List[str] = field(default_factory=list)
+    constraints: Optional[Dict[str, Any]] = None
+
+
+@dataclass
+class GlossaryItem:
+    """A term definition in the glossary."""
+
+    term: str
+    definition: str
+    aliases: List[str] = field(default_factory=list)
+
+
+@dataclass
+class Spec:
+    """A complete system specification.
+    
+    Hierarchical structure:
+    - Metadata (versioning, ownership, imports)
+    - Principles (high-level values)
+    - Rules (specific policies with constraints, examples, tests)
+    - Interfaces (capabilities, modes)
+    - Glossary (domain terminology)
+    - Changelog (version history)
+    """
+
+    metadata: Metadata
+    principles: List[Principle] = field(default_factory=list)
+    rules: List[Rule] = field(default_factory=list)
+    interfaces: Interfaces = field(default_factory=Interfaces)
+    glossary: List[GlossaryItem] = field(default_factory=list)
+    changelog: List[Dict[str, Any]] = field(default_factory=list)
+
+    def get_rule(self, rule_id: str) -> Optional[Rule]:
+        """Get a rule by ID."""
+        for rule in self.rules:
+            if rule.id == rule_id:
+                return rule
+        return None
+
+    def get_principle(self, principle_id: str) -> Optional[Principle]:
+        """Get a principle by ID."""
+        for principle in self.principles:
+            if principle.id == principle_id:
+                return principle
+        return None
+
+    def get_glossary_term(self, term: str) -> Optional[GlossaryItem]:
+        """Get a glossary item by term or alias."""
+        term_lower = term.lower()
+        for item in self.glossary:
+            if item.term.lower() == term_lower:
+                return item
+            if any(alias.lower() == term_lower for alias in item.aliases):
+                return item
+        return None
+
+    def get_high_priority_rules(self, min_priority: int = 8) -> List[Rule]:
+        """Get rules with priority >= min_priority."""
+        return [
+            rule for rule in self.rules
+            if rule.priority is not None and rule.priority >= min_priority
+        ]
+
+

synth_ai/spec/loader.py

@@ -0,0 +1,144 @@
+"""Loaders for system specifications from JSON files."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any, Dict
+
+from synth_ai.spec.dataclasses import (
+    Constraints,
+    Example,
+    GlossaryItem,
+    Interfaces,
+    Metadata,
+    Principle,
+    Rule,
+    Spec,
+    TestCase,
+)
+
+
+def load_spec_from_dict(data: Dict[str, Any]) -> Spec:
+    """Load a Spec from a dictionary.
+    
+    Args:
+        data: Dictionary representation of a spec
+        
+    Returns:
+        Spec instance
+    """
+    # Load metadata
+    metadata_dict = data["metadata"]
+    md = Metadata(
+        id=metadata_dict["id"],
+        title=metadata_dict["title"],
+        version=metadata_dict["version"],
+        owner=metadata_dict.get("owner"),
+        created_at=metadata_dict.get("created_at"),
+        updated_at=metadata_dict.get("updated_at"),
+        imports=metadata_dict.get("imports", []),
+        scope=metadata_dict.get("scope"),
+        description=metadata_dict.get("description"),
+    )
+    
+    # Load principles
+    principles = [
+        Principle(
+            id=p["id"],
+            text=p["text"],
+            rationale=p.get("rationale"),
+        )
+        for p in data.get("principles", [])
+    ]
+    
+    # Load rules
+    def load_rule(r: Dict[str, Any]) -> Rule:
+        constraints_data = r.get("constraints", {})
+        constraints = Constraints(**constraints_data)
+        
+        examples_data = r.get("examples", [])
+        examples = [
+            Example(
+                kind=e["kind"],
+                prompt=e["prompt"],
+                response=e["response"],
+                description=e.get("description"),
+            )
+            for e in examples_data
+        ]
+        
+        tests_data = r.get("tests", [])
+        tests = [
+            TestCase(
+                id=t["id"],
+                challenge=t["challenge"],
+                asserts=t.get("asserts", []),
+                expected_behavior=t.get("expected_behavior"),
+            )
+            for t in tests_data
+        ]
+        
+        return Rule(
+            id=r["id"],
+            title=r["title"],
+            rationale=r.get("rationale"),
+            constraints=constraints,
+            examples=examples,
+            tests=tests,
+            priority=r.get("priority"),
+        )
+    
+    rules = [load_rule(r) for r in data.get("rules", [])]
+    
+    # Load interfaces
+    interfaces_data = data.get("interfaces", {})
+    interfaces = Interfaces(**interfaces_data)
+    
+    # Load glossary
+    glossary = [
+        GlossaryItem(
+            term=g["term"],
+            definition=g["definition"],
+            aliases=g.get("aliases", []),
+        )
+        for g in data.get("glossary", [])
+    ]
+    
+    # Load changelog
+    changelog = data.get("changelog", [])
+    
+    return Spec(
+        metadata=md,
+        principles=principles,
+        rules=rules,
+        interfaces=interfaces,
+        glossary=glossary,
+        changelog=changelog,
+    )
+
+
+def load_spec_from_file(path: str | Path) -> Spec:
+    """Load a Spec from a JSON file.
+    
+    Args:
+        path: Path to JSON file
+        
+    Returns:
+        Spec instance
+        
+    Raises:
+        FileNotFoundError: If file doesn't exist
+        json.JSONDecodeError: If file is not valid JSON
+    """
+    path = Path(path)
+    
+    if not path.exists():
+        raise FileNotFoundError(f"Spec file not found: {path}")
+    
+    with open(path, encoding="utf-8") as f:
+        data = json.load(f)
+    
+    return load_spec_from_dict(data)
+
+