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

# API Reference

> Complete API reference for Foomstack framework components and functions

# API Reference

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

## Core Decorators

### @workflow

<ParamField body="func" type="Callable">
  The function to be decorated as a workflow
</ParamField>

<ResponseField name="wrapped_function" type="Callable">
  The decorated workflow function with enhanced execution capabilities
</ResponseField>

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

```python
from foomstack import workflow

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

### @transformer

<ParamField body="func" type="Callable">
  The function to be decorated as a transformer
</ParamField>

<ResponseField name="wrapped_function" type="Callable">
  The decorated transformer function with caching and tracing
</ResponseField>

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

```python
from foomstack import transformer

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

## Core Classes

### WorkflowResult

<ResponseField name="success" type="bool">
  Whether the workflow execution was successful
</ResponseField>

<ResponseField name="data" type="Any">
  The result data from the workflow execution
</ResponseField>

<ResponseField name="error" type="Optional[str]">
  Error message if the workflow failed
</ResponseField>

<ResponseField name="execution_time" type="float">
  Total execution time in seconds
</ResponseField>

<ResponseField name="trace" type="List[Dict]">
  Detailed execution trace for debugging
</ResponseField>

Container for workflow execution results with comprehensive metadata.

## Provider Classes

### OpenAIProvider

<ParamField body="api_key" type="str" required>
  OpenAI API key for authentication
</ParamField>

<ParamField body="model" type="str" default="gpt-4">
  The OpenAI model to use for completions
</ParamField>

<ParamField body="temperature" type="float" default="0.7">
  Sampling temperature between 0 and 2
</ParamField>

<ResponseField name="client" type="OpenAI">
  Configured OpenAI client instance
</ResponseField>

OpenAI provider implementation with automatic retry logic and error handling.

<RequestExample>
  ```python
  from foomstack.providers import OpenAIProvider

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

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

  ```
</RequestExample>

### AnthropicProvider

<ParamField body="api_key" type="str" required>
  Anthropic API key for authentication
</ParamField>

<ParamField body="model" type="str" default="claude-3-sonnet-20240229">
  The Anthropic model to use for completions
</ParamField>

<ParamField body="temperature" type="float" default="0.7">
  Sampling temperature between 0 and 1
</ParamField>

<ResponseField name="client" type="Anthropic">
  Configured Anthropic client instance
</ResponseField>

Anthropic provider implementation with streaming support and advanced features.

## Utility Functions

### cache\_result

<ParamField body="ttl" type="int" default="3600">
  Time to live in seconds for cached results
</ParamField>

<ParamField body="key_func" type="Optional[Callable]" default="None">
  Custom function to generate cache keys
</ParamField>

Decorator for caching function results based on input parameters.

```python
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

<ParamField body="func" type="Callable">
  Function to apply to each item
</ParamField>

<ParamField body="items" type="List[Any]">
  List of items to process
</ParamField>

<ParamField body="max_workers" type="int" default="4">
  Maximum number of concurrent workers
</ParamField>

<ResponseField name="results" type="List[Any]">
  List of results in the same order as input items
</ResponseField>

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

<CodeGroup>
  ```python
  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]

  ```
</CodeGroup>

## Configuration Classes

### FoomstackConfig

<ResponseField name="providers" type="Dict[str, Provider]">
  Dictionary of configured providers by name
</ResponseField>

<ResponseField name="cache_backend" type="CacheBackend">
  Configured caching backend
</ResponseField>

<ResponseField name="tracing_enabled" type="bool">
  Whether tracing is enabled
</ResponseField>

<ResponseField name="max_retries" type="int">
  Maximum number of retries for failed operations
</ResponseField>

<ResponseField name="timeout" type="float">
  Global timeout for operations in seconds
</ResponseField>

Global configuration class for customizing Foomstack behavior.

## Error Classes

### WorkflowError

<ResponseField name="message" type="str">
  Human-readable error message
</ResponseField>

<ResponseField name="workflow_name" type="str">
  Name of the workflow that failed
</ResponseField>

<ResponseField name="step_name" type="str">
  Name of the step that failed
</ResponseField>

<ResponseField name="traceback" type="str">
  Full Python traceback for debugging
</ResponseField>

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

### ProviderError

<ResponseField name="message" type="str">
  Human-readable error message
</ResponseField>

<ResponseField name="provider_name" type="str">
  Name of the provider that failed
</ResponseField>

<ResponseField name="status_code" type="Optional[int]">
  HTTP status code if applicable
</ResponseField>

<ResponseField name="retry_after" type="Optional[int]">
  Seconds to wait before retrying
</ResponseField>

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

## Constants

### DEFAULT\_MODEL\_TIMEOUT

```python
DEFAULT_MODEL_TIMEOUT = 300  # 5 minutes
```

Default timeout for model API calls in seconds.

### MAX\_RETRY\_ATTEMPTS

```python
MAX_RETRY_ATTEMPTS = 3
```

Maximum number of retry attempts for failed operations.

### CACHE\_DEFAULT\_TTL

```python
CACHE_DEFAULT_TTL = 3600  # 1 hour
```

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

## Examples

See our [examples section](/examples) for complete working code samples demonstrating these APIs in action.