hoshii-cdk 1.0.5

A framework for building Hoshii-compliant code components

hoshii-cdk

A Python framework for building Hoshii-compliant code components with declarative action definitions.

Installation

pip install hoshii-cdk

Quick Start

Define a component with typed actions:

from hoshii_cdk import Component, action
from your_proto_package import ListItemsRequest, ListItemsResponse

class ItemsComponent(Component):
    name = "Items"
    description = "Item/product operations"
    
    @action(
        name="List Items",
        description="List items with optional filtering and pagination",
        request_schema=ListItemsRequest,
        response_schema=ListItemsResponse,
    )
    def list_items(self, request: dict) -> dict:
        # Your implementation here
        ...

Register and use the component:

from hoshii_cdk import Registry
from your_components import ItemsComponent

registry = Registry()
registry.register(ItemsComponent)

# Get manifest for workflow platform introspection
manifest = registry.get_manifest()

# Invoke an action
result = registry.invoke("Items", "list_items", {"active_only": True})

Features

• Declarative Actions: Define actions with @action decorator including name, description, and schemas
• Protobuf Schema Support: Automatically converts protobuf message types to JSON Schema
• Registry System: Discover, register, and invoke component actions
• Workflow Platform Integration: Get action manifests with full schema information for UI generation
• Manifest Generation: Export component metadata to JSON files for build-time discovery
• Runtime Execution: Load manifests and execute actions in sandboxed environments (e.g., e2b)
• CLI Tools: Command-line utilities for generating and validating manifests

API Reference

Component

Base class for defining components:

class MyComponent(Component):
    name = "My Component"
    description = "Description of what this component does"

@action

Decorator for defining actions:

@action(
    name="Action Name",
    description="What this action does",
    request_schema=RequestProtoMessage,
    response_schema=ResponseProtoMessage,
    tags=["optional", "tags"],
)
def my_action(self, request: dict) -> dict:
    ...

Registry

Central registry for managing components:

registry = Registry()

# Register a component
registry.register(MyComponent)

# Auto-discover components in a module
registry.discover("my_package.components")

# Get manifest with all actions and schemas
manifest = registry.get_manifest()

# Invoke an action
result = registry.invoke("ComponentName", "action_name", request_dict)

Manifest Workflow

The CDK supports a two-phase workflow for integration with workflow platforms:

Build-Time: Generate Manifest

Generate a JSON manifest containing all component and action metadata:

from hoshii_cdk import Registry, generate_manifest

# Discover and register components
registry = Registry()
registry.discover("my_component.components")

# Generate manifest.json
generate_manifest(registry, "manifest.json")

Or use the CLI:

python -m hoshii_cdk.cli generate \
  --module my_component.components \
  --output manifest.json

The generated manifest contains:

• Component names and descriptions
• Action names, descriptions, and tags
• Full JSON Schema for request/response types
• All metadata needed for UI generation

Runtime: Execute from Manifest

In a sandboxed environment (e.g., e2b), load the manifest and execute actions:

from hoshii_cdk import ComponentRunner

# Initialize runner with manifest and component module
runner = ComponentRunner("manifest.json", "my_component.components")

# Import components
runner.import_components()

# List available components and actions
components = runner.list_components()  # ["Items", "BusinessPartners"]
actions = runner.list_actions("Items")  # ["list_items", "get_item"]

# Get schema for an action
schema = runner.get_action_schema("Items", "list_items")
# Returns: {"request_schema": {...}, "response_schema": {...}}

# Invoke an action
result = runner.invoke("Items", "list_items", {"active_only": True})

CLI Tools

Validate a manifest:

python -m hoshii_cdk.cli validate manifest.json -vv

Development

Setup

1. Clone the repository:

git clone https://github.com/hoshii-ai/hoshii-cdk-python
cd hoshii-cdk-python

2. Create and activate a virtual environment:

python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

3. Install the package in development mode with dev dependencies:

pip install -e ".[dev]"

Running Tests

Run all tests:

pytest

Run with coverage:

pytest --cov=hoshii_cdk --cov-report=html

Run specific test file:

pytest tests/test_component.py -v

Building the Package

1. Install build tools:

pip install build twine

2. Build the package:

python -m build

This creates distribution files in the dist/ directory:

• hoshii_cdk-1.0.0-py3-none-any.whl (wheel)
• hoshii-cdk-1.0.0.tar.gz (source distribution)

Publishing to PyPI

The package includes a publish script for easy deployment:

Quick Publish

# Publish to PyPI
./scripts/publish.sh

# Publish to TestPyPI (recommended first)
./scripts/publish.sh --test

# Build only (no upload)
./scripts/publish.sh --dry-run

Manual Publishing

If you prefer to publish manually:

Test PyPI (Recommended First)

1. Create an account on Test PyPI

2. Upload to Test PyPI:

python -m build
python -m twine upload --repository testpypi dist/*

3. Test installation from Test PyPI:

pip install --index-url https://test.pypi.org/simple/ hoshii-cdk

Production PyPI

1. Create an account on PyPI

2. Create an API token:

   • Go to Account Settings → API tokens
   • Create a token for the project or account

3. Configure credentials (optional):

# Create ~/.pypirc
cat > ~/.pypirc << EOF
[pypi]
username = __token__
password = pypi-YOUR-API-TOKEN
EOF
chmod 600 ~/.pypirc

4. Upload to PyPI:

python -m build
python -m twine upload dist/*

Or with token directly:

python -m twine upload -u __token__ -p pypi-YOUR-API-TOKEN dist/*

5. Verify installation:

pip install hoshii-cdk

Version Bumping

Update the version in pyproject.toml and src/hoshii_cdk/__init__.py before publishing:

# pyproject.toml
[project]
version = "1.0.1"

# src/hoshii_cdk/__init__.py
__version__ = "1.0.1"

License

MIT