agent-recipes 0.0.5__py3-none-any.whl

agent_recipes/__init__.py

@@ -0,0 +1,27 @@
+"""
+Agent Recipes - Real-world AI agent templates for PraisonAI
+
+This package provides ready-to-use templates for common AI agent workflows.
+"""
+
+__version__ = "0.1.0"
+__all__ = ["get_template_path", "list_templates"]
+
+from pathlib import Path
+
+
+def get_template_path(template_name: str) -> Path:
+    """Get the path to a template directory."""
+    templates_dir = Path(__file__).parent / "templates"
+    template_path = templates_dir / template_name
+    if not template_path.exists():
+        raise ValueError(f"Template not found: {template_name}")
+    return template_path
+
+
+def list_templates() -> list:
+    """List all available templates."""
+    templates_dir = Path(__file__).parent / "templates"
+    if not templates_dir.exists():
+        return []
+    return [d.name for d in templates_dir.iterdir() if d.is_dir() and not d.name.startswith(".")]

agent_recipes/recipe_runtime/__init__.py

@@ -0,0 +1,28 @@
+"""
+Recipe Runtime - Shared utilities for all Agent-Recipes.
+
+Provides:
+- Output directory management
+- run.json generation
+- Logging setup
+- Dry-run support
+- Safety defaults
+"""
+
+from .core import (
+    RecipeRunner,
+    RecipeConfig,
+    RecipeResult,
+    create_output_dir,
+    write_run_json,
+    setup_logging,
+)
+
+__all__ = [
+    "RecipeRunner",
+    "RecipeConfig",
+    "RecipeResult",
+    "create_output_dir",
+    "write_run_json",
+    "setup_logging",
+]

agent_recipes/recipe_runtime/core.py

@@ -0,0 +1,385 @@
+"""
+Core recipe runtime utilities.
+
+Provides the foundation for all recipe execution including:
+- Output directory management with timestamps
+- run.json generation and validation
+- Logging setup
+- Dry-run support
+- Safety defaults (no overwrites, resource limits)
+"""
+
+import hashlib
+import json
+import logging
+import time
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Union
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class RecipeConfig:
+    """Configuration for a recipe run."""
+    recipe_name: str
+    input_path: str
+    output_dir: Optional[str] = None
+    preset: Optional[str] = None
+    dry_run: bool = False
+    force: bool = False
+    verbose: bool = False
+    config_file: Optional[str] = None
+    extra: Dict[str, Any] = field(default_factory=dict)
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary for run.json."""
+        return {
+            "recipe_name": self.recipe_name,
+            "input_path": self.input_path,
+            "output_dir": self.output_dir,
+            "preset": self.preset,
+            "dry_run": self.dry_run,
+            "force": self.force,
+            "verbose": self.verbose,
+            **self.extra,
+        }
+
+
+@dataclass
+class OutputFile:
+    """Information about an output file."""
+    name: str
+    path: str
+    size: int
+    sha256: Optional[str] = None
+    
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "name": self.name,
+            "path": self.path,
+            "size": self.size,
+            "sha256": self.sha256,
+        }
+
+
+@dataclass
+class RecipeResult:
+    """Result of a recipe execution."""
+    recipe: str
+    version: str
+    status: str  # success, failed, dry_run
+    started_at: str
+    completed_at: Optional[str] = None
+    input_path: str = ""
+    output_dir: str = ""
+    config: Dict[str, Any] = field(default_factory=dict)
+    outputs: List[OutputFile] = field(default_factory=list)
+    metrics: Dict[str, Any] = field(default_factory=dict)
+    logs: str = ""
+    error: Optional[str] = None
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary for run.json."""
+        return {
+            "recipe": self.recipe,
+            "version": self.version,
+            "started_at": self.started_at,
+            "completed_at": self.completed_at,
+            "status": self.status,
+            "input": self.input_path,
+            "output_dir": self.output_dir,
+            "config": self.config,
+            "outputs": [o.to_dict() for o in self.outputs],
+            "metrics": self.metrics,
+            "logs": self.logs,
+            "error": self.error,
+        }
+
+
+def get_timestamp() -> str:
+    """Get current timestamp in ISO 8601 format."""
+    return datetime.now(timezone.utc).isoformat()
+
+
+def get_timestamp_dir() -> str:
+    """Get timestamp string for directory naming."""
+    return datetime.now().strftime("%Y%m%d-%H%M%S")
+
+
+def create_output_dir(
+    recipe_name: str,
+    base_dir: Optional[Union[str, Path]] = None,
+    force: bool = False,
+) -> Path:
+    """
+    Create output directory for a recipe run.
+    
+    Args:
+        recipe_name: Name of the recipe
+        base_dir: Base output directory (default: ./outputs)
+        force: Allow overwriting existing directory
+        
+    Returns:
+        Path to created output directory
+    """
+    if base_dir is None:
+        base_dir = Path("./outputs")
+    else:
+        base_dir = Path(base_dir)
+    
+    # Create timestamped directory
+    timestamp = get_timestamp_dir()
+    output_dir = base_dir / recipe_name / timestamp
+    
+    if output_dir.exists() and not force:
+        raise FileExistsError(
+            f"Output directory already exists: {output_dir}. "
+            "Use --force to overwrite."
+        )
+    
+    output_dir.mkdir(parents=True, exist_ok=True)
+    return output_dir
+
+
+def calculate_sha256(path: Path) -> str:
+    """Calculate SHA256 hash of a file."""
+    sha256 = hashlib.sha256()
+    with open(path, "rb") as f:
+        for chunk in iter(lambda: f.read(8192), b""):
+            sha256.update(chunk)
+    return sha256.hexdigest()
+
+
+def collect_outputs(output_dir: Path, include_hash: bool = True) -> List[OutputFile]:
+    """
+    Collect information about output files.
+    
+    Args:
+        output_dir: Output directory to scan
+        include_hash: Calculate SHA256 hashes
+        
+    Returns:
+        List of OutputFile objects
+    """
+    outputs = []
+    
+    for path in output_dir.rglob("*"):
+        if path.is_file() and path.name != "run.json" and path.name != "run.log":
+            rel_path = path.relative_to(output_dir)
+            sha256 = calculate_sha256(path) if include_hash else None
+            
+            outputs.append(OutputFile(
+                name=path.name,
+                path=str(rel_path),
+                size=path.stat().st_size,
+                sha256=sha256,
+            ))
+    
+    return outputs
+
+
+def write_run_json(
+    output_dir: Path,
+    result: RecipeResult,
+) -> Path:
+    """
+    Write run.json to output directory.
+    
+    Args:
+        output_dir: Output directory
+        result: Recipe result
+        
+    Returns:
+        Path to run.json
+    """
+    run_json_path = output_dir / "run.json"
+    
+    with open(run_json_path, "w", encoding="utf-8") as f:
+        json.dump(result.to_dict(), f, indent=2)
+    
+    return run_json_path
+
+
+def setup_logging(
+    output_dir: Path,
+    verbose: bool = False,
+) -> Path:
+    """
+    Setup logging for a recipe run.
+    
+    Args:
+        output_dir: Output directory for log file
+        verbose: Enable verbose logging
+        
+    Returns:
+        Path to log file
+    """
+    log_path = output_dir / "run.log"
+    
+    # Configure logging
+    level = logging.DEBUG if verbose else logging.INFO
+    
+    # Create file handler
+    file_handler = logging.FileHandler(log_path)
+    file_handler.setLevel(level)
+    file_handler.setFormatter(logging.Formatter(
+        "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+    ))
+    
+    # Add to root logger
+    root_logger = logging.getLogger()
+    root_logger.addHandler(file_handler)
+    
+    if verbose:
+        root_logger.setLevel(logging.DEBUG)
+    
+    return log_path
+
+
+class RecipeRunner:
+    """
+    Base class for running recipes with standard safety defaults.
+    
+    Handles:
+    - Output directory creation
+    - run.json generation
+    - Logging
+    - Dry-run mode
+    - Error handling
+    """
+    
+    def __init__(
+        self,
+        recipe_name: str,
+        version: str = "1.0.0",
+    ):
+        self.recipe_name = recipe_name
+        self.version = version
+        self._start_time: Optional[float] = None
+        self._result: Optional[RecipeResult] = None
+        self._output_dir: Optional[Path] = None
+        self._log_path: Optional[Path] = None
+    
+    def run(self, config: RecipeConfig) -> RecipeResult:
+        """
+        Execute the recipe with the given configuration.
+        
+        Args:
+            config: Recipe configuration
+            
+        Returns:
+            RecipeResult with execution details
+        """
+        self._start_time = time.time()
+        started_at = get_timestamp()
+        
+        # Initialize result
+        self._result = RecipeResult(
+            recipe=self.recipe_name,
+            version=self.version,
+            status="running",
+            started_at=started_at,
+            input_path=config.input_path,
+            config=config.to_dict(),
+        )
+        
+        try:
+            # Validate input
+            self._validate_input(config)
+            
+            # Create output directory
+            if config.output_dir:
+                self._output_dir = Path(config.output_dir)
+                self._output_dir.mkdir(parents=True, exist_ok=config.force)
+            else:
+                self._output_dir = create_output_dir(
+                    self.recipe_name,
+                    force=config.force,
+                )
+            
+            self._result.output_dir = str(self._output_dir)
+            
+            # Setup logging
+            self._log_path = setup_logging(self._output_dir, config.verbose)
+            self._result.logs = str(self._log_path)
+            
+            logger.info(f"Starting recipe: {self.recipe_name}")
+            logger.info(f"Input: {config.input_path}")
+            logger.info(f"Output: {self._output_dir}")
+            
+            if config.dry_run:
+                # Dry run - just plan, don't execute
+                self._result.status = "dry_run"
+                logger.info("DRY RUN - no files will be created")
+                self._plan(config)
+            else:
+                # Execute the recipe
+                self._execute(config)
+                
+                # Collect outputs
+                self._result.outputs = collect_outputs(self._output_dir)
+                self._result.status = "success"
+            
+        except Exception as e:
+            self._result.status = "failed"
+            self._result.error = str(e)
+            logger.exception(f"Recipe failed: {e}")
+            raise
+        
+        finally:
+            # Finalize result
+            self._result.completed_at = get_timestamp()
+            
+            # Calculate metrics
+            duration = time.time() - self._start_time
+            self._result.metrics = {
+                "duration_sec": round(duration, 2),
+            }
+            
+            # Write run.json
+            if self._output_dir:
+                write_run_json(self._output_dir, self._result)
+        
+        return self._result
+    
+    def _validate_input(self, config: RecipeConfig) -> None:
+        """Validate input path exists."""
+        input_path = Path(config.input_path)
+        
+        # Allow URLs
+        if config.input_path.startswith(("http://", "https://")):
+            return
+        
+        if not input_path.exists():
+            raise FileNotFoundError(f"Input not found: {config.input_path}")
+    
+    def _plan(self, config: RecipeConfig) -> None:
+        """
+        Plan the recipe execution (for dry-run).
+        
+        Override in subclasses to provide planning output.
+        """
+        logger.info("Planning recipe execution...")
+        logger.info(f"Would process: {config.input_path}")
+        logger.info(f"Would output to: {self._output_dir}")
+    
+    def _execute(self, config: RecipeConfig) -> None:
+        """
+        Execute the recipe.
+        
+        Override in subclasses to implement recipe logic.
+        """
+        raise NotImplementedError("Subclasses must implement _execute()")
+    
+    @property
+    def output_dir(self) -> Optional[Path]:
+        """Get the output directory."""
+        return self._output_dir
+    
+    @property
+    def result(self) -> Optional[RecipeResult]:
+        """Get the current result."""
+        return self._result

agent_recipes/templates/ai-ab-hook-tester/recipe.yaml

@@ -0,0 +1,45 @@
+name: ai-ab-hook-tester
+version: 1.0.0
+description: Generate A/B test variants for hooks with tracking plan
+author: PraisonAI
+tags:
+  - testing
+  - ab-test
+  - hooks
+  - optimization
+
+config:
+  num_variants: 3
+  test_duration_days: 7
+  metrics_to_track:
+    - ctr
+    - watch_time
+    - engagement
+
+input:
+  type: object
+  properties:
+    original_hook:
+      type: string
+    topic:
+      type: string
+
+output:
+  type: object
+  properties:
+    variants:
+      type: array
+    tracking_plan:
+      type: object
+
+requires:
+  env:
+    - OPENAI_API_KEY
+
+workflow:
+  agents:
+    - name: ab_tester
+      role: A/B Test Specialist
+      tools:
+        - generate_test_variants
+        - create_tracking_plan

agent_recipes/templates/ai-ab-hook-tester/tools.py

@@ -0,0 +1,169 @@
+"""
+AI A/B Hook Tester Tools
+
+Generate test variants and tracking plans for hook optimization.
+"""
+
+import logging
+import os
+from datetime import datetime, timedelta, timezone
+from typing import Any, Dict, List
+
+logger = logging.getLogger(__name__)
+
+
+def call_llm(prompt: str, max_tokens: int = 600) -> str:
+    """Call OpenAI API."""
+    import requests
+    api_key = os.environ.get("OPENAI_API_KEY")
+    if not api_key:
+        raise ValueError("OPENAI_API_KEY not set")
+    response = requests.post(
+        "https://api.openai.com/v1/chat/completions",
+        headers={"Authorization": f"Bearer {api_key}", "Content-Type": "application/json"},
+        json={"model": "gpt-4o-mini", "messages": [{"role": "user", "content": prompt}], "max_tokens": max_tokens},
+        timeout=60,
+    )
+    response.raise_for_status()
+    return response.json()["choices"][0]["message"]["content"]
+
+
+def generate_test_variants(
+    original_hook: str,
+    topic: str,
+    num_variants: int = 3,
+) -> Dict[str, Any]:
+    """
+    Generate A/B test variants for a hook.
+    
+    Args:
+        original_hook: Original hook text
+        topic: Content topic
+        num_variants: Number of variants to generate
+        
+    Returns:
+        Dictionary with variants
+    """
+    prompt = f"""Create {num_variants} A/B test variants for this video hook:
+
+Original Hook: "{original_hook}"
+Topic: {topic}
+
+For each variant:
+1. Use a different psychological trigger (curiosity, fear, benefit, controversy)
+2. Keep it under 15 words
+3. Make it distinctly different from the original
+
+Format each variant as:
+VARIANT [number]: [hook text]
+TRIGGER: [psychological trigger used]
+HYPOTHESIS: [why this might perform better]"""
+    
+    try:
+        result = call_llm(prompt, max_tokens=500)
+        
+        variants = []
+        current_variant = {}
+        
+        for line in result.split("\n"):
+            line = line.strip()
+            if line.startswith("VARIANT"):
+                if current_variant:
+                    variants.append(current_variant)
+                current_variant = {"text": line.split(":", 1)[-1].strip()}
+            elif line.startswith("TRIGGER:"):
+                current_variant["trigger"] = line.split(":", 1)[-1].strip()
+            elif line.startswith("HYPOTHESIS:"):
+                current_variant["hypothesis"] = line.split(":", 1)[-1].strip()
+        
+        if current_variant:
+            variants.append(current_variant)
+        
+        # Add control (original)
+        all_variants = [
+            {"text": original_hook, "trigger": "control", "hypothesis": "Original baseline"}
+        ] + variants[:num_variants]
+        
+        return {
+            "variants": all_variants,
+            "original": original_hook,
+            "total_variants": len(all_variants),
+        }
+    except Exception as e:
+        logger.error(f"Error generating variants: {e}")
+        return {"error": str(e)}
+
+
+def create_tracking_plan(
+    variants: List[Dict[str, Any]],
+    test_duration_days: int = 7,
+    metrics: List[str] = None,
+) -> Dict[str, Any]:
+    """
+    Create a tracking plan for A/B test.
+    
+    Args:
+        variants: List of variant dictionaries
+        test_duration_days: Test duration in days
+        metrics: Metrics to track
+        
+    Returns:
+        Tracking plan
+    """
+    metrics = metrics or ["ctr", "watch_time", "engagement"]
+    
+    start_date = datetime.now(timezone.utc)
+    end_date = start_date + timedelta(days=test_duration_days)
+    
+    tracking_plan = {
+        "test_id": f"ab_test_{start_date.strftime('%Y%m%d_%H%M%S')}",
+        "start_date": start_date.isoformat(),
+        "end_date": end_date.isoformat(),
+        "duration_days": test_duration_days,
+        "variants": [
+            {
+                "id": f"variant_{i}",
+                "text": v.get("text", ""),
+                "trigger": v.get("trigger", ""),
+            }
+            for i, v in enumerate(variants)
+        ],
+        "metrics": {
+            m: {"description": _get_metric_description(m), "target": _get_metric_target(m)}
+            for m in metrics
+        },
+        "sample_size_per_variant": 1000,
+        "statistical_significance": 0.95,
+        "instructions": [
+            "Run each variant for equal time/impressions",
+            "Track all specified metrics",
+            "Wait for statistical significance before declaring winner",
+            "Document any external factors that might affect results",
+        ],
+    }
+    
+    return {"tracking_plan": tracking_plan}
+
+
+def _get_metric_description(metric: str) -> str:
+    """Get description for a metric."""
+    descriptions = {
+        "ctr": "Click-through rate from thumbnail/title",
+        "watch_time": "Average watch time in seconds",
+        "engagement": "Likes + comments + shares",
+        "retention": "Percentage of video watched",
+        "conversion": "Desired action completion rate",
+    }
+    return descriptions.get(metric, metric)
+
+
+def _get_metric_target(metric: str) -> str:
+    """Get target for a metric."""
+    targets = {
+        "ctr": ">5%",
+        "watch_time": ">60 seconds",
+        "engagement": ">3%",
+        "retention": ">50%",
+        "conversion": ">2%",
+    }
+    return targets.get(metric, "improve over control")

agent_recipes/templates/ai-angle-generator/recipe.yaml

@@ -0,0 +1,49 @@
+name: ai-angle-generator
+version: 1.0.0
+description: Generate multiple content angles for a topic - controversial, educational, business, risk, future prediction
+author: PraisonAI
+tags:
+  - content
+  - angles
+  - strategy
+  - ideation
+
+config:
+  angle_types:
+    - controversial
+    - educational
+    - business
+    - risk
+    - future_prediction
+    - personal_story
+    - comparison
+  num_angles: 5
+
+input:
+  type: object
+  properties:
+    topic:
+      type: string
+    angle_types:
+      type: array
+    num_angles:
+      type: integer
+
+output:
+  type: object
+  properties:
+    angles:
+      type: array
+
+requires:
+  env:
+    - OPENAI_API_KEY
+
+workflow:
+  agents:
+    - name: angle_generator
+      role: Content Strategist
+      goal: Generate diverse content angles
+      tools:
+        - generate_angles
+        - evaluate_angles