agentflowkit 0.1.0__py3-none-any.whl

agentflow/__init__.py

@@ -0,0 +1,25 @@
+"""agentflow - Lightweight multi-agent AI pipeline framework."""
+
+__version__ = "0.1.0"
+
+from .agent import Agent, BaseAgent
+from .llm import LLM
+from .pipeline import Pipeline
+from .types import AgentResult, PipelineResult, Event
+from .events import EventEmitter
+from .exceptions import AgentFlowError, AgentError, PipelineError, LLMError
+
+__all__ = [
+    "Agent",
+    "BaseAgent",
+    "LLM",
+    "Pipeline",
+    "AgentResult",
+    "PipelineResult",
+    "Event",
+    "EventEmitter",
+    "AgentFlowError",
+    "AgentError",
+    "PipelineError",
+    "LLMError",
+]

agentflow/agent.py

@@ -0,0 +1,97 @@
+"""Agent definition via decorators and base class."""
+
+from __future__ import annotations
+
+import time
+from abc import ABC, abstractmethod
+from typing import Any, Callable, Awaitable
+
+from .llm import LLM
+from .types import AgentResult
+from .exceptions import AgentError
+
+
+class BaseAgent(ABC):
+    """Base class for agents that need full control.
+
+    Subclass this for complex agents with custom logic.
+    """
+
+    name: str
+    role: str
+
+    def __init__(self, name: str, role: str):
+        self.name = name
+        self.role = role
+
+    @abstractmethod
+    async def execute(self, task: str, context: dict[str, str], llm: LLM) -> AgentResult:
+        """Execute the agent's task.
+
+        Args:
+            task: The task/topic string.
+            context: Dict mapping agent_name -> output from previous agents.
+            llm: The LLM provider to use.
+
+        Returns:
+            AgentResult with the agent's output.
+        """
+        ...
+
+
+class _DecoratorAgent:
+    """Agent created via the @Agent decorator."""
+
+    def __init__(self, name: str, role: str, prompt_fn: Callable[..., Awaitable[str]]):
+        self.name = name
+        self.role = role
+        self._prompt_fn = prompt_fn
+
+    async def execute(self, task: str, context: dict[str, str], llm: LLM) -> AgentResult:
+        start = time.perf_counter()
+        try:
+            user_message = await self._prompt_fn(task, context)
+        except Exception as e:
+            raise AgentError(self.name, f"Prompt function failed: {e}") from e
+
+        system_prompt = f"You are a {self.role}. Provide clear, thorough, well-structured responses."
+
+        try:
+            response = await llm.generate([
+                {"role": "system", "content": system_prompt},
+                {"role": "user", "content": user_message},
+            ])
+        except Exception as e:
+            raise AgentError(self.name, str(e)) from e
+
+        duration = time.perf_counter() - start
+        return AgentResult(
+            agent=self.name,
+            output=response["content"],
+            tokens_used=response["tokens"],
+            duration=round(duration, 3),
+            metadata={"model": response["model"]},
+        )
+
+    def __repr__(self) -> str:
+        return f"Agent(name={self.name!r}, role={self.role!r})"
+
+
+class Agent:
+    """Decorator to define an agent from an async function.
+
+    The decorated function receives (task, context) and returns
+    the user message to send to the LLM.
+
+    Usage:
+        @Agent(name="researcher", role="Research Analyst")
+        async def researcher(task: str, context: dict) -> str:
+            return f"Research this topic: {task}"
+    """
+
+    def __init__(self, name: str, role: str):
+        self.name = name
+        self.role = role
+
+    def __call__(self, fn: Callable[..., Awaitable[str]]) -> _DecoratorAgent:
+        return _DecoratorAgent(self.name, self.role, fn)

agentflow/events.py

@@ -0,0 +1,32 @@
+"""Event system for pipeline streaming."""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any, AsyncGenerator
+
+from .types import Event
+
+
+class EventEmitter:
+    """Async event emitter for pipeline progress."""
+
+    def __init__(self):
+        self._queue: asyncio.Queue[Event | None] = asyncio.Queue()
+
+    def emit(self, event_type: str, agent: str = "", **data: Any) -> None:
+        """Emit an event (non-blocking)."""
+        event = Event(type=event_type, agent=agent, data=data)
+        self._queue.put_nowait(event)
+
+    def done(self) -> None:
+        """Signal that no more events will be emitted."""
+        self._queue.put_nowait(None)
+
+    async def stream(self) -> AsyncGenerator[Event, None]:
+        """Async generator that yields events until done."""
+        while True:
+            event = await self._queue.get()
+            if event is None:
+                break
+            yield event

agentflow/exceptions.py

@@ -0,0 +1,21 @@
+"""agentflow - Lightweight multi-agent AI pipeline framework."""
+
+
+class AgentFlowError(Exception):
+    """Base exception for agentflow."""
+
+
+class LLMError(AgentFlowError):
+    """Raised when an LLM call fails."""
+
+
+class AgentError(AgentFlowError):
+    """Raised when an agent execution fails."""
+
+    def __init__(self, agent_name: str, message: str):
+        self.agent_name = agent_name
+        super().__init__(f"Agent '{agent_name}' failed: {message}")
+
+
+class PipelineError(AgentFlowError):
+    """Raised when pipeline orchestration fails."""

agentflow/llm.py

@@ -0,0 +1,96 @@
+"""LLM provider abstraction for agentflow."""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from typing import Any
+
+from openai import AsyncOpenAI, APIError, RateLimitError
+
+from .exceptions import LLMError
+
+
+class LLM:
+    """OpenAI-compatible LLM provider.
+
+    Works with any provider that exposes an OpenAI-compatible API:
+    OpenAI, Groq, Together, Ollama, vLLM, etc.
+
+    Args:
+        model: Model name (e.g. "gpt-4o", "llama-3.3-70b-versatile").
+        api_key: API key for the provider.
+        base_url: Base URL for the API (default: OpenAI).
+        temperature: Sampling temperature (0.0-2.0).
+        max_tokens: Maximum tokens in response.
+        max_retries: Number of retries on transient failures.
+    """
+
+    def __init__(
+        self,
+        model: str = "gpt-4o-mini",
+        api_key: str | None = None,
+        base_url: str | None = None,
+        temperature: float = 0.7,
+        max_tokens: int = 4096,
+        max_retries: int = 2,
+    ):
+        self.model = model
+        self.temperature = temperature
+        self.max_tokens = max_tokens
+        self.max_retries = max_retries
+
+        kwargs: dict[str, Any] = {}
+        if api_key:
+            kwargs["api_key"] = api_key
+        if base_url:
+            kwargs["base_url"] = base_url
+
+        self._client = AsyncOpenAI(**kwargs)
+
+    async def generate(
+        self,
+        messages: list[dict[str, str]],
+        model: str | None = None,
+        temperature: float | None = None,
+        max_tokens: int | None = None,
+    ) -> dict[str, Any]:
+        """Generate a completion from the LLM.
+
+        Returns:
+            Dict with keys: content, tokens, duration, model.
+        """
+        start = time.perf_counter()
+        last_error = None
+
+        for attempt in range(self.max_retries + 1):
+            try:
+                response = await self._client.chat.completions.create(
+                    model=model or self.model,
+                    messages=messages,
+                    temperature=temperature if temperature is not None else self.temperature,
+                    max_tokens=max_tokens or self.max_tokens,
+                )
+                duration = time.perf_counter() - start
+                choice = response.choices[0]
+                usage = response.usage
+
+                return {
+                    "content": choice.message.content or "",
+                    "tokens": usage.total_tokens if usage else 0,
+                    "duration": round(duration, 3),
+                    "model": response.model,
+                }
+
+            except RateLimitError as e:
+                last_error = e
+                if attempt < self.max_retries:
+                    await asyncio.sleep(2 ** attempt)
+                    continue
+            except APIError as e:
+                last_error = e
+                if attempt < self.max_retries:
+                    await asyncio.sleep(1)
+                    continue
+
+        raise LLMError(f"LLM call failed after {self.max_retries + 1} attempts: {last_error}")

agentflow/pipeline.py

@@ -0,0 +1,170 @@
+"""Pipeline orchestrator for multi-agent execution."""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any, AsyncGenerator
+
+from .agent import _DecoratorAgent, BaseAgent
+from .events import EventEmitter
+from .exceptions import PipelineError, AgentError
+from .llm import LLM
+from .types import AgentResult, PipelineResult, Event
+
+
+AgentLike = _DecoratorAgent | BaseAgent
+
+
+class _PipelineNode:
+    """Internal node in the pipeline graph."""
+
+    def __init__(self, agent: AgentLike, depends_on: list[str]):
+        self.agent = agent
+        self.depends_on = depends_on
+
+
+class Pipeline:
+    """Multi-agent pipeline with dependency resolution.
+
+    Args:
+        llm: The LLM provider for all agents.
+
+    Usage:
+        pipe = Pipeline(llm=llm)
+        pipe.add(researcher)
+        pipe.add(writer, depends_on=["researcher"])
+        result = await pipe.run("AI in Healthcare")
+    """
+
+    def __init__(self, llm: LLM):
+        self._llm = llm
+        self._nodes: list[_PipelineNode] = []
+        self._agent_names: set[str] = set()
+
+    def add(self, agent: AgentLike, depends_on: list[str] | None = None) -> "Pipeline":
+        """Add an agent to the pipeline.
+
+        Args:
+            agent: An @Agent-decorated function or BaseAgent subclass instance.
+            depends_on: List of agent names this agent depends on.
+
+        Returns:
+            self (for chaining).
+        """
+        name = agent.name
+        if name in self._agent_names:
+            raise PipelineError(f"Duplicate agent name: '{name}'")
+
+        deps = depends_on or []
+        for dep in deps:
+            if dep not in self._agent_names:
+                raise PipelineError(
+                    f"Agent '{name}' depends on '{dep}', but '{dep}' hasn't been added yet"
+                )
+
+        self._nodes.append(_PipelineNode(agent, deps))
+        self._agent_names.add(name)
+        return self
+
+    def _resolve_order(self) -> list[_PipelineNode]:
+        """Topological sort of the pipeline graph."""
+        resolved: list[_PipelineNode] = []
+        seen: set[str] = set()
+        node_map = {n.agent.name: n for n in self._nodes}
+
+        def visit(name: str) -> None:
+            if name in seen:
+                return
+            node = node_map[name]
+            for dep in node.depends_on:
+                if dep not in seen:
+                    visit(dep)
+            seen.add(name)
+            resolved.append(node)
+
+        for node in self._nodes:
+            visit(node.agent.name)
+
+        return resolved
+
+    async def run(self, task: str) -> PipelineResult:
+        """Execute the pipeline sequentially.
+
+        Args:
+            task: The task string passed to each agent.
+
+        Returns:
+            PipelineResult with all agent results.
+        """
+        ordered = self._resolve_order()
+        results: dict[str, AgentResult] = {}
+        context: dict[str, str] = {}
+
+        for node in ordered:
+            agent = node.agent
+            result = await agent.execute(task, context, self._llm)
+            results[agent.name] = result
+            context[agent.name] = result.output
+
+        last_output = results[ordered[-1].agent.name].output if ordered else ""
+        total_tokens = sum(r.tokens_used for r in results.values())
+        total_duration = sum(r.duration for r in results.values())
+
+        return PipelineResult(
+            output=last_output,
+            results=results,
+            total_tokens=total_tokens,
+            total_duration=round(total_duration, 3),
+        )
+
+    async def stream(self, task: str) -> AsyncGenerator[Event, None]:
+        """Execute the pipeline and yield events.
+
+        Yields Event objects as agents start, complete, or error.
+        The final event has type "pipeline_complete".
+        """
+        emitter = EventEmitter()
+        ordered = self._resolve_order()
+        results: dict[str, AgentResult] = {}
+        context: dict[str, str] = {}
+
+        async def _run() -> None:
+            try:
+                for node in ordered:
+                    agent = node.agent
+                    emitter.emit("agent_start", agent=agent.name, role=agent.role)
+
+                    try:
+                        result = await agent.execute(task, context, self._llm)
+                        results[agent.name] = result
+                        context[agent.name] = result.output
+                        emitter.emit(
+                            "agent_complete",
+                            agent=agent.name,
+                            tokens=result.tokens_used,
+                            duration=result.duration,
+                            output_preview=result.output[:200],
+                        )
+                    except AgentError as e:
+                        emitter.emit("agent_error", agent=agent.name, error=str(e))
+                        raise
+
+                total_tokens = sum(r.tokens_used for r in results.values())
+                total_duration = sum(r.duration for r in results.values())
+                emitter.emit(
+                    "pipeline_complete",
+                    total_tokens=total_tokens,
+                    total_duration=round(total_duration, 3),
+                    agents_completed=len(results),
+                )
+            except Exception as e:
+                emitter.emit("pipeline_error", error=str(e))
+            finally:
+                emitter.done()
+
+        run_task = asyncio.create_task(_run())
+
+        async for event in emitter.stream():
+            yield event
+
+        await run_task

agentflow/types.py

@@ -0,0 +1,40 @@
+"""Core data models for agentflow."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class AgentResult(BaseModel):
+    """Result from a single agent execution."""
+
+    agent: str
+    output: str
+    tokens_used: int = 0
+    duration: float = 0.0
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class PipelineResult(BaseModel):
+    """Result from a full pipeline execution."""
+
+    output: str  # Last agent's output
+    results: dict[str, AgentResult] = Field(default_factory=dict)
+    total_tokens: int = 0
+    total_duration: float = 0.0
+
+    def get(self, agent_name: str) -> AgentResult | None:
+        """Get a specific agent's result."""
+        return self.results.get(agent_name)
+
+
+class Event(BaseModel):
+    """Pipeline event for streaming."""
+
+    type: str  # agent_start, agent_complete, agent_error, pipeline_complete
+    agent: str = ""
+    data: dict[str, Any] = Field(default_factory=dict)
+    timestamp: str = Field(default_factory=lambda: datetime.now(timezone.utc).isoformat())

agentflowkit-0.1.0.dist-info/METADATA

@@ -0,0 +1,177 @@
+Metadata-Version: 2.4
+Name: agentflowkit
+Version: 0.1.0
+Summary: Lightweight multi-agent AI pipeline framework with decorator-based API
+Project-URL: Homepage, https://github.com/KaramQ6/agentflow
+Project-URL: Repository, https://github.com/KaramQ6/agentflow
+Author: KaramQ6
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,ai,async,llm,multi-agent,pipeline
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: openai>=1.0.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# agentflow
+
+[![PyPI version](https://badge.fury.io/py/agentflow-py.svg)](https://pypi.org/project/agentflow-py/)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
+
+Lightweight multi-agent AI pipeline framework. Define agents with decorators, wire them into pipelines, stream events in real-time.
+
+- **Decorator-based** - Define agents as simple async functions
+- **Async-first** - Built on asyncio, no sync bottlenecks
+- **Event streaming** - Real-time pipeline monitoring via async generators
+- **Provider agnostic** - Works with any OpenAI-compatible API (OpenAI, Groq, Together, Ollama, etc.)
+- **Minimal deps** - Just `openai` + `pydantic`
+
+## Install
+
+```bash
+pip install agentflow-py
+```
+
+## Quick Start
+
+```python
+import asyncio
+from agentflow import Agent, Pipeline, LLM
+
+# 1. Configure LLM (any OpenAI-compatible provider)
+llm = LLM(
+    model="llama-3.3-70b-versatile",
+    base_url="https://api.groq.com/openai/v1",
+    api_key="your-api-key",
+)
+
+# 2. Define agents with decorators
+@Agent(name="researcher", role="Research Analyst")
+async def researcher(task: str, context: dict) -> str:
+    return f"Research this topic thoroughly: {task}"
+
+@Agent(name="writer", role="Content Writer")
+async def writer(task: str, context: dict) -> str:
+    research = context["researcher"]
+    return f"Write an article based on:\n{research}"
+
+# 3. Build pipeline
+pipe = Pipeline(llm=llm)
+pipe.add(researcher)
+pipe.add(writer, depends_on=["researcher"])
+
+# 4. Run
+async def main():
+    result = await pipe.run("AI in Healthcare")
+    print(result.output)
+    print(f"Tokens: {result.total_tokens}")
+
+asyncio.run(main())
+```
+
+## Event Streaming
+
+Stream real-time events as agents execute:
+
+```python
+async for event in pipe.stream("AI in Healthcare"):
+    if event.type == "agent_start":
+        print(f"{event.agent} started...")
+    elif event.type == "agent_complete":
+        print(f"{event.agent} done ({event.data['tokens']} tokens)")
+    elif event.type == "pipeline_complete":
+        print(f"Total: {event.data['total_tokens']} tokens")
+```
+
+## Pipeline Results
+
+Access individual agent results:
+
+```python
+result = await pipe.run("AI in Healthcare")
+
+# Final output (last agent)
+print(result.output)
+
+# Individual agent results
+research = result.get("researcher")
+print(research.output)
+print(research.tokens_used)
+print(research.duration)
+
+# Totals
+print(result.total_tokens)
+print(result.total_duration)
+```
+
+## Advanced: Class-Based Agents
+
+For complex agents that need custom logic:
+
+```python
+from agentflow import BaseAgent, AgentResult
+
+class CustomAgent(BaseAgent):
+    def __init__(self):
+        super().__init__(name="custom", role="Custom Processor")
+
+    async def execute(self, task, context, llm):
+        # Custom logic here
+        response = await llm.generate([
+            {"role": "system", "content": f"You are a {self.role}."},
+            {"role": "user", "content": task},
+        ])
+        return AgentResult(
+            agent=self.name,
+            output=response["content"],
+            tokens_used=response["tokens"],
+            duration=response["duration"],
+        )
+
+pipe.add(CustomAgent())
+```
+
+## Supported Providers
+
+Any OpenAI-compatible API works:
+
+```python
+# OpenAI
+llm = LLM(model="gpt-4o-mini", api_key="sk-...")
+
+# Groq (free tier)
+llm = LLM(model="llama-3.3-70b-versatile",
+           base_url="https://api.groq.com/openai/v1",
+           api_key="gsk_...")
+
+# Ollama (local)
+llm = LLM(model="llama3", base_url="http://localhost:11434/v1")
+
+# Together AI
+llm = LLM(model="meta-llama/Llama-3-70b-chat-hf",
+           base_url="https://api.together.xyz/v1",
+           api_key="...")
+```
+
+## Examples
+
+- [`examples/research_crew.py`](examples/research_crew.py) - Multi-agent research pipeline
+- [`examples/code_reviewer.py`](examples/code_reviewer.py) - AI code review pipeline
+
+## License
+
+MIT

agentflowkit-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+agentflow/__init__.py,sha256=rcexChol8voXcAacVHhd9oaThKS0cZEPZk3iQV3ZAUo,563
+agentflow/agent.py,sha256=Gy5oLL-tD3ep7rLsWX_tiRzCvdwcymZhBJIAUcDU6Vw,2893
+agentflow/events.py,sha256=i_rVWlg4r2v3pU46Aupv1NLJb_4c-PkXJKL0cc5MkgI,933
+agentflow/exceptions.py,sha256=oNmZALxuHE0YqwAL6BXLlGRj_Sw4LAvxnhjgd3FEC90,551
+agentflow/llm.py,sha256=R-UAYae9eNG_YkpkqChGVOGzmOs7pxWTWjKM9mlUDnE,3048
+agentflow/pipeline.py,sha256=61fIeKEMsD_shFOebfLUzXWkg9EsmP8564XvLonS5sA,5552
+agentflow/types.py,sha256=VLa-e_Bq_G0LEqFjPI3nl_59tmam06QlPVPJo2TilZA,1105
+agentflowkit-0.1.0.dist-info/METADATA,sha256=9DeoONIEqtFf6QX88rSLsU3fQ0kLkbC416l4qJjglvk,5101
+agentflowkit-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+agentflowkit-0.1.0.dist-info/licenses/LICENSE,sha256=hRbBgprHDfoNgRcvsejDAkGyaR4XuKztjvO1ic93iK8,1064
+agentflowkit-0.1.0.dist-info/RECORD,,

agentflowkit-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

agentflowkit-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 KaramQ6
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.