agentflowkit 0.1.0__tar.gz → 0.4.0__tar.gz

agentflowkit-0.4.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,43 @@
+---
+name: Bug Report
+about: Report a reproducible bug in agentflowkit
+title: "[Bug] "
+labels: bug
+assignees: ""
+---
+
+## Description
+
+A clear, concise description of the bug.
+
+## Reproduction Steps
+
+```python
+# Minimal reproducible example
+from agentflow import Agent, LLM, Pipeline
+
+@Agent(name="example", role="Example")
+async def example(task: str, context: dict) -> str:
+    return task
+
+# Code that triggers the bug
+```
+
+## Expected Behavior
+
+What you expected to happen.
+
+## Actual Behavior
+
+What actually happened (include full traceback if applicable).
+
+## Environment
+
+- `agentflowkit` version: <!-- e.g. 0.2.0 -->
+- Python version: <!-- e.g. 3.11.5 -->
+- OS: <!-- e.g. Ubuntu 22.04 / macOS 14 / Windows 11 -->
+- LLM provider: <!-- e.g. OpenAI, Groq, Ollama -->
+
+## Additional Context
+
+Any other context, screenshots, or logs that may help diagnose the issue.

agentflowkit-0.4.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,29 @@
+---
+name: Feature Request
+about: Suggest a new feature or improvement
+title: "[Feature] "
+labels: enhancement
+assignees: ""
+---
+
+## Problem Statement
+
+What problem does this feature solve? Who is affected?
+
+## Proposed Solution
+
+A clear description of what you want to happen.
+
+```python
+# Ideally, show what the API would look like
+pipe = Pipeline(llm=llm)
+pipe.add(agent, new_feature_param=...)
+```
+
+## Alternatives Considered
+
+Other approaches you considered and why you prefer this one.
+
+## Additional Context
+
+Links to related issues, prior art in other frameworks (LangChain, CrewAI, etc.), or references.

agentflowkit-0.4.0/.github/workflows/ci.yml

@@ -0,0 +1,81 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    name: Lint & Type Check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install dev dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Run ruff
+        run: ruff check src/ tests/ examples/ benchmarks/
+
+      - name: Run mypy
+        run: mypy src/agentflow/
+
+  test:
+    name: Tests (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Run tests with coverage
+        run: pytest tests/ -v --cov=agentflow --cov-report=xml --cov-report=term-missing
+
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v4
+        with:
+          file: ./coverage.xml
+          fail_ci_if_error: false
+        env:
+          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
+
+  build:
+    name: Build Distribution
+    runs-on: ubuntu-latest
+    needs: [lint, test]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build wheel and sdist
+        run: python -m build
+
+      - name: Check distributions
+        run: |
+          pip install twine
+          twine check dist/*

agentflowkit-0.4.0/.github/workflows/docs.yml

@@ -0,0 +1,32 @@
+name: Docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - "src/**"
+      - ".github/workflows/docs.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    name: Build & Deploy MkDocs
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install docs dependencies
+        run: pip install -e ".[docs]"
+
+      - name: Build and deploy to GitHub Pages
+        run: mkdocs gh-deploy --force

agentflowkit-0.4.0/.github/workflows/publish.yml

@@ -0,0 +1,33 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    environment: release
+    permissions:
+      id-token: write  # Required for OIDC trusted publishing
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build distribution
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        # No API key needed — uses OIDC trusted publishing
+        # Configure at: https://pypi.org/manage/project/agentflowkit/settings/publishing/

agentflowkit-0.4.0/.gitignore

@@ -0,0 +1,21 @@
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+.env
+.pytest_cache/
+*.egg
+# AI assistants / agents
+.claude/
+CLAUDE.md
+.cursor/
+.cursorrules
+.aider*
+.github/copilot-instructions.md
+AGENTS.md
+chat.md
+tmpclaude-*

agentflowkit-0.4.0/CHANGELOG.md

@@ -0,0 +1,111 @@
+# Changelog
+
+All notable changes to this project will be documented here.
+
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [0.3.0]
+
+### Added
+- **Tool / function calling** (`tools.py`): the `@tool` decorator turns any sync
+  or async Python function into an LLM-callable tool. Argument JSON schemas are
+  generated automatically from type hints via Pydantic. Agents given `tools=[...]`
+  run a bounded **ReAct loop** (call → execute tools → observe → repeat) up to
+  `max_tool_iterations` (default 6). Tool errors are fed back to the model for
+  recovery. New `ToolError` exception; tool-call traces recorded in
+  `AgentResult.metadata["tool_calls"]`.
+- **Cost tracking** (`pricing.py`): built-in USD price tables for common OpenAI
+  and Anthropic models with longest-prefix matching. `LLM.generate()` returns a
+  `cost` (and `prompt_tokens`/`completion_tokens`); `AgentResult.cost` and
+  `PipelineResult.total_cost` aggregate spend. Cache hits bill `0.0`.
+  `register_price()` / `estimate_cost()` are public.
+- **Token streaming**: `LLM.astream()` yields content deltas token-by-token for
+  interactive UIs (honours the rate limiter; no cache/retry mid-stream).
+- **Observability hooks** (`observability.py`): `Hooks` base class + `LoggingHooks`
+  wire the previously-unused `PipelineLogger` into `Pipeline.run()` (which was
+  silent before). A raising hook is caught and warned, never crashing the run.
+- **Production-grade retry**: unified exponential backoff with jitter and
+  `Retry-After` header support. New `LLM(retry_base_delay=, retry_jitter=)` args.
+- **Documentation site**: MkDocs Material + mkdocstrings under `docs/`, deployed
+  via a new `docs.yml` workflow. New `docs` optional-dependency group.
+- New examples: `tool_agent.py`, `streaming_and_cost.py`; and
+  `benchmarks/parallel_speedup.py`.
+
+### Fixed
+- **`py.typed` marker** added — the package advertised `Typing :: Typed` but
+  shipped no marker, so downstream type-checkers saw no types.
+- **Red CI made green**: resolved 1 `ruff` error (B904) and 7 `mypy --strict`
+  errors across `llm.py`, `cache.py`, `logging.py`, `events.py`, `pipeline.py`.
+
+### Changed
+- `__version__` bumped to `0.3.0`.
+- Test coverage raised to ~91%; `fail_under` tightened from 80 → 90.
+- `Pipeline.__init__` gains a `hooks` parameter; `run()` now emits lifecycle
+  events and generates `run_id` up front.
+
+---
+
+## [0.2.0]
+
+### Added
+- **Parallel execution**: Agents at the same DAG level now run concurrently via
+  `asyncio.gather()`. `_resolve_levels()` replaces `_resolve_order()` and uses
+  Kahn's algorithm to group independent agents.
+- **Per-agent timeout**: `Pipeline.add(timeout=N)` wraps each agent coroutine with
+  `asyncio.wait_for`; raises `AgentTimeoutError` on expiry.
+- **Conditional branching**: `Pipeline.add(condition=lambda ctx: ...)` allows
+  dynamic skipping of agents based on upstream outputs. Skipped agents emit
+  `agent_skipped` events in streaming mode.
+- **Pipeline-level retry**: `Pipeline(retry_failed_agents=N)` retries failed
+  agents up to N times with exponential backoff (1s, 2s, 4s). Timeouts are
+  non-retriable.
+- **LLM response caching** (`cache.py`): `ResponseCache` ABC with `InMemoryCache`
+  (SHA-256 key, lazy TTL eviction, max-size LRU) and `RedisCache` (optional dep).
+  Cache is wired into `LLM(cache=...)`.
+- **Rate limiting** (`rate_limiter.py`): `RateLimiter(requests_per_minute, max_concurrent)`
+  using `asyncio.Semaphore` + sliding-window counter. Async context manager interface.
+  Wired into `LLM(rate_limiter=...)`.
+- **Structured logging** (`logging.py`): `PipelineLogger` (LoggerAdapter with JSON
+  formatter) carrying `run_id` and `pipeline` through all log records.
+- **Agent output validation**: `@Agent(output_schema=MyPydanticModel)` validates
+  LLM response JSON against a Pydantic v2 model; raises `AgentOutputValidationError`
+  on failure.
+- New exception classes: `AgentTimeoutError`, `AgentOutputValidationError`.
+- `AgentResult` gains: `cached`, `level`, `timestamp` fields.
+- `PipelineResult` gains: `run_id`, `levels_executed`, `agents_with_cache_hits` fields.
+- `Event.type` now documents all valid values including `"agent_skipped"`.
+- GitHub Actions CI workflow (lint, test matrix py3.10-3.12, codecov, build check).
+- GitHub Actions publish workflow (OIDC trusted publishing on version tags).
+- Issue templates for bug reports and feature requests.
+- `CONTRIBUTING.md` with development setup and PR checklist.
+- `pythonpath = ["src"]` in pytest config to fix editable install on non-ASCII paths.
+
+### Changed
+- `__version__` bumped to `0.2.0`.
+- `pipeline.py`: `Pipeline.__init__` gains `retry_failed_agents` parameter.
+- `pipeline.py`: `Pipeline.add` gains `timeout` and `condition` parameters.
+- `llm.py`: `LLM.__init__` gains `cache` and `rate_limiter` parameters.
+  Return dict from `generate()` now includes `"cached"` key.
+- `pyproject.toml`: classifier updated to Beta; dev extras expanded;
+  `ruff`, `mypy`, `coverage` tool config sections added.
+
+### Performance
+- Two independent agents that each take 0.1s now complete in ~0.1s (parallel),
+  not ~0.2s (sequential).
+
+---
+
+## [0.1.0] — 2026-02-27
+
+### Added
+- Initial release.
+- `@Agent` decorator and `BaseAgent` ABC for defining agents.
+- `Pipeline` with topological sort (`_resolve_order`) for dependency resolution.
+- `LLM` provider abstraction with OpenAI-compatible API, retry logic.
+- `EventEmitter` + `pipeline.stream()` for async event streaming.
+- Pydantic v2 data models: `AgentResult`, `PipelineResult`, `Event`.
+- Custom exception hierarchy: `AgentFlowError`, `AgentError`, `LLMError`, `PipelineError`.
+- Published to PyPI as `agentflowkit`.

agentflowkit-0.4.0/CONTRIBUTING.md

@@ -0,0 +1,99 @@
+# Contributing to agentflowkit
+
+Thank you for your interest in contributing! This guide explains how to work on the project.
+
+## Development Setup
+
+```bash
+git clone https://github.com/KaramQ6/agentflow.git
+cd agentflow
+pip install -e ".[dev]"
+```
+
+Verify your setup:
+
+```bash
+pytest tests/ -v
+```
+
+All tests should pass before you start making changes.
+
+## Project Structure
+
+```
+src/agentflow/
+├── agent.py          # @Agent decorator + BaseAgent ABC
+├── cache.py          # ResponseCache, InMemoryCache, RedisCache
+├── events.py         # EventEmitter for streaming
+├── exceptions.py     # Exception hierarchy
+├── llm.py            # LLM provider abstraction
+├── logging.py        # PipelineLogger (structured JSON)
+├── pipeline.py       # Pipeline DAG orchestration (core)
+├── rate_limiter.py   # RateLimiter (RPM + concurrency)
+└── types.py          # Pydantic data models
+```
+
+## Code Style
+
+We use **ruff** for linting + formatting and **mypy** for type checking.
+
+```bash
+ruff check src/ tests/          # Lint
+ruff format src/ tests/         # Format
+mypy src/agentflow/             # Type check
+```
+
+All code must:
+- Have full type hints
+- Pass `ruff check` with no errors
+- Pass `mypy` in strict mode
+
+## Adding a Feature
+
+### New cache backend
+
+1. Subclass `ResponseCache` in `cache.py`
+2. Implement `async get(key)` and `async set(key, value, ttl)`
+3. Add to `__all__` in `__init__.py`
+4. Write tests in `tests/test_cache.py`
+
+### New exception type
+
+1. Add to `exceptions.py` (subclass the appropriate parent)
+2. Add to `__all__` in `__init__.py`
+3. Import and use in the relevant module
+
+### New pipeline feature
+
+1. Add to `pipeline.py` — keep changes localized to `_PipelineNode`, `Pipeline.add()`, or the execution loop
+2. Emit appropriate events for streaming consumers
+3. Write tests in `tests/test_parallel.py` or a new test file
+
+## Pull Request Checklist
+
+- [ ] Tests added for new functionality
+- [ ] All existing tests still pass (`pytest tests/ -v`)
+- [ ] Type hints on all new functions and classes
+- [ ] Docstrings on public API additions
+- [ ] Entry added to `[Unreleased]` section in `CHANGELOG.md`
+- [ ] No new dependencies added without discussion in an issue first
+
+## Commit Message Convention
+
+We use [Conventional Commits](https://www.conventionalcommits.org/):
+
+```
+feat: add Redis cache backend
+fix: handle asyncio.TimeoutError in _execute_node
+docs: add caching section to README
+test: add parallel execution timing test
+refactor: extract _resolve_levels from _resolve_order
+```
+
+## Running the Full Suite
+
+```bash
+pytest tests/ -v --cov=agentflow --cov-report=term-missing
+```
+
+Coverage should remain ≥ 80%.