Metadata-Version: 2.4
Name: aiworkflow
Version: 0.1.1
Summary: A framework for AI workflow development and experimentation
Requires-Python: <3.13,>=3.10
Description-Content-Type: text/markdown
Requires-Dist: anthropic>=0.18.1
Requires-Dist: jsonschema>=4.21.1
Requires-Dist: jinja2>=3.1.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: numpy<2,>=1.21.0
Requires-Dist: openai>=1.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: requests>=2.32.0
Requires-Dist: typing_extensions>=4.0.0
Provides-Extra: tokens
Requires-Dist: tiktoken>=0.5.0; extra == "tokens"
Provides-Extra: pyfuncgen
Requires-Dist: pytest>=7.0.0; extra == "pyfuncgen"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "pyfuncgen"
Requires-Dist: pytest-timeout>=2.1.0; extra == "pyfuncgen"
Requires-Dist: pytest-json-report>=1.5.0; extra == "pyfuncgen"
Provides-Extra: kernel-gen
Requires-Dist: torch==2.7.1; extra == "kernel-gen"
Requires-Dist: ttnn==0.65.1; platform_system == "Linux" and extra == "kernel-gen"
Provides-Extra: restapi
Requires-Dist: fastapi>=0.104.0; extra == "restapi"
Requires-Dist: uvicorn[standard]>=0.24.0; extra == "restapi"
Requires-Dist: gunicorn>=21.2.0; extra == "restapi"
Requires-Dist: fastapi-azure-auth>=4.0.0; extra == "restapi"
Requires-Dist: psycopg2-binary>=2.9.0; extra == "restapi"
Provides-Extra: cli
Requires-Dist: msal>=1.34.0; extra == "cli"
Requires-Dist: python-dotenv>=1.0.0; extra == "cli"
Provides-Extra: examples
Requires-Dist: PyYAML>=6.0; extra == "examples"
Requires-Dist: pytest>=7.0.0; extra == "examples"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "examples"
Requires-Dist: pytest-timeout>=2.1.0; extra == "examples"
Requires-Dist: pytest-json-report>=1.5.0; extra == "examples"
Requires-Dist: pytest-xdist>=3.0.0; extra == "examples"
Requires-Dist: hypothesis>=6.75.3; extra == "examples"
Requires-Dist: beautifulsoup4>=4.14.2; extra == "examples"
Requires-Dist: uv>=0.9.7; extra == "examples"
Provides-Extra: dev
Requires-Dist: black>=24.2.0; extra == "dev"
Requires-Dist: mypy>=1.8.0; extra == "dev"
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: pytest-json-report>=1.5.0; extra == "dev"
Requires-Dist: pytest-xdist>=3.0.0; extra == "dev"
Requires-Dist: pre-commit>=3.5.0; extra == "dev"
Requires-Dist: locust>=2.15.0; extra == "dev"

# AIWorkflow

A Python framework for building structured AI workflows with typed LLM invocations, rich context support, and modular service architecture.

## Key Features

- **Structured AI Functions**: Define functions with typed inputs, outputs, and validation
- **Flexible Conversations**: Optionally maintain conversation context across multiple AI function calls
- **Rich Context Support**: Add files, URLs, directories, or custom data to your AI functions
- **Model Abstraction**: Switch between different LLM providers without changing your function code
- **Service Architecture**: Modular services for specific AI tasks like docstring generation and code generation
- **Schema Validation**: Automatic input validation and JSON schema output validation
- **Execution Logging**: Built-in structured logging for debugging and analysis
- **Async Support**: Full async/await support for concurrent execution
- **Complete Applications**: Full-featured applications built on the framework

## Installation

```bash
pip install aiworkflow
```

### Optional Dependencies

Install additional features as needed:

```bash
# For accurate token counting (recommended for production)
pip install aiworkflow[tokens]

# For development and examples
pip install aiworkflow[examples,dev]

# For pyfuncgen service
pip install aiworkflow[pyfuncgen]
```

## Configuration

### Anthropic Claude Models

Set your API key:

```bash
export ANTHROPIC_API_KEY="your-api-key"
```

Or configure via `~/.claude/settings.json`:

```json
{
  "apiKeyHelper": "/path/to/script/that/exports/api/key"
}
```

### LiteLLM Proxy Backend

Set your LiteLLM proxy configuration:

```bash
export LITELLM_BASE_URL="https://your-proxy-url.com"
export LITELLM_API_KEY="your-proxy-key"
```

The LiteLLM backend provides access to multiple LLM providers through a unified OpenAI-compatible interface. It uses the OpenAI Python SDK to communicate with a LiteLLM proxy server.

## Project Structure

```
aiworkflow/
├── src/aiworkflow/            # Core framework source
│   ├── core/                  # Core AIFunction and BaseModel classes
│   ├── models/                # LLM provider implementations
│   └── services/              # Specialized AI services
│       ├── docstring/         # Docstring generation service
│       └── pyfuncgen/         # Python function generation and testing
├── apps/                      # Complete applications
│   └── leetcode_solver/       # LeetCode problem solver application
└── examples/                  # Usage examples and tutorials
    ├── docstring.py           # Docstring generation with web context
    ├── greeting.py            # Basic greeting function with context
    ├── multiturn/             # Multi-turn conversation patterns
    ├── product_description.py # Product description generator
    ├── leetcode/              # LeetCode problem solver examples
    ├── pyfuncgen/             # Code generation and testing examples
    └── utils/                 # Utility functions and helpers
```

## Quick Start

```python
from aiworkflow import create_model

# Create a model (auto-detects provider from model name)
model = create_model("claude-sonnet-4-20250514")

# Run an AI function
result, conversation = await model.run(my_function, {"input": "value"})
```

For complete usage patterns including multi-turn conversations, context management, and advanced features, see [src/aiworkflow/README.md](src/aiworkflow/README.md)

## Core Components

- **AIFunction** - Base class for structured AI functions with typed inputs and outputs
- **BaseModel** - Abstract provider interface for LLM backends
- **Message** - Immutable message class for conversation management
- **Factory Functions** - Simplified model creation with automatic provider detection
- **Context System** - Rich context support for files, URLs, and directories
- **Services** - Specialized AI services for common development tasks

For detailed architecture and implementation details, see:
- [Core Abstractions](src/aiworkflow/core/README.md) - AIFunction, BaseModel, and Message classes
- [Model Implementations](src/aiworkflow/models/README.md) - Provider-specific backends and factory functions
- [Package Documentation](src/aiworkflow/README.md) - Complete API reference

## Examples

See [examples/README.md](examples/README.md) for detailed instructions on setting up and running the example code.

## Requirements

- Python 3.9+
- `jsonschema>=4.21.1`
- `jinja2>=3.1.0`
- `typing_extensions>=4.0.0`

### Model Provider Dependencies

- **Anthropic**: `anthropic>=0.18.1`, `numpy>=1.21.0`
- **LiteLLM**: `openai>=1.0.0`

### Development and Examples

- `PyYAML>=6.0` (configuration)
- `pytest>=7.0.0` (testing)
- `pytest-asyncio>=0.21.0` (async testing)
- `pytest-timeout>=2.1.0` (timeout testing)
- `pytest-json-report>=1.5.0` (JSON test reports)
- `hypothesis>=6.75.3` (property-based testing)
- `black>=24.2.0`, `mypy>=1.8.0`, `ruff>=0.2.2` (code quality)
