synth-ai 0.2.9.dev11__py3-none-any.whl → 0.4.1__py3-none-any.whl

synth_ai/sdk/research_agent/results_collector.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+import json
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Dict, Iterable
+
+from synth_ai.sdk.research_agent.container_builder import ContainerBackend
+
+
+class ResultsCollector:
+    """Collect and persist artifacts from a container run."""
+
+    def __init__(self, output_dir: Path):
+        self.output_dir = output_dir
+        self.output_dir.mkdir(parents=True, exist_ok=True)
+
+    async def collect_from_container(
+        self,
+        backend: ContainerBackend,
+        container_id: str,
+        patterns: Iterable[str],
+    ) -> Dict[str, Path]:
+        """Fetch artifacts via the backend and write them to disk."""
+        artifacts = await backend.collect_artifacts(container_id, patterns)
+        saved: Dict[str, Path] = {}
+        for name, content in artifacts.items():
+            path = self.output_dir / Path(name).name
+            path.write_bytes(content)
+            saved[name] = path
+        return saved
+
+    def create_manifest(self, saved_files: Dict[str, Path]) -> Path:
+        """Create a manifest describing collected artifacts."""
+        manifest = {
+            "files": [
+                {
+                    "name": name,
+                    "path": str(path.relative_to(self.output_dir)),
+                    "size_bytes": path.stat().st_size,
+                    "type": self._classify_file(name),
+                }
+                for name, path in saved_files.items()
+            ],
+            "collected_at": datetime.now(UTC).isoformat(),
+            "total_size_bytes": sum(path.stat().st_size for path in saved_files.values()),
+        }
+        manifest_path = self.output_dir / "manifest.json"
+        manifest_path.write_text(json.dumps(manifest, indent=2))
+        return manifest_path
+
+    def _classify_file(self, filename: str) -> str:
+        """Coarse file typing to make downstream filtering simpler."""
+        lowered = filename.lower()
+        if lowered.endswith(".json"):
+            if "result" in lowered or "metric" in lowered:
+                return "metrics"
+            if "config" in lowered:
+                return "config"
+            return "data"
+        if lowered.endswith(".log"):
+            return "logs"
+        if lowered.endswith(".md"):
+            return "documentation"
+        if lowered.endswith((".toml", ".yaml", ".yml")):
+            return "config"
+        if lowered == "diff.patch":
+            return "code_changes"
+        return "other"

synth_ai/sdk/specs/__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.sdk.specs.dataclasses import (
+    Constraints,
+    Example,
+    GlossaryItem,
+    Interfaces,
+    Metadata,
+    Principle,
+    Rule,
+    Spec,
+    TestCase,
+)
+from synth_ai.sdk.specs.loader import load_spec_from_dict, load_spec_from_file
+from synth_ai.sdk.specs.serializer import spec_to_compact_context, spec_to_prompt_context
+from synth_ai.sdk.specs.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/sdk/specs/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/sdk/specs/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.sdk.specs.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)
+
+

synth_ai/sdk/specs/serializer.py

@@ -0,0 +1,199 @@
+"""Serializers for converting specs to prompt-friendly formats."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from synth_ai.sdk.specs.dataclasses import Spec
+
+
+def spec_to_prompt_context(
+    spec: Spec,
+    include_examples: bool = True,
+    include_tests: bool = False,
+    include_glossary: bool = True,
+    max_rules: Optional[int] = None,
+    priority_threshold: Optional[int] = None,
+) -> str:
+    """Convert a Spec to a prompt-friendly markdown format.
+    
+    Args:
+        spec: The specification to serialize
+        include_examples: Whether to include rule examples
+        include_tests: Whether to include test cases
+        include_glossary: Whether to include glossary terms
+        max_rules: Maximum number of rules to include (None = all)
+        priority_threshold: Only include rules with priority >= threshold
+        
+    Returns:
+        Markdown-formatted string suitable for inclusion in prompts
+    """
+    lines = []
+    
+    # Header
+    lines.append(f"# {spec.metadata.title}")
+    if spec.metadata.description:
+        lines.append(f"\n{spec.metadata.description}")
+    lines.append(f"\n**Version:** {spec.metadata.version}")
+    if spec.metadata.scope:
+        lines.append(f"**Scope:** {spec.metadata.scope}")
+    lines.append("")
+    
+    # Principles
+    if spec.principles:
+        lines.append("## Guiding Principles\n")
+        for principle in spec.principles:
+            lines.append(f"**{principle.id}**: {principle.text}")
+            if principle.rationale:
+                lines.append(f"  - *Rationale:* {principle.rationale}")
+            lines.append("")
+    
+    # Rules
+    if spec.rules:
+        # Filter rules by priority if specified
+        rules_to_include = spec.rules
+        if priority_threshold is not None:
+            rules_to_include = [
+                r for r in rules_to_include
+                if r.priority is not None and r.priority >= priority_threshold
+            ]
+        
+        # Sort by priority (highest first)
+        rules_to_include = sorted(
+            rules_to_include,
+            key=lambda r: r.priority if r.priority is not None else 0,
+            reverse=True,
+        )
+        
+        # Limit number of rules
+        if max_rules is not None:
+            rules_to_include = rules_to_include[:max_rules]
+        
+        if rules_to_include:
+            lines.append("## Rules and Policies\n")
+            
+            for rule in rules_to_include:
+                # Rule header
+                priority_str = f" [Priority: {rule.priority}]" if rule.priority else ""
+                lines.append(f"### {rule.id}: {rule.title}{priority_str}\n")
+                
+                if rule.rationale:
+                    lines.append(f"*Rationale:* {rule.rationale}\n")
+                
+                # Constraints
+                if rule.constraints.must or rule.constraints.must_not:
+                    lines.append("**Constraints:**")
+                    
+                    if rule.constraints.must:
+                        lines.append("- **MUST:**")
+                        for constraint in rule.constraints.must:
+                            lines.append(f"  - {constraint}")
+                    
+                    if rule.constraints.must_not:
+                        lines.append("- **MUST NOT:**")
+                        for constraint in rule.constraints.must_not:
+                            lines.append(f"  - {constraint}")
+                    
+                    if rule.constraints.should:
+                        lines.append("- **SHOULD:**")
+                        for constraint in rule.constraints.should:
+                            lines.append(f"  - {constraint}")
+                    
+                    if rule.constraints.should_not:
+                        lines.append("- **SHOULD NOT:**")
+                        for constraint in rule.constraints.should_not:
+                            lines.append(f"  - {constraint}")
+                    
+                    lines.append("")
+                
+                # Examples
+                if include_examples and rule.examples:
+                    lines.append("**Examples:**\n")
+                    
+                    good_examples = [e for e in rule.examples if e.kind == "good"]
+                    bad_examples = [e for e in rule.examples if e.kind == "bad"]
+                    
+                    if good_examples:
+                        lines.append("✅ **Good:**")
+                        for ex in good_examples:
+                            lines.append(f"- Prompt: \"{ex.prompt}\"")
+                            lines.append(f"  Response: \"{ex.response}\"")
+                            if ex.description:
+                                lines.append(f"  *{ex.description}*")
+                        lines.append("")
+                    
+                    if bad_examples:
+                        lines.append("❌ **Bad:**")
+                        for ex in bad_examples:
+                            lines.append(f"- Prompt: \"{ex.prompt}\"")
+                            lines.append(f"  Response: \"{ex.response}\"")
+                            if ex.description:
+                                lines.append(f"  *{ex.description}*")
+                        lines.append("")
+                
+                # Tests
+                if include_tests and rule.tests:
+                    lines.append("**Test Cases:**\n")
+                    for test in rule.tests:
+                        lines.append(f"- {test.id}: {test.challenge}")
+                        if test.asserts:
+                            lines.append(f"  Asserts: {', '.join(test.asserts)}")
+                        if test.expected_behavior:
+                            lines.append(f"  Expected: {test.expected_behavior}")
+                    lines.append("")
+    
+    # Glossary
+    if include_glossary and spec.glossary:
+        lines.append("## Glossary\n")
+        for item in spec.glossary:
+            aliases_str = f" (aliases: {', '.join(item.aliases)})" if item.aliases else ""
+            lines.append(f"**{item.term}**{aliases_str}: {item.definition}")
+        lines.append("")
+    
+    return "\n".join(lines)
+
+
+def spec_to_compact_context(spec: Spec, max_tokens: int = 5000) -> str:
+    """Convert a Spec to a compact prompt context within token limit.
+    
+    Prioritizes high-priority rules and essential information.
+    
+    Args:
+        spec: The specification to serialize
+        max_tokens: Approximate maximum tokens (uses char estimation: 4 chars ≈ 1 token)
+        
+    Returns:
+        Compact markdown-formatted string
+    """
+    # Start with high-priority rules only
+    context = spec_to_prompt_context(
+        spec,
+        include_examples=True,
+        include_tests=False,
+        include_glossary=True,
+        priority_threshold=7,
+    )
+    
+    # If still too long, try with fewer examples
+    max_chars = max_tokens * 4
+    if len(context) > max_chars:
+        context = spec_to_prompt_context(
+            spec,
+            include_examples=False,
+            include_tests=False,
+            include_glossary=True,
+            priority_threshold=7,
+        )
+    
+    # If still too long, reduce glossary
+    if len(context) > max_chars:
+        context = spec_to_prompt_context(
+            spec,
+            include_examples=False,
+            include_tests=False,
+            include_glossary=False,
+            priority_threshold=8,
+        )
+    
+    return context
+