> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Recipe Registry Module

> Python API for local and HTTP recipe registries

The Recipe Registry Module provides a unified API for publishing, pulling, listing, and searching recipe bundles from both local filesystem and HTTP registries.

## Installation

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
pip install praisonai
```

## Quick Start

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonai.recipe.registry import get_registry, LocalRegistry, HttpRegistry

# Get default local registry (~/.praisonai/registry)
registry = get_registry()

# Or connect to HTTP registry
registry = get_registry("http://localhost:7777", token="your-token")
```

## Core Classes

### LocalRegistry

Filesystem-based registry with atomic writes and concurrency safety.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonai.recipe.registry import LocalRegistry
from pathlib import Path

# Use default path (~/.praisonai/registry)
registry = LocalRegistry()

# Or specify custom path
registry = LocalRegistry(Path("/path/to/registry"))
```

#### Publish a Recipe

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
result = registry.publish(
    bundle_path="./my-recipe-1.0.0.praison",
    force=False,  # Set True to overwrite existing version
    metadata={"custom_key": "value"}  # Optional metadata
)

print(f"Published: {result['name']}@{result['version']}")
print(f"Checksum: {result['checksum']}")
```

#### Pull a Recipe

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
result = registry.pull(
    name="my-recipe",
    version="1.0.0",  # Optional, defaults to latest
    output_dir=Path("./pulled"),
    verify_checksum=True
)

print(f"Pulled to: {result['path']}")
```

#### List Recipes

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
result = registry.list_recipes(
    tags=["agent", "tool"],  # Optional filter by tags
    limit=50,
    offset=0
)

for recipe in result["recipes"]:
    print(f"{recipe['name']} v{recipe['version']}: {recipe['description']}")
```

#### Search Recipes

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
results = registry.search("agent")

for recipe in results:
    print(f"{recipe['name']}: {recipe['description']}")
```

#### Get Recipe Info

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
info = registry.get_info("my-recipe")
print(f"Latest version: {info['latest']}")
print(f"Available versions: {info['versions']}")
```

#### Delete a Recipe Version

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
registry.delete("my-recipe", version="1.0.0")
```

### HttpRegistry

HTTP client for remote registries with token authentication.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonai.recipe.registry import HttpRegistry
import os

# Create client with token from environment
registry = HttpRegistry(
    url="http://localhost:7777",
    token=os.environ.get("PRAISONAI_REGISTRY_TOKEN"),
    timeout=30
)
```

#### Health Check

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
health = registry.health()
print(f"Status: {health['status']}")
print(f"Auth required: {health['auth_required']}")
```

#### All LocalRegistry Methods Available

HttpRegistry supports the same methods as LocalRegistry:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Publish (requires token if server has auth enabled)
result = registry.publish("./my-recipe-1.0.0.praison")

# Pull
result = registry.pull("my-recipe", output_dir=Path("./pulled"))

# List
recipes = registry.list_recipes()

# Search
results = registry.search("agent")
```

### get\_registry Factory

Automatically returns the appropriate registry type based on input.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonai.recipe.registry import get_registry
import os

# Local registry (default)
local = get_registry()

# Local registry with custom path
local = get_registry("/path/to/registry")

# HTTP registry
http = get_registry(
    "http://localhost:7777",
    token=os.environ.get("PRAISONAI_REGISTRY_TOKEN")
)

# HTTPS registry
https = get_registry(
    "https://registry.example.com",
    token="your-token"
)
```

## Error Handling

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonai.recipe.registry import (
    RegistryError,
    RecipeNotFoundError,
    RecipeExistsError,
    RegistryAuthError,
    RegistryNetworkError
)

try:
    registry.pull("nonexistent-recipe")
except RecipeNotFoundError as e:
    print(f"Recipe not found: {e}")
except RegistryAuthError as e:
    print(f"Authentication failed: {e}")
except RegistryNetworkError as e:
    print(f"Network error: {e}")
except RegistryError as e:
    print(f"Registry error: {e}")
```

## Environment Variables

| Variable                   | Description                                    |
| -------------------------- | ---------------------------------------------- |
| `PRAISONAI_REGISTRY_TOKEN` | Default token for HTTP registry authentication |

## Starting a Local HTTP Server

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonai.recipe.server import run_server
from pathlib import Path

# Start server programmatically
run_server(
    host="127.0.0.1",
    port=7777,
    registry_path=Path("~/.praisonai/registry").expanduser(),
    token="optional-auth-token",
    read_only=False
)
```

## Complete Example

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import os
from pathlib import Path
from praisonai.recipe.registry import get_registry

# Connect to registry
registry = get_registry(
    os.environ.get("PRAISONAI_REGISTRY_URL", None),  # None = local
    token=os.environ.get("PRAISONAI_REGISTRY_TOKEN")
)

# Publish a recipe
result = registry.publish("./my-agent-1.0.0.praison")
print(f"✓ Published {result['name']}@{result['version']}")

# List all recipes
recipes = registry.list_recipes()
print(f"\nAvailable recipes ({recipes['total']}):")
for r in recipes["recipes"]:
    print(f"  - {r['name']} v{r['version']}")

# Search for agent recipes
print("\nSearching for 'agent':")
for r in registry.search("agent"):
    print(f"  - {r['name']}: {r['description']}")

# Pull a recipe
pulled = registry.pull("my-agent", output_dir=Path("./recipes"))
print(f"\n✓ Pulled to {pulled['path']}")
```

## See Also

* [Recipe Registry CLI](/docs/cli/recipe-registry) - Command-line interface
* [Recipe Commands](/docs/cli/recipe) - Full recipe CLI reference