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

pip install praisonai

Quick Start

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.

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

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

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

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

results = registry.search("agent")

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

Get Recipe Info

info = registry.get_info("my-recipe")
print(f"Latest version: {info['latest']}")
print(f"Available versions: {info['versions']}")

Delete a Recipe Version

registry.delete("my-recipe", version="1.0.0")

HttpRegistry

HTTP client for remote registries with token authentication.

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

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:

# 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.

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

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

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

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 - Command-line interface
• Recipe Commands - Full recipe CLI reference