API Reference

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

Core Decorators

@workflow

func

Callable

The function to be decorated as a workflow

wrapped_function

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

func

Callable

The function to be decorated as a transformer

wrapped_function

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

success

bool

Whether the workflow execution was successful

data

Any

The result data from the workflow execution

error

Optional[str]

Error message if the workflow failed

execution_time

float

Total execution time in seconds

trace

List[Dict]

Detailed execution trace for debugging

Container for workflow execution results with comprehensive metadata.

Provider Classes

OpenAIProvider

api_key

str

required

OpenAI API key for authentication

model

str

default:"gpt-4"

The OpenAI model to use for completions

temperature

float

default:"0.7"

Sampling temperature between 0 and 2

client

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

api_key

str

required

Anthropic API key for authentication

model

str

default:"claude-3-sonnet-20240229"

The Anthropic model to use for completions

temperature

float

default:"0.7"

Sampling temperature between 0 and 1

client

Anthropic

Configured Anthropic client instance

Anthropic provider implementation with streaming support and advanced features.

Utility Functions

cache_result

ttl

int

default:"3600"

Time to live in seconds for cached results

key_func

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

func

Callable

Function to apply to each item

items

List[Any]

List of items to process

max_workers

int

default:"4"

Maximum number of concurrent workers

results

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

providers

Dict[str, Provider]

Dictionary of configured providers by name

cache_backend

CacheBackend

Configured caching backend

tracing_enabled

bool

Whether tracing is enabled

max_retries

int

Maximum number of retries for failed operations

timeout

float

Global timeout for operations in seconds

Global configuration class for customizing Foomstack behavior.

Error Classes

WorkflowError

message

str

Human-readable error message

workflow_name

str

Name of the workflow that failed

step_name

str

Name of the step that failed

traceback

str

Full Python traceback for debugging

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

ProviderError

message

str

Human-readable error message

provider_name

str

Name of the provider that failed

status_code

Optional[int]

HTTP status code if applicable

retry_after

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.

​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