agentflowkit 0.1.0__tar.gz → 0.5.0__tar.gz

agentflowkit-0.5.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.5.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.5.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.5.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.5.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.5.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.5.0/AUDIT_REPORT.md

@@ -0,0 +1,137 @@
+# 🔍 Audit Report — `agentflowkit` v0.4.0
+
+> **الوضع:** Pass 1 (تقرير فقط — ما تم تعديل أي سطر).
+> **التاريخ:** 2026-07-03
+> **الفرع:** `main` @ `03a370d`
+> **المدقّق:** Claude (Opus 4.8) — Two-Pass Security & Health Audit
+
+---
+
+## 0. الملخّص التنفيذي
+
+| البند | النتيجة |
+|-------|---------|
+| **Stack** | Python ≥3.10 · packaging: `hatchling` · quality: `ruff` + `mypy --strict` |
+| **Core deps** | `openai>=1.0.0`, `pydantic>=2.0.0` (باقي backends: docker/redis/chromadb/aiomqtt = optional extras) |
+| **Test baseline** | ✅ `202 passed, 11 skipped` بـ ~22s — كلها خضراء (التقرير الأصلي حكى 99؛ الواقع أكبر وأصحّ) |
+| **Ruff (src)** | ❌ 2 errors بـ `swarm.py` |
+| **Mypy (src)** | ❌ 1 error بـ `swarm.py` |
+| **pip-audit** | ✅ ولا CVE بأي dependency حقيقي لـ agentflow |
+| **Secrets / eval / exec** | ✅ نظيف |
+
+**أهم 5 أولويات:**
+1. **D1** — تصليح lint/type بـ `swarm.py` (بوابة الجودة حمرا حالياً، إصلاح آمن 100%).
+2. **A1** — لفّ استدعاءات ChromaDB المتزامنة بـ `asyncio.to_thread` (blocking داخل الـ event loop).
+3. **S1** — قرار حول الـ sandbox fallback الصامت (يغيّر سلوك خارجي).
+4. **H1** — سقف عدد الجلسات بـ `InMemoryContext` (نمو ذاكرة غير محدود).
+5. **H2/A2/A3/H3/H4/H5** — تحصينات صغيرة آمنة.
+
+**تنبيه على البيئة:** الـ `venv` المفحوص بيئة مشتركة (torch+cuda، transformers، streamlit، rembg، langchain…) مش معزولة لـ agentflow — بيأثّر على قراءة الـ CVEs (شوف القسم 3).
+
+---
+
+## 1. 🔒 Security & AI Risks (أولوية قصوى)
+
+| # | Sev | Issue | File+Line | Impact | Suggested Fix |
+|---|-----|-------|-----------|--------|---------------|
+| S1 | 🟠 Med-High | **Fallback صامت لـ `SubprocessSandbox`** — لما Docker مش متوفر، `create_sandbox(prefer_docker=True)` بيرجع `SubprocessSandbox` اللي بشغّل كود الـ LLM مباشرة على الهوست (`sys.executable -c code`) بدون عزل. الاسم `sandboxed_tool` بيوحي بالأمان، والـ fallback بصير بصمت وقت الإعداد (في warning بس وقت التنفيذ). | `sandbox.py:389-415` | كود مولّد من LLM (يحتمل injection) ينفّذ على جهاز المستخدم بكامل صلاحياته. | opt-in صريح `allow_insecure_fallback=False`؛ إذا Docker مفقود وما في سماح → `raise`. **⚠️ يغيّر السلوك الخارجي — بدّه قرار.** |
+| S2 | 🟡 Low | **Heredoc breakout بالـ C++** — الكود بينحطّ داخل `sh -c` heredoc بفاصل ثابت `AGENTFLOW_EOF`؛ كود فيه هاض السطر بيكسر الـ heredoc. | `sandbox.py:64-79` | منخفض: الكسر بيضل جوّا نفس الـ container المعزول (network none, cap_drop ALL, read_only). مش هروب من الحدود. | تمرير الكود عبر stdin أو file mount بدل heredoc. |
+| S3 | 🟡 Low-Med | **Trust elevation بالـ prompt** — مخرجات الوكلاء/الأدوات السابقة بتنحقن بالـ **system** prompt (مقصوصة 300 حرف)؛ محتوى غير موثوق (نتيجة أداة web/MQTT) بيترفّع لمستوى system. | `agent.py:106-115` | منخفض-متوسط: بيضخّم prompt-injection؛ متأصّل بأطر الوكلاء. | نقل ذاكرة الجلسة لرسالة `user`/`assistant` مش `system`. informational. |
+| S4 | 🟢 OK | **No hardcoded secrets / no eval / no exec** — بس placeholders بالـ tests/docs (`"test-key"`, `"sk-or-..."`). `subprocess` محصور بـ `sandbox.py` بالتصميم. | — | نظيف. | لا شيء. |
+| S5 | 🟢 OK | **No path traversal بالـ loggers** — كتابة على stdout بس (`StreamHandler`)، ما في file paths. | `logging.py` | نظيف. | لا شيء. |
+
+---
+
+## 2. ⚙️ Async & Concurrency Health
+
+| # | Sev | Issue | File+Line | Impact | Suggested Fix |
+|---|-----|-------|-----------|--------|---------------|
+| A1 | 🟠 Med | **استدعاءات ChromaDB متزامنة (blocking) جوّا `async def`** — كل دوال `VectorContext` معرّفة `async` بس بتنادي `._collection.upsert/.query/.get/.delete` المتزامنة مباشرة. مع `PersistentClient` (disk IO) أو حساب embeddings بيتجمّد الـ event loop. باقي الكود بيلفّ الـ blocking بـ `asyncio.to_thread` (DockerSandbox / tools.py) — هون غير متسق. | `memory.py:258-323` | تجميد الـ loop تحت الحمل. | `await asyncio.to_thread(self._collection.method, …)`. |
+| A2 | 🟡 Low-Med | **RateLimiter ماسك الـ lock عبر `await sleep`** — `_wait_for_window` ماسك `self._lock` وهو نايم بالـ `asyncio.sleep`، فكل الكوروتينات الباقية بتتسكّر (تسلسل الإنتاجية)، والـ semaphore slot محجوز طول الانتظار. | `rate_limiter.py:47-59` | خنق الـ throughput، مش deadlock. | احسب مدة النوم تحت الـ lock، حرّر الـ lock، بعدها نام. |
+| A3 | 🟡 Low | **تسرّب Semaphore عند الإلغاء** — `acquire()` بياخد الـ semaphore بعدها `_wait_for_window`؛ إلغاء أثناء النوم ما بيحرّر الـ slot. وبـ `llm.py` الـ `acquire()` برّا الـ try/finally (121 مقابل try 123). | `rate_limiter.py:36-39`, `llm.py:120-121` | حالة حافة ضيّقة (cancellation). | خلّي `acquire` يحرّر الـ semaphore إذا `_wait_for_window` رمى؛ أو انقل `acquire` جوّا try. |
+| A4 | 🟢 OK | **`asyncio.gather`** — كلها `return_exceptions=True` مع معالجة، أو await متسلسل للـ tasks. ما في gather exceptions مهملة. | `pipeline.py:248,440,558`; `agent.py:283-286`; `swarm.py:162-163` | نظيف. | لا شيء. |
+| A5 | 🟢 OK | **`InMemoryContext` locking** — قفل واحد متّسق، ما في await بين check/act يسبّب race، ولا nesting. | `memory.py:48-104` | نظيف. | لا شيء. |
+
+---
+
+## 3. 📦 Dependencies
+
+### النُّسخ (Installed vs Latest)
+
+| Package | Installed | Latest | نوع | ملاحظة |
+|---------|-----------|--------|-----|--------|
+| `openai` | 1.99.9 | **2.44.0** | **MAJOR** | الكود بستورد `APIError, RateLimitError, AsyncOpenAI` + `openai.types.chat` — 2.x محتمل يكسر. **توصية بس.** |
+| `pydantic-core` | 2.46.4 | 2.47.0 | minor | آمن (patch/minor). |
+| `anyio` | 4.14.0 | 4.14.1 | patch | آمن. |
+| `ruff` (dev) | 0.1.14 | 0.15.20 | — | ⚠️ مثبّت **أقل** من floor المعلن `>=0.4` بالـ pyproject. |
+| `pytest-asyncio` (dev) | 0.23.3 | 1.4.0 | major | dev بس. |
+| `pytest-cov` (dev) | 7.0.0 | 7.1.0 | minor | dev بس. |
+
+### CVEs (pip-audit)
+
+✅ **ولا CVE بأي من dependencies الحقيقية لـ agentflow** (`openai`, `pydantic`).
+
+كل الثغرات المكتشفة بحزم **مش تابعة** لـ agentflow، موجودة بالـ venv المشترك:
+
+```
+setuptools  65.5.0  CVE-2024-6345 (RCE), PYSEC-2025-49 (path traversal), PYSEC-2022-43012
+starlette   0.37.2  عدة CVEs (2024-2026)
+tornado     6.5.2   عدة CVEs (2026)
+werkzeug    3.1.3   CVE-2025-66221, CVE-2026-21860, CVE-2026-27199
+transformers 4.57.6 PYSEC-2025-217, CVE-2026-1839, CVE-2026-4372
+streamlit   1.53.1  CVE-2026-33682
+pyarrow / rembg / wheel  ثغرات إضافية
+```
+
+- كل هدول **مش** dependencies لـ agentflow.
+- تنبيه: الـ extra الاختياري `chromadb` بيجرّ transitively `fastapi/starlette/uvicorn`.
+- **توصية:** شغّل الـ audit بـ venv معزول فيه agentflow + extras بس عشان قراءة دقيقة.
+
+---
+
+## 4. 🔁 Duplicated Logic & Refactors
+
+| # | Sev | Issue | File+Line | Impact | Suggested Fix |
+|---|-----|-------|-----------|--------|---------------|
+| D1 | 🟠 Med | **Lint/type فاشلة بـ `swarm.py`** — `ruff`: B007 (`iteration` unused @104)، F841 (`arguments` unused @148). `mypy`: no-untyped-def @184 (`_make_delegate_fn`). بوابة الجودة **حالياً حمرا**. | `swarm.py:104,148,184` | إصلاحات تافهة وآمنة. | `for _ in range(...)`، احذف `arguments` المكرّر، ضيف return type annotation. **✅ أسهل مكسب.** |
+| D2 | 🟠 Med | **بلوك HITL pause/persist مكرّر 3×** حرفياً. | `pipeline.py:250-296, 442-485, 560-595` | صيانة مؤلمة. | استخرج helper `_persist_pause_state(...)`. **⚠️ يلمس تدفق pipeline — بدّه قرار.** |
+| D3 | 🟡 Low | **حلقة ReAct مكرّرة** بين الوكيل والـ supervisor. | `agent.py:195-307` vs `swarm.py:104-182` | تكرار كبير بس **core logic**. | **توصية بس — ممنوع لمسها حسب القيود.** |
+| D4 | 🟡 Low | **guard استيراد redis مكرّر** بنمطين مختلفين. | `cache.py:80-84` vs `memory.py:108-135` | بسيط. | توحيد النمط. |
+
+---
+
+## 5. 🩺 General Health
+
+| # | Sev | Issue | File+Line | Impact | Suggested Fix |
+|---|-----|-------|-----------|--------|---------------|
+| H1 | 🟠 Med | **نمو `InMemoryContext` غير محدود بالجلسات** — `max_entries` بحدّ الإدخالات **لكل جلسة**، بس عدد الجلسات (`self._store` keys) غير محدود. الجلسات المنتهية بتتنظّف بس لما تتقرا هي بالذات عبر `load_context`. workload بيولّد session_id فريد لكل طلب وما بيرجع يقراه = تسرّب ذاكرة. | `memory.py:60, 78-91` | نمو ذاكرة غير محدود. | سقف max-sessions/sweep دوري، أو توثيق إن الـ caller لازم `clear()`. |
+| H2 | 🟡 Low | **`getattr` برّا الـ try بـ tools** — `kwargs = {k: getattr(validated, k) for k in arguments}` قبل الـ try؛ إذا الـ LLM بعت مفتاح زيادة (pydantic بتجاهله)، `getattr` بترمي `AttributeError` غير ملفوفة بـ `ToolError`. | `tools.py:94` | منخفض. | كرّر على حقول الموديل مش مفاتيح `arguments`، أو انقل جوّا try. |
+| H3 | 🟡 Low | **ما في لفّ لأخطاء Redis** — استثناءات redis الخام بتنتشر بدل framework error (غير متّسق مع لفّ `LLMError`/`ToolError`). | `memory.py:186-201`, `cache.py:119-131` | منخفض. | لفّ استدعاءات redis. |
+| H4 | 🟡 Low | **`InMemoryCache` موصوف "Thread-safe" بدون قفل** — dict عادي بلا lock (بعكس `InMemoryContext`). آمن ضمن الـ event loop بس، مش thread-safe فعلياً؛ وكمان FIFO مش LRU رغم التسمية. | `cache.py:36-70` | docstring مضلّل. | صحّح الـ docstring أو ضيف قفل. |
+| H5 | 🟡 Low | **DockerSandbox `read_only=True` مع كتابة `/tmp`** — مسار الـ C++ بيكتب `/tmp/code.cpp` بس الـ container read-only بلا tmpfs → تنفيذ C++ بالـ Docker بيفشل runtime. | `sandbox.py:201, 73-76` | خلل وظيفي (مش أمني). | ضيف `tmpfs={"/tmp": ""}` أو `read_only=False`. |
+
+---
+
+## 6. القرارات المعلّقة (بدّها موافقتك)
+
+| القرار | الوصف | الخيار |
+|--------|-------|--------|
+| **S1** | الـ sandbox fallback الصامت | نضيف `allow_insecure_fallback` ونمنع الـ fallback الصامت؟ (يغيّر سلوك) |
+| **D2** | HITL persist helper | نستخرج helper (يلمس pipeline flow)؟ |
+| **D3** | ReAct dedup | توصية فقط — ممنوع اللمس حسب القيود |
+| **openai 2.x** | ترقية major | نتركها توصية أم نجرّبها بفرع منفصل؟ |
+
+---
+
+## 7. خطة Pass 2 المقترحة (بعد الموافقة)
+
+**المجموعة الآمنة (ما بتغيّر سلوك — بتنفّذ مباشرة بعد الموافقة):**
+`D1` (lint/type) → `A1` (to_thread) → `H1` (session cap) → `H2` (try scope) → `A2`+`A3` (rate limiter) → `H3` (redis wrap) → `H4` (docstring) → `H5` (tmpfs) → dependency patches (anyio, pydantic-core).
+
+**بعد كل مجموعة:** `pytest` + `ruff` + `mypy` — والـ 202 لازم تضل خضرا.
+
+**تُترك كتوصيات فقط:** `S1`, `D2`, `D3`, `openai 2.x`.
+
+---
+
+*انتهى Pass 1 — ما تم تعديل أي سطر بالكود.*

agentflowkit-0.5.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.5.0/CMakeLists.txt

@@ -0,0 +1,30 @@
+cmake_minimum_required(VERSION 3.15)
+project(agentflow_cpp LANGUAGES NONE)
+
+set(SKIP_CPP_EXTENSION OFF CACHE BOOL "Skip building the C++ pybind11 extension")
+
+if(NOT SKIP_CPP_EXTENSION)
+    include(CheckLanguage)
+    check_language(CXX)
+    if(CMAKE_CXX_COMPILER)
+        enable_language(CXX)
+        set(CMAKE_CXX_STANDARD 17)
+        set(CMAKE_CXX_STANDARD_REQUIRED ON)
+    endif()
+endif()
+
+if(CMAKE_CXX_COMPILER AND NOT SKIP_CPP_EXTENSION)
+    find_package(pybind11 CONFIG QUIET)
+    if(pybind11_FOUND)
+        message(STATUS "pybind11 found — building _agentflow_cpp extension")
+        pybind11_add_module(_agentflow_cpp
+            src/agentflow/cpp_core/bindings.cpp
+            src/agentflow/cpp_core/dag_engine.cpp
+        )
+        target_include_directories(_agentflow_cpp PRIVATE src/agentflow/cpp_core)
+    else()
+        message(STATUS "pybind11 not found — skipping _agentflow_cpp extension (Python fallback will be used)")
+    endif()
+else()
+    message(STATUS "C++ compiler not available — skipping _agentflow_cpp extension (Python fallback will be used)")
+endif()

agentflowkit-0.5.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%.