aap-core 0.1.3.dev1__tar.gz → 0.3.0__tar.gz

aap_core-0.3.0/PKG-INFO

@@ -0,0 +1,200 @@
+Metadata-Version: 2.3
+Name: aap-core
+Version: 0.3.0
+Summary: Agent design pattern core framework
+Keywords: agent,ai,pattern,llm
+Author: Ly Hon Quang
+Author-email: Ly Hon Quang <lyhonquang@gmail.com>
+License: MIT
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Framework :: Pydantic :: 2
+Classifier: Operating System :: OS Independent
+Requires-Dist: a2a-sdk>=0.3.12
+Requires-Dist: gymnasium>=1.2.3
+Requires-Dist: nltk>=3.9.2
+Requires-Dist: pandas>=2.0.0
+Requires-Dist: rouge-score>=0.1.2
+Requires-Dist: sacrebleu>=2.5.1
+Requires-Dist: scipy>=1.15.3
+Requires-Dist: wandb>=0.27.0
+Requires-Dist: torch
+Requires-Dist: rensa>=0.4.0
+Requires-Dist: rbloom>=1.5.4
+Requires-Python: >=3.10.12
+Project-URL: Repository, https://github.com/quanghona/aap_core.git
+Description-Content-Type: text/markdown
+
+# aap_core
+
+Agent design pattern core framework for building, orchestrating, and training AI agents.
+
+![PyPI - License](https://img.shields.io/pypi/l/aap_core)
+![PyPI - Downloads](https://img.shields.io/pypi/dm/aap_core)
+![PyPI - Version](https://img.shields.io/pypi/v/aap_core?label=%20)
+![Python Version](https://img.shields.io/pypi/pyversions/aap_core)
+
+## What is this?
+
+`aap_core` is the foundational framework within the **AI Agent Pattern** project. It provides a unified abstraction layer for building AI agents, orchestrating multi-agent workflows, and training policies via reinforcement learning — all built on Pydantic and compatible with the [A2A protocol](https://github.com/google/a2a-sdk).
+
+The framework separates orchestration logic from LLM manipulation, delegating model interaction to integration packages (`aap_langchain`, `aap_llamaindex`, `aap_dspy`, `aap_transformers`). This lets you swap backends without changing agent architecture.
+
+## Quick Start
+
+```bash
+pip install aap_core
+# or
+uv add aap_core
+```
+
+```python
+from a2a.types import AgentCard
+from aap_core.agent import BaseAgent
+from aap_core.types import AgentMessage
+
+# Define a minimal agent
+class MyAgent(BaseAgent):
+    card: AgentCard = AgentCard(
+        name="my-agent",
+        description="A simple agent",
+        skills=[],
+    )
+
+    def execute(self, message: AgentMessage, **kwargs) -> AgentMessage:
+        # Your agent logic here
+        message.responses = [("my-agent", "Hello!")]
+        message.execution_result = "success"
+        return message
+```
+
+## Features
+
+- **Agent Abstraction**: Clean `BaseAgent` interface with A2A `AgentCard` integration for self-describing agent metadata
+- **Orchestration Patterns**: Built-in agents for reflection, looping, voting, coordination, and debate patterns
+- **Chain System**: Generic multi-turn causal chains with history management, tool processing, and token tracking
+- **Prompt Augmentation**: Data and structure-based prompt enhancement with configurable looping strategies
+- **Retrieval System**: Pluggable retrievers with post-processing (e.g., rerankers, summarizers)
+- **RL Policy Training**: Full RL loop with replay buffers, exploration modules, and trainers (PPO, DPO, GRPO, Reinforce++), powered by Gymnasium
+- **Thought Chains**: Chain-of-Thought, Tree-of-Thought, Graph-of-Thought, and Self-Consistency patterns
+- **Guardrails**: Extensible guardrail system for input/output filtering
+- **Async Support**: All agent execution methods have async counterparts (`aexecute`)
+- **Token Usage Tracking**: Automatic token accounting across multi-agent chains
+
+## Installation
+
+### Core
+
+```bash
+pip install aap_core
+```
+
+### Integration Packages
+
+```bash
+pip install aap_langchain   # LangChain integration
+pip install aap_llamaindex  # LlamaIndex integration
+pip install aap_dspy        # DSPy integration
+pip install aap_transformers  # Hugging Face Transformers integration
+```
+
+## Usage
+
+### Building an Agent
+
+```python
+from aap_core.agent import BaseAgent
+from aap_core.types import AgentMessage
+from a2a.types import AgentCard
+
+class TaskAgent(BaseAgent):
+    def execute(self, message: AgentMessage, **kwargs) -> AgentMessage:
+        self.state = "running"
+        # Process the message...
+        message.responses = [(self.card.name, "Task completed")]
+        message.execution_result = "success"
+        self.state = "idle"
+        return message
+```
+
+### Using Orchestration Patterns
+
+```python
+from aap_core.orchestration import ReflectionAgent, LoopAgent
+
+# Self-reflection: execute then reflect on the result
+reflector = ReflectionAgent(
+    chain_task=my_chain,
+    chain_reflection=reflection_chain,
+)
+result = reflector.execute(message)
+
+# Loop until a condition is met
+stopper = lambda msg: "done" in msg.query.lower()
+loop = LoopAgent(agent=my_agent, stop_condition=stopper)
+result = loop.execute(message)
+```
+
+### Prompt Augmentation
+
+```python
+from aap_core.prompt_augmenter import SimplePromptAugmenter
+
+# Augment prompts with external context data
+augmenter = SimplePromptAugmenter(
+    format="Context:\n{context}\n\nQuery: {query}",
+    loop=3,  # Apply 3 times
+)
+augmented = augmenter(message)
+```
+
+### RL-Based Prompt Optimization
+
+```python
+from aap_core.policy_trainer import PPOTrainer, SimpleReplayBuffer
+from aap_core.prompt_augmenter import PromptOptimizationEnv
+
+# Create the environment with multiple augmenters
+env = PromptOptimizationEnv(augmenters=[augmenter_a, augmenter_b])
+
+# Create a replay buffer and trainer
+buffer = SimpleReplayBuffer(capacity=10000)
+trainer = PPOTrainer(policy=my_policy, buffer=buffer)
+trainer.train(env, num_steps=10000)
+```
+
+## Architecture
+
+`aap_core` is organized into the following modules:
+
+| Module | Description |
+|--------|-------------|
+| `agent` | Base agent interface with A2A `AgentCard` support and state management |
+| `orchestration` | Multi-agent patterns: reflection, looping, voting, coordination, debate |
+| `chain` | Generic multi-turn causal chains with history, tool processing, and token tracking |
+| `policy` | RL policy models (GPT-2 based) with RMSNorm, RoPE, and GQA |
+| `policy_trainer` | Replay buffers, exploration modules, and trainers (PPO, DPO, GRPO, Reinforce++) |
+| `prompt_augmenter` | Data and structure-based prompt enhancement with Gymnasium environments |
+| `retriever` | Pluggable retrieval system with post-processing support |
+| `thought` | Thought chain patterns: CoT, ToT, GoT, Self-Consistency |
+| `guardrail` | Input/output filtering system |
+| `types` | Core type definitions: `AgentMessage`, `TokenUsage`, `BaseLLMChain`, `BaseChain` |
+| `utils` | Utility functions (e.g., thinking tag removal) |
+
+## Documentation
+
+- Full project documentation: [aap_core docs](https://github.com/quanghona/aap_core)
+- Example notebooks: [example](https://github.com/quanghona/aap_example.git)
+- A2A Protocol: [google/a2a-sdk](https://github.com/google/a2a-sdk)
+
+## Contributing
+
+See the [main project README](https://github.com/quanghona/aap_core) for contribution guidelines.
+
+## License
+
+This project is licensed under the MIT License — see the [LICENSE](https://github.com/quanghona/aap_core/blob/master/LICENSE) file for details.

aap_core-0.3.0/README.md

@@ -0,0 +1,169 @@
+# aap_core
+
+Agent design pattern core framework for building, orchestrating, and training AI agents.
+
+![PyPI - License](https://img.shields.io/pypi/l/aap_core)
+![PyPI - Downloads](https://img.shields.io/pypi/dm/aap_core)
+![PyPI - Version](https://img.shields.io/pypi/v/aap_core?label=%20)
+![Python Version](https://img.shields.io/pypi/pyversions/aap_core)
+
+## What is this?
+
+`aap_core` is the foundational framework within the **AI Agent Pattern** project. It provides a unified abstraction layer for building AI agents, orchestrating multi-agent workflows, and training policies via reinforcement learning — all built on Pydantic and compatible with the [A2A protocol](https://github.com/google/a2a-sdk).
+
+The framework separates orchestration logic from LLM manipulation, delegating model interaction to integration packages (`aap_langchain`, `aap_llamaindex`, `aap_dspy`, `aap_transformers`). This lets you swap backends without changing agent architecture.
+
+## Quick Start
+
+```bash
+pip install aap_core
+# or
+uv add aap_core
+```
+
+```python
+from a2a.types import AgentCard
+from aap_core.agent import BaseAgent
+from aap_core.types import AgentMessage
+
+# Define a minimal agent
+class MyAgent(BaseAgent):
+    card: AgentCard = AgentCard(
+        name="my-agent",
+        description="A simple agent",
+        skills=[],
+    )
+
+    def execute(self, message: AgentMessage, **kwargs) -> AgentMessage:
+        # Your agent logic here
+        message.responses = [("my-agent", "Hello!")]
+        message.execution_result = "success"
+        return message
+```
+
+## Features
+
+- **Agent Abstraction**: Clean `BaseAgent` interface with A2A `AgentCard` integration for self-describing agent metadata
+- **Orchestration Patterns**: Built-in agents for reflection, looping, voting, coordination, and debate patterns
+- **Chain System**: Generic multi-turn causal chains with history management, tool processing, and token tracking
+- **Prompt Augmentation**: Data and structure-based prompt enhancement with configurable looping strategies
+- **Retrieval System**: Pluggable retrievers with post-processing (e.g., rerankers, summarizers)
+- **RL Policy Training**: Full RL loop with replay buffers, exploration modules, and trainers (PPO, DPO, GRPO, Reinforce++), powered by Gymnasium
+- **Thought Chains**: Chain-of-Thought, Tree-of-Thought, Graph-of-Thought, and Self-Consistency patterns
+- **Guardrails**: Extensible guardrail system for input/output filtering
+- **Async Support**: All agent execution methods have async counterparts (`aexecute`)
+- **Token Usage Tracking**: Automatic token accounting across multi-agent chains
+
+## Installation
+
+### Core
+
+```bash
+pip install aap_core
+```
+
+### Integration Packages
+
+```bash
+pip install aap_langchain   # LangChain integration
+pip install aap_llamaindex  # LlamaIndex integration
+pip install aap_dspy        # DSPy integration
+pip install aap_transformers  # Hugging Face Transformers integration
+```
+
+## Usage
+
+### Building an Agent
+
+```python
+from aap_core.agent import BaseAgent
+from aap_core.types import AgentMessage
+from a2a.types import AgentCard
+
+class TaskAgent(BaseAgent):
+    def execute(self, message: AgentMessage, **kwargs) -> AgentMessage:
+        self.state = "running"
+        # Process the message...
+        message.responses = [(self.card.name, "Task completed")]
+        message.execution_result = "success"
+        self.state = "idle"
+        return message
+```
+
+### Using Orchestration Patterns
+
+```python
+from aap_core.orchestration import ReflectionAgent, LoopAgent
+
+# Self-reflection: execute then reflect on the result
+reflector = ReflectionAgent(
+    chain_task=my_chain,
+    chain_reflection=reflection_chain,
+)
+result = reflector.execute(message)
+
+# Loop until a condition is met
+stopper = lambda msg: "done" in msg.query.lower()
+loop = LoopAgent(agent=my_agent, stop_condition=stopper)
+result = loop.execute(message)
+```
+
+### Prompt Augmentation
+
+```python
+from aap_core.prompt_augmenter import SimplePromptAugmenter
+
+# Augment prompts with external context data
+augmenter = SimplePromptAugmenter(
+    format="Context:\n{context}\n\nQuery: {query}",
+    loop=3,  # Apply 3 times
+)
+augmented = augmenter(message)
+```
+
+### RL-Based Prompt Optimization
+
+```python
+from aap_core.policy_trainer import PPOTrainer, SimpleReplayBuffer
+from aap_core.prompt_augmenter import PromptOptimizationEnv
+
+# Create the environment with multiple augmenters
+env = PromptOptimizationEnv(augmenters=[augmenter_a, augmenter_b])
+
+# Create a replay buffer and trainer
+buffer = SimpleReplayBuffer(capacity=10000)
+trainer = PPOTrainer(policy=my_policy, buffer=buffer)
+trainer.train(env, num_steps=10000)
+```
+
+## Architecture
+
+`aap_core` is organized into the following modules:
+
+| Module | Description |
+|--------|-------------|
+| `agent` | Base agent interface with A2A `AgentCard` support and state management |
+| `orchestration` | Multi-agent patterns: reflection, looping, voting, coordination, debate |
+| `chain` | Generic multi-turn causal chains with history, tool processing, and token tracking |
+| `policy` | RL policy models (GPT-2 based) with RMSNorm, RoPE, and GQA |
+| `policy_trainer` | Replay buffers, exploration modules, and trainers (PPO, DPO, GRPO, Reinforce++) |
+| `prompt_augmenter` | Data and structure-based prompt enhancement with Gymnasium environments |
+| `retriever` | Pluggable retrieval system with post-processing support |
+| `thought` | Thought chain patterns: CoT, ToT, GoT, Self-Consistency |
+| `guardrail` | Input/output filtering system |
+| `types` | Core type definitions: `AgentMessage`, `TokenUsage`, `BaseLLMChain`, `BaseChain` |
+| `utils` | Utility functions (e.g., thinking tag removal) |
+
+## Documentation
+
+- Full project documentation: [aap_core docs](https://github.com/quanghona/aap_core)
+- Example notebooks: [example](https://github.com/quanghona/aap_example.git)
+- A2A Protocol: [google/a2a-sdk](https://github.com/google/a2a-sdk)
+
+## Contributing
+
+See the [main project README](https://github.com/quanghona/aap_core) for contribution guidelines.
+
+## License
+
+This project is licensed under the MIT License — see the [LICENSE](https://github.com/quanghona/aap_core/blob/master/LICENSE) file for details.

{aap_core-0.1.3.dev1 → aap_core-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "aap_core"
-version = "0.1.3.dev1"
+version = "0.3.0"
 description = "Agent design pattern core framework"
 readme = "README.md"
 license = { text = "MIT" }
@@ -11,9 +11,16 @@ authors = [
 requires-python = ">=3.10.12"
 dependencies = [
     "a2a-sdk>=0.3.12",
+    "gymnasium>=1.2.3",
+    "nltk>=3.9.2",
     "pandas>=2.0.0",
     "rouge-score>=0.1.2",
     "sacrebleu>=2.5.1",
+    "scipy>=1.15.3",
+    "wandb>=0.27.0",
+    "torch",
+    "rensa>=0.4.0",
+    "rbloom>=1.5.4",
 ]
 classifiers = [
     "Programming Language :: Python :: 3.10",
@@ -27,9 +34,14 @@ classifiers = [
 ]
 
 [project.urls]
-Repository = "https://github.com/quanghona/agent_design_pattern.git"
+Repository = "https://github.com/quanghona/aap_core.git"
 
 [dependency-groups]
+dev = [
+    "pytest>=9.0.3",
+    "ruff>=0.14.0",
+    "pytest-cov>=7.1.0",
+]
 lint = [
     "ruff==0.14.0",
 ]

aap_core-0.3.0/src/aap_core/__init__.py

@@ -0,0 +1,23 @@
+from aap_core.policy_trainer import (
+    BaseExplorationModule,
+    BasePolicyTrainer,
+    DPOTrainer,
+    EpsilonGreedyExploration,
+    GRPOTrainer,
+    PPOTrainer,
+    RandomExploration,
+    ReinforcePPTrainer,
+    SimpleReplayBuffer,
+)
+
+__all__ = [
+    "BaseExplorationModule",
+    "BasePolicyTrainer",
+    "DPOTrainer",
+    "EpsilonGreedyExploration",
+    "GRPOTrainer",
+    "PPOTrainer",
+    "RandomExploration",
+    "ReinforcePPTrainer",
+    "SimpleReplayBuffer",
+]

{aap_core-0.1.3.dev1 → aap_core-0.3.0}/src/aap_core/agent.py

@@ -5,13 +5,15 @@ from typing import Any, Dict, Literal
 from a2a.types import AgentCard
 from pydantic import BaseModel, Field, PrivateAttr
 
-from .chain import BaseLLMChain
-from .types import AgentMessage
+from .types import AgentMessage, BaseLLMChain
 
 
 class BaseAgent(abc.ABC, BaseModel):
     """An interface for agent implementations."""
 
+    # a2a-sdk >= 1.0 exposes AgentCard as a protobuf message, not a pydantic model.
+    model_config = {"arbitrary_types_allowed": True}
+
     _state: str = PrivateAttr("idle")
     _composed_state: str = PrivateAttr("idle")
 

{aap_core-0.1.3.dev1 → aap_core-0.3.0}/src/aap_core/chain.py

@@ -9,28 +9,7 @@ from .prompt_augmenter import (
     BasePromptAugmenter,
     IdentityPromptAugmenter,
 )
-from .types import AgentMessage, BaseChain, ChainMessage, ChainResponse
-
-
-class BaseLLMChain(BaseChain):
-    """
-    Base class for LLM chains.
-    """
-
-    name: str = Field(
-        "chain",
-        description="The name of the chain. Should be same at agent who hold this chain for easy to operate.",
-    )
-
-    @abc.abstractmethod
-    def invoke(self, message: AgentMessage, **kwargs) -> AgentMessage:
-        pass
-
-    async def ainvoke(self, message: AgentMessage, **kwargs) -> AgentMessage:
-        return self.invoke(message, **kwargs)
-
-    def __call__(self, message: AgentMessage, **kwargs) -> AgentMessage:
-        return self.invoke(message, **kwargs)
+from .types import AgentMessage, BaseLLMChain, ChainMessage, ChainResponse, TokenUsage
 
 
 class BaseCausalMultiTurnsChain(BaseLLMChain, Generic[ChainMessage, ChainResponse]):
@@ -46,6 +25,10 @@ class BaseCausalMultiTurnsChain(BaseLLMChain, Generic[ChainMessage, ChainRespons
         default=False, description="store intermediate steps output"
     )
 
+    max_turns: int = Field(
+        default=50, description="maximum number of turns before stopping"
+    )
+
     def final_response_as_context(self, key: str) -> None:
         self._last_response_as_context = key.replace("context_", "")
 
@@ -56,7 +39,7 @@ class BaseCausalMultiTurnsChain(BaseLLMChain, Generic[ChainMessage, ChainRespons
     @abc.abstractmethod
     def _generate_response(
         self, conversation: List[ChainMessage], **kwargs
-    ) -> Tuple[List[ChainMessage], ChainResponse, bool]:
+    ) -> Tuple[List[ChainMessage], ChainResponse, bool, TokenUsage]:
         pass
 
     @abc.abstractmethod
@@ -74,14 +57,38 @@ class BaseCausalMultiTurnsChain(BaseLLMChain, Generic[ChainMessage, ChainRespons
         pass
 
     def invoke(self, message: AgentMessage, **kwargs) -> AgentMessage:
-        # Template method
+        if message.token_usage is None:
+            message.token_usage = {
+                "steps": [],
+                "total": TokenUsage(input_tokens=0, output_tokens=0, total_tokens=0),
+            }
+        if "steps" not in message.token_usage:
+            message.token_usage["steps"] = []
+        if "total" not in message.token_usage:
+            message.token_usage["total"] = TokenUsage(
+                input_tokens=0, output_tokens=0, total_tokens=0
+            )
+
+        def add_token(usage: TokenUsage):
+            message.token_usage["steps"].append(usage)  # type: ignore
+            message.token_usage["total"]["input_tokens"] += usage["input_tokens"]  # type: ignore
+            message.token_usage["total"]["output_tokens"] += usage["output_tokens"]  # type: ignore
+            message.token_usage["total"]["total_tokens"] += usage["total_tokens"]  # type: ignore
+
+        # Template method — ReAct loop: Thought → Act → Thought → ... → Final
         conversation = self._prepare_conversation(message)
-        conversation, response, has_tool = self._generate_response(
-            conversation, **kwargs
-        )
-        if has_tool:
+        turn = 0
+        while turn < self.max_turns:
+            conversation, response, has_tool, usage = self._generate_response(
+                conversation, **kwargs
+            )
+            add_token(usage)
+
+            if not has_tool:
+                break
+
             conversation = self._process_tools(conversation, response)
-            conversation, _, _ = self._generate_response(conversation, **kwargs)
+            turn += 1
 
         message = self._append_responses(message, conversation)
 
@@ -132,13 +139,3 @@ class TypicalLLMChain(BaseLLMChain):
         message = self.generate(message, **kwargs)
         message = self.output_guardrail(message)
         return message
-
-
-class MetaPromptAugmenter(BasePromptAugmenter):
-    """A prompt augmenter that use an LLM chain to rewrite the prompt."""
-
-    chain: BaseLLMChain = Field(..., description="LLM chain that rewrite the prompt")
-
-    def augment(self, message: AgentMessage, **kwargs) -> AgentMessage:
-        message = self.chain.invoke(message, **kwargs)
-        return message