beeflow-ai-toolkit 0.1.0
Beeflow AI Toolkit: prompt builders, OpenAI chat client, JSON schema validation, and content generators.
Requires Python: >=3.11
Keywords: beeflow, llm, prompt, jsonschema, content-generator, openai

# Beeflow AI Toolkit

A lightweight Python toolkit providing:
- an OpenAI Chat Completions client (with simple dependency injection),
- prompt builders (e.g., concise feedback for a poker session),
- a JSON Schema validator (Draft-07),
- a registry and a base class for content generators.

Distributed under the MIT licence. Suitable for use in any project.

## Installation

Option A: install directly from the source directory (recommended for local development)

```bash
python -m pip install .
```

Option B: build and install from a wheel package

```bash
python -m pip install -U build && python -m build
python -m pip install dist/beeflow_ai_toolkit-*.whl
```

Requirements: Python 3.11+, `openai>=1.40.0`, `jsonschema>=4.21.0` (installed automatically).

## Building the package

You can build both source distribution (sdist) and wheel using the standard Python build tool.

```bash
# Optional: clean previous build artefacts
rm -rf dist/

# Install the build backend
python -m pip install -U build

# Build sdist and wheel according to pyproject.toml
python -m build

# The artefacts will be placed in ./dist/
ls dist/
# beeflow_ai_toolkit-<version>.tar.gz (sdist)
# beeflow_ai_toolkit-<version>-py3-none-any.whl (wheel)

# Optionally, verify the wheel installs correctly
python -m pip install dist/beeflow_ai_toolkit-*.whl
```

The project is configured via `pyproject.toml` and uses `setuptools` as the build backend.

## Quick Start

### 1) OpenAI client and poker feedback generator

```python
from beeflow_ai import (
    OpenAIChatCompletionClient,
    PokerFeedbackGenerator,
    PokerStats,
)

# Set the API key (or pass it explicitly to the client)
# export OPENAI_API_KEY=...

client = OpenAIChatCompletionClient()  # uses OPENAI_API_KEY from the environment

# Optional: select the model via an environment variable, e.g. POKER_FEEDBACK_MODEL
# export POKER_FEEDBACK_MODEL=gpt-4o-mini

gen = PokerFeedbackGenerator(chat_completion_client=client)  # default model from env or 'gpt-5'
stats: PokerStats = {
    "hands_played": 120,
    "vpip": 28.3,
    "pfr": 22.1,
    "three_bet": 9.6,
    "aggression_factor": 2.7,
    "showdown_win_rate": 55.0,
    "net_profit_bb": 35,
    "session_minutes": 75,
    "strengths": ["Value-betting"],
    "leaks": ["Calling 3-bets too wide"],
}
text = gen.generate(stats, top_p=0.8, max_tokens=64)
print(text)
```

### 2) JSON Schema validation

```python
from beeflow_ai import JsonSchemaValidator, SchemaValidatorLoader

schema = {
    "$schema": "http://json-schema.org/draft-07/schema#",
    "type": "object",
    "properties": {
        "name": {"type": "string"},
        "age": {"type": "integer", "minimum": 0},
    },
    "required": ["name"],
}
validator = JsonSchemaValidator(schema)
result = validator.validate({"name": "Alice", "age": 8})
assert result["ok"]

# Or use the loader (e.g., when schemas are packaged as data files)
loader = SchemaValidatorLoader(
    schema_pkg="my.schemas",
    schema_name="person.schema.json",
)
print(loader.validate({"name": "Bob"}))
```

## Public API

The package exports:
- `OpenAIChatCompletionClient`, `ChatCompletionClient` (protocol),
- `BaseContentGenerator`, `ContentGeneratorRegistry`, `register_content_generator`,
- `PokerFeedbackPromptBuilder`, `PokerFeedbackGenerator`, `PokerStats`,
- `JsonSchemaValidator`, `SchemaValidatorLoader`, `load_schema`.

Internal implementations rely on relative imports and dependency injection, making them easy
to test without patching global modules.

## Environment Configuration

- `OPENAI_API_KEY` — API key for OpenAI.
- `STORY_GENERATION_MODEL` — default model for generators based on `BaseContentGenerator`.
- `POKER_FEEDBACK_MODEL` — default model used by `PokerFeedbackGenerator`.

## Licence

MIT — see the `LICENSE` file for details.