agentflowkit 0.1.0__tar.gz

agentflowkit-0.1.0/.gitattributes

@@ -0,0 +1,2 @@
+# Auto detect text files and perform LF normalization
+* text=auto

agentflowkit-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+.env
+.pytest_cache/
+*.egg

agentflowkit-0.1.0/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.

agentflowkit-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,149 @@
+# 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/examples/code_reviewer.py

@@ -0,0 +1,77 @@
+"""Code reviewer example - AI code review pipeline.
+
+Run: python examples/code_reviewer.py
+
+Requires GROQ_API_KEY environment variable.
+"""
+
+import asyncio
+import os
+
+from agentflow import Agent, Pipeline, LLM
+
+
+llm = LLM(
+    model="llama-3.3-70b-versatile",
+    base_url="https://api.groq.com/openai/v1",
+    api_key=os.environ.get("GROQ_API_KEY", ""),
+)
+
+
+@Agent(name="analyzer", role="Code Analyzer")
+async def analyzer(task: str, context: dict) -> str:
+    return (
+        f"Analyze the following code for potential issues including bugs, "
+        f"security vulnerabilities, performance problems, and code smells. "
+        f"List each issue with its severity (critical/warning/info).\n\n"
+        f"Code:\n```\n{task}\n```"
+    )
+
+
+@Agent(name="suggester", role="Code Improvement Specialist")
+async def suggester(task: str, context: dict) -> str:
+    analysis = context["analyzer"]
+    return (
+        f"Based on the following code analysis, provide specific code "
+        f"improvements. For each issue found, show the exact fix with "
+        f"before/after code snippets.\n\n"
+        f"Original code:\n```\n{task}\n```\n\n"
+        f"Analysis:\n{analysis}"
+    )
+
+
+SAMPLE_CODE = '''
+def get_user(user_id):
+    query = f"SELECT * FROM users WHERE id = {user_id}"
+    result = db.execute(query)
+    data = result.fetchone()
+    password = data['password']
+    return {"id": data['id'], "name": data['name'], "password": password}
+'''
+
+
+async def main():
+    pipe = Pipeline(llm=llm)
+    pipe.add(analyzer)
+    pipe.add(suggester, depends_on=["analyzer"])
+
+    print("Code Review Pipeline")
+    print("=" * 60)
+
+    async for event in pipe.stream(SAMPLE_CODE.strip()):
+        if event.type == "agent_start":
+            print(f"\n>> {event.agent} reviewing...")
+        elif event.type == "agent_complete":
+            print(f"   Done ({event.data.get('tokens', 0)} tokens)")
+        elif event.type == "pipeline_complete":
+            print(f"\nReview complete in {event.data.get('total_duration', 0):.1f}s")
+
+    result = await pipe.run(SAMPLE_CODE.strip())
+    print(f"\n{'=' * 60}")
+    print("REVIEW RESULT:")
+    print("=" * 60)
+    print(result.output)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

agentflowkit-0.1.0/examples/research_crew.py

@@ -0,0 +1,85 @@
+"""Research crew example - multi-agent research pipeline.
+
+Run: python examples/research_crew.py
+
+Requires GROQ_API_KEY environment variable or replace the api_key below.
+"""
+
+import asyncio
+import os
+
+from agentflow import Agent, Pipeline, LLM
+
+
+# Configure LLM (Groq free tier)
+llm = LLM(
+    model="llama-3.3-70b-versatile",
+    base_url="https://api.groq.com/openai/v1",
+    api_key=os.environ.get("GROQ_API_KEY", ""),
+)
+
+
+@Agent(name="researcher", role="Research Analyst")
+async def researcher(task: str, context: dict) -> str:
+    return (
+        f"Research the following topic and provide a comprehensive analysis "
+        f"with key findings, statistics, and expert opinions:\n\n{task}"
+    )
+
+
+@Agent(name="writer", role="Content Writer")
+async def writer(task: str, context: dict) -> str:
+    research = context["researcher"]
+    return (
+        f"Based on the following research, write a well-structured article "
+        f"with an introduction, 3-4 main sections, and a conclusion.\n\n"
+        f"Topic: {task}\n\nResearch:\n{research}"
+    )
+
+
+@Agent(name="editor", role="Editor and Fact-Checker")
+async def editor(task: str, context: dict) -> str:
+    article = context["writer"]
+    return (
+        f"Review and improve the following article. Fix any issues with "
+        f"clarity, structure, grammar, and factual accuracy. Return the "
+        f"final polished version.\n\nArticle:\n{article}"
+    )
+
+
+async def main():
+    topic = "The Impact of Large Language Models on Software Development in 2025"
+
+    # Build pipeline
+    pipe = Pipeline(llm=llm)
+    pipe.add(researcher)
+    pipe.add(writer, depends_on=["researcher"])
+    pipe.add(editor, depends_on=["writer"])
+
+    print(f"Running research crew on: {topic}\n")
+    print("=" * 60)
+
+    # Stream events
+    async for event in pipe.stream(topic):
+        if event.type == "agent_start":
+            print(f"\n>> {event.agent} started...")
+        elif event.type == "agent_complete":
+            tokens = event.data.get("tokens", 0)
+            duration = event.data.get("duration", 0)
+            print(f"   {event.agent} done ({tokens} tokens, {duration:.1f}s)")
+        elif event.type == "pipeline_complete":
+            print(f"\n{'=' * 60}")
+            print(f"Pipeline complete!")
+            print(f"  Total tokens: {event.data.get('total_tokens', 0)}")
+            print(f"  Total time: {event.data.get('total_duration', 0):.1f}s")
+
+    # Also run without streaming to get the result
+    result = await pipe.run(topic)
+    print(f"\n{'=' * 60}")
+    print("FINAL ARTICLE:")
+    print("=" * 60)
+    print(result.output[:2000])  # Print first 2000 chars
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

agentflowkit-0.1.0/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "agentflowkit"
+version = "0.1.0"
+description = "Lightweight multi-agent AI pipeline framework with decorator-based API"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{ name = "KaramQ6" }]
+keywords = ["ai", "agents", "multi-agent", "llm", "pipeline", "async"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Framework :: AsyncIO",
+]
+dependencies = [
+    "openai>=1.0.0",
+    "pydantic>=2.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "build",
+]
+
+[project.urls]
+Homepage = "https://github.com/KaramQ6/agentflow"
+Repository = "https://github.com/KaramQ6/agentflow"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/agentflow"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

agentflowkit-0.1.0/src/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",
+]

agentflowkit-0.1.0/src/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)