API Reference

This comprehensive API reference covers all the core components, decorators, and utilities available in the Foomstack framework.

Core Decorators

@workflow

Callable

The function to be decorated as a workflow

Callable

The decorated workflow function with enhanced execution capabilities

Defines a workflow that orchestrates multiple transformers. Workflows automatically handle dependency resolution, parallel execution, and error recovery.

from foomstack import workflow

@workflow
def my_workflow(input_data: str) -> str:
    # Your workflow logic here
    pass

@transformer

Callable

The function to be decorated as a transformer

Callable

The decorated transformer function with caching and tracing

Transforms input data into output data with built-in caching, error handling, and observability.

from foomstack import transformer

@transformer
def process_text(text: str) -> Dict[str, Any]:
    # Your transformation logic here
    pass

Core Classes

WorkflowResult

bool

Whether the workflow execution was successful

Any

The result data from the workflow execution

Optional[str]

Error message if the workflow failed

float

Total execution time in seconds

List[Dict]

Detailed execution trace for debugging

Container for workflow execution results with comprehensive metadata.

Provider Classes

OpenAIProvider

str

required

OpenAI API key for authentication

str

default:"gpt-4"

The OpenAI model to use for completions

float

default:"0.7"

Sampling temperature between 0 and 2

OpenAI

Configured OpenAI client instance

OpenAI provider implementation with automatic retry logic and error handling.

from foomstack.providers import OpenAIProvider

provider = OpenAIProvider(
api_key="your-api-key",
model="gpt-4",
temperature=0.8
)

response = await provider.complete("Hello, world!")

AnthropicProvider

str

required

Anthropic API key for authentication

str

default:"claude-3-sonnet-20240229"

The Anthropic model to use for completions

float

default:"0.7"

Sampling temperature between 0 and 1

Anthropic

Configured Anthropic client instance

Anthropic provider implementation with streaming support and advanced features.

Utility Functions

cache_result

int

default:"3600"

Time to live in seconds for cached results

Optional[Callable]

default:"None"

Custom function to generate cache keys

Decorator for caching function results based on input parameters.

from foomstack.utils import cache_result

@cache_result(ttl=1800)  # Cache for 30 minutes
def expensive_computation(data: str) -> Dict:
    # Expensive operation here
    return result

parallel_map

Callable

Function to apply to each item

List[Any]

List of items to process

int

default:"4"

Maximum number of concurrent workers

List[Any]

List of results in the same order as input items

Apply a function to multiple items in parallel with automatic error handling.

from foomstack.utils import parallel_map

def process_item(item: str) -> int:
return len(item)

items = ["hello", "world", "parallel", "processing"]
results = await parallel_map(process_item, items)

# Results: [5, 5, 8, 10]

Configuration Classes

FoomstackConfig

Dict[str, Provider]

Dictionary of configured providers by name

CacheBackend

Configured caching backend

bool

Whether tracing is enabled

int

Maximum number of retries for failed operations

float

Global timeout for operations in seconds

Global configuration class for customizing Foomstack behavior.

Error Classes

WorkflowError

str

Human-readable error message

str

Name of the workflow that failed

str

Name of the step that failed

str

Full Python traceback for debugging

Custom exception class for workflow-related errors with detailed context.

ProviderError

str

Human-readable error message

str

Name of the provider that failed

Optional[int]

HTTP status code if applicable

Optional[int]

Seconds to wait before retrying

Custom exception class for provider-related errors with retry information.

Constants

DEFAULT_MODEL_TIMEOUT

DEFAULT_MODEL_TIMEOUT = 300  # 5 minutes

Default timeout for model API calls in seconds.

MAX_RETRY_ATTEMPTS

MAX_RETRY_ATTEMPTS = 3

Maximum number of retry attempts for failed operations.

CACHE_DEFAULT_TTL

CACHE_DEFAULT_TTL = 3600  # 1 hour

Default time-to-live for cached results in seconds.

Examples

See our examples section for complete working code samples demonstrating these APIs in action.

Overview

Decorators & hooks

API Reference

API Reference

Core Decorators

@workflow

@transformer

Core Classes

WorkflowResult

Provider Classes

OpenAIProvider

AnthropicProvider

Utility Functions

cache_result

parallel_map

Configuration Classes

FoomstackConfig

Error Classes

WorkflowError

ProviderError

Constants

DEFAULT_MODEL_TIMEOUT

MAX_RETRY_ATTEMPTS

CACHE_DEFAULT_TTL

Examples

​API Reference

​Core Decorators

​@workflow

​@transformer

​Core Classes

​WorkflowResult

​Provider Classes

​OpenAIProvider

​AnthropicProvider

​Utility Functions

​cache_result

​parallel_map

​Configuration Classes

​FoomstackConfig

​Error Classes

​WorkflowError

​ProviderError

​Constants

​DEFAULT_MODEL_TIMEOUT

​MAX_RETRY_ATTEMPTS

​CACHE_DEFAULT_TTL

​Examples

API Reference

Core Decorators

@workflow

@transformer

Core Classes

WorkflowResult

Provider Classes

OpenAIProvider

AnthropicProvider

Utility Functions

cache_result

parallel_map

Configuration Classes

FoomstackConfig

Error Classes

WorkflowError

ProviderError

Constants

DEFAULT_MODEL_TIMEOUT

MAX_RETRY_ATTEMPTS

CACHE_DEFAULT_TTL

Examples