grasp_agents 0.1.15__tar.gz → 0.1.17__tar.gz

grasp_agents-0.1.17/PKG-INFO

@@ -0,0 +1,212 @@
+Metadata-Version: 2.4
+Name: grasp_agents
+Version: 0.1.17
+Summary: Grasp Agents Library
+License-File: LICENSE.md
+Requires-Python: <4,>=3.11.4
+Requires-Dist: dotenv>=0.9.9
+Requires-Dist: httpx<1,>=0.27.0
+Requires-Dist: openai<2,>=1.68.2
+Requires-Dist: pydantic>=2
+Requires-Dist: pyyaml>=6.0.2
+Requires-Dist: tenacity>=9.1.2
+Requires-Dist: termcolor<3,>=2.4.0
+Requires-Dist: tqdm<5,>=4.66.2
+Description-Content-Type: text/markdown
+
+# Grasp Agents
+
+<br/>
+<img src="./.assets/grasp.svg" alt="Grasp Agents" width="320" />
+<br/>
+<br/>
+
+[![PyPI version](https://badge.fury.io/py/grasp_agents.svg)](https://badge.fury.io/py/grasp-agents)
+[![License: MIT](https://img.shields.io/badge/license-MIT-yellow?style=flat-square)](https://mit-license.org/)
+[![PyPI downloads](https://img.shields.io/pypi/dm/grasp-agents?style=flat-square)](https://pypi.org/project/grasp-agents/)
+[![GitHub Stars](https://img.shields.io/github/stars/grasp-technologies/grasp-agents?style=social)](https://github.com/grasp-technologies/grasp-agents/stargazers)
+[![GitHub Forks](https://img.shields.io/github/forks/grasp-technologies/grasp-agents?style=social)](https://github.com/grasp-technologies/grasp-agents/network/members)
+
+## Overview
+
+**Grasp Agents** is a modular Python framework for building agentic AI pipelines and applications. It is meant to be minimalistic but functional, allowing for rapid experimentation while keeping full and granular low-level control over prompting, LLM handling, and inter-agent communication by avoiding excessive higher-level abstractions.
+
+## Features
+
+- Clean formulation of agents as generic entities over:
+    * I/O schemas
+    * Agent state
+    * Shared context
+- Transparent implementation of common agentic patterns:
+    * Single-agent loops with an optional "ReAct mode" to enforce reasoning between the tool calls
+    * Workflows (static communication topology), including loops
+    * Agents-as-tools for task delegation
+    * Freeform A2A communication via in-process Actor model
+- Batch processing support outside of agentic loops
+- Simple logging and usage/cost tracking
+
+## Project Structure
+
+- `base_agent.py`, `llm_agent.py`, `comm_agent.py`: Core agent class implementations.
+- `agent_message.py`, `agent_message_pool.py`: Messaging and message pool management.
+- `llm_agent_state.py`: State management for LLM agents.
+- `tool_orchestrator.py`: Orchestration of tools used by agents.
+- `prompt_builder.py`: Tools for constructing prompts.
+- `workflow/`: Modules for defining and managing agent workflows.
+- `cloud_llm.py`, `llm.py`: LLM integration and base LLM functionalities.
+- `openai/`: Modules specific to OpenAI API integration.    
+- `memory.py`: Memory management for agents (currently only message history).
+- `run_context.py`: Context management for agent runs.
+- `usage_tracker.py`: Tracking of API usage and costs.
+- `costs_dict.yaml`: Dictionary for cost tracking (update if needed).
+- `rate_limiting/`: Basic rate limiting tools.
+
+## Quickstart & Installation Variants (UV Package manager)
+
+> **Note:** You can check this sample project code in the [src/grasp_agents/examples/demo/uv](src/grasp_agents/examples/demo/uv) folder. Feel free to copy and paste the code from there to a separate project. There are also [examples](src/grasp_agents/examples/demo/) for other package managers.
+
+#### 1. Prerequisites
+
+Install the [UV Package Manager](https://github.com/astral-sh/uv):
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+#### 2. Create Project & Install Dependencies
+
+```bash
+mkdir my-test-uv-app
+cd my-test-uv-app
+uv init .
+```
+
+Create and activate a virtual environment:
+
+```bash
+uv venv
+source .venv/bin/activate
+```
+
+Add and sync dependencies:
+
+```bash
+uv add grasp_agents
+uv sync
+```
+
+#### 3. Example Usage
+
+Ensure you have a `.env` file with your OpenAI and Google AI Studio API keys set
+
+```
+OPENAI_API_KEY=your_openai_api_key
+GOOGLE_AI_STUDIO_API_KEY=your_google_ai_studio_api_key
+```
+
+Create a script, e.g., `problem_recommender.py`:
+
+```python
+import re
+from typing import Any
+from pathlib import Path
+from pydantic import BaseModel, Field
+from dotenv import load_dotenv
+from grasp_agents.typing.tool import BaseTool
+from grasp_agents.typing.io import AgentPayload
+from grasp_agents.run_context import RunContextWrapper
+from grasp_agents.openai.openai_llm import OpenAILLM, OpenAILLMSettings
+from grasp_agents.llm_agent import LLMAgent
+from grasp_agents.grasp_logging import setup_logging
+from grasp_agents.typing.message import Conversation
+
+load_dotenv()
+
+
+# Configure the logger to output to the console and/or a file
+setup_logging(
+    logs_file_path="grasp_agents_demo.log",
+    logs_config_path=Path().cwd() / "configs/logging/default.yaml",
+)
+
+sys_prompt_react = """
+Your task is to suggest an exciting stats problem to a student. 
+Ask the student about their education, interests, and preferences, then suggest a problem tailored to them. 
+
+# Instructions
+* Ask questions one by one.
+* Provide your thinking before asking a question and after receiving a reply.
+* The problem must be enclosed in <PROBLEM> tags.
+"""
+
+
+class TeacherQuestion(BaseModel):
+    question: str = Field(..., description="The question to ask the student.")
+
+StudentReply = str
+
+
+class AskStudentTool(BaseTool[TeacherQuestion, StudentReply, Any]):
+    name: str = "ask_student_tool"
+    description: str = "Ask the student a question and get their reply."
+    in_schema: type[TeacherQuestion] = TeacherQuestion
+    out_schema: type[StudentReply] = StudentReply
+
+    async def run(
+        self, inp: TeacherQuestion, ctx: RunContextWrapper[Any] | None = None
+    ) -> StudentReply:
+        return input(inp.question)
+
+
+class FinalResponse(AgentPayload):
+    problem: str
+
+
+teacher = LLMAgent[Any, FinalResponse, None](
+    agent_id="teacher",
+    llm=OpenAILLM(
+        model_name="gpt-4.1",
+        api_provider="openai",
+        llm_settings=OpenAILLMSettings(temperature=0.1),
+    ),
+    tools=[AskStudentTool()],
+    max_turns=20,
+    react_mode=True,
+    sys_prompt=sys_prompt_react,
+    out_schema=FinalResponse,
+    set_state_strategy="reset",
+)
+
+
+@teacher.tool_call_loop_exit_handler
+def exit_tool_call_loop(conversation: Conversation, ctx, **kwargs) -> None:
+    message_text = conversation[-1].content
+
+    return re.search(r"<PROBLEM>", message_text)
+
+
+@teacher.parse_output_handler
+def parse_output(conversation: Conversation, ctx, **kwargs) -> FinalResponse:
+    message_text = conversation[-1].content
+    matches = re.findall(r"<PROBLEM>(.*?)</PROBLEM>", message_text, re.DOTALL)
+
+    return FinalResponse(problem=matches[0])
+
+
+async def main():
+    ctx = RunContextWrapper(print_messages=True)
+    out = await teacher.run(ctx=ctx)
+    print(out.payloads[0].problem)
+    print(ctx.usage_tracker.total_usage)
+
+
+asyncio.run(main())
+```
+
+Run your script:
+
+```bash
+uv run problem_recommender.py
+```
+
+You can find more examples in [src/grasp_agents/examples/notebooks/agents_demo.ipynb](src/grasp_agents/examples/notebooks/agents_demo.ipynb).

grasp_agents-0.1.17/README.md

@@ -0,0 +1,196 @@
+# Grasp Agents
+
+<br/>
+<img src="./.assets/grasp.svg" alt="Grasp Agents" width="320" />
+<br/>
+<br/>
+
+[![PyPI version](https://badge.fury.io/py/grasp_agents.svg)](https://badge.fury.io/py/grasp-agents)
+[![License: MIT](https://img.shields.io/badge/license-MIT-yellow?style=flat-square)](https://mit-license.org/)
+[![PyPI downloads](https://img.shields.io/pypi/dm/grasp-agents?style=flat-square)](https://pypi.org/project/grasp-agents/)
+[![GitHub Stars](https://img.shields.io/github/stars/grasp-technologies/grasp-agents?style=social)](https://github.com/grasp-technologies/grasp-agents/stargazers)
+[![GitHub Forks](https://img.shields.io/github/forks/grasp-technologies/grasp-agents?style=social)](https://github.com/grasp-technologies/grasp-agents/network/members)
+
+## Overview
+
+**Grasp Agents** is a modular Python framework for building agentic AI pipelines and applications. It is meant to be minimalistic but functional, allowing for rapid experimentation while keeping full and granular low-level control over prompting, LLM handling, and inter-agent communication by avoiding excessive higher-level abstractions.
+
+## Features
+
+- Clean formulation of agents as generic entities over:
+    * I/O schemas
+    * Agent state
+    * Shared context
+- Transparent implementation of common agentic patterns:
+    * Single-agent loops with an optional "ReAct mode" to enforce reasoning between the tool calls
+    * Workflows (static communication topology), including loops
+    * Agents-as-tools for task delegation
+    * Freeform A2A communication via in-process Actor model
+- Batch processing support outside of agentic loops
+- Simple logging and usage/cost tracking
+
+## Project Structure
+
+- `base_agent.py`, `llm_agent.py`, `comm_agent.py`: Core agent class implementations.
+- `agent_message.py`, `agent_message_pool.py`: Messaging and message pool management.
+- `llm_agent_state.py`: State management for LLM agents.
+- `tool_orchestrator.py`: Orchestration of tools used by agents.
+- `prompt_builder.py`: Tools for constructing prompts.
+- `workflow/`: Modules for defining and managing agent workflows.
+- `cloud_llm.py`, `llm.py`: LLM integration and base LLM functionalities.
+- `openai/`: Modules specific to OpenAI API integration.    
+- `memory.py`: Memory management for agents (currently only message history).
+- `run_context.py`: Context management for agent runs.
+- `usage_tracker.py`: Tracking of API usage and costs.
+- `costs_dict.yaml`: Dictionary for cost tracking (update if needed).
+- `rate_limiting/`: Basic rate limiting tools.
+
+## Quickstart & Installation Variants (UV Package manager)
+
+> **Note:** You can check this sample project code in the [src/grasp_agents/examples/demo/uv](src/grasp_agents/examples/demo/uv) folder. Feel free to copy and paste the code from there to a separate project. There are also [examples](src/grasp_agents/examples/demo/) for other package managers.
+
+#### 1. Prerequisites
+
+Install the [UV Package Manager](https://github.com/astral-sh/uv):
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+#### 2. Create Project & Install Dependencies
+
+```bash
+mkdir my-test-uv-app
+cd my-test-uv-app
+uv init .
+```
+
+Create and activate a virtual environment:
+
+```bash
+uv venv
+source .venv/bin/activate
+```
+
+Add and sync dependencies:
+
+```bash
+uv add grasp_agents
+uv sync
+```
+
+#### 3. Example Usage
+
+Ensure you have a `.env` file with your OpenAI and Google AI Studio API keys set
+
+```
+OPENAI_API_KEY=your_openai_api_key
+GOOGLE_AI_STUDIO_API_KEY=your_google_ai_studio_api_key
+```
+
+Create a script, e.g., `problem_recommender.py`:
+
+```python
+import re
+from typing import Any
+from pathlib import Path
+from pydantic import BaseModel, Field
+from dotenv import load_dotenv
+from grasp_agents.typing.tool import BaseTool
+from grasp_agents.typing.io import AgentPayload
+from grasp_agents.run_context import RunContextWrapper
+from grasp_agents.openai.openai_llm import OpenAILLM, OpenAILLMSettings
+from grasp_agents.llm_agent import LLMAgent
+from grasp_agents.grasp_logging import setup_logging
+from grasp_agents.typing.message import Conversation
+
+load_dotenv()
+
+
+# Configure the logger to output to the console and/or a file
+setup_logging(
+    logs_file_path="grasp_agents_demo.log",
+    logs_config_path=Path().cwd() / "configs/logging/default.yaml",
+)
+
+sys_prompt_react = """
+Your task is to suggest an exciting stats problem to a student. 
+Ask the student about their education, interests, and preferences, then suggest a problem tailored to them. 
+
+# Instructions
+* Ask questions one by one.
+* Provide your thinking before asking a question and after receiving a reply.
+* The problem must be enclosed in <PROBLEM> tags.
+"""
+
+
+class TeacherQuestion(BaseModel):
+    question: str = Field(..., description="The question to ask the student.")
+
+StudentReply = str
+
+
+class AskStudentTool(BaseTool[TeacherQuestion, StudentReply, Any]):
+    name: str = "ask_student_tool"
+    description: str = "Ask the student a question and get their reply."
+    in_schema: type[TeacherQuestion] = TeacherQuestion
+    out_schema: type[StudentReply] = StudentReply
+
+    async def run(
+        self, inp: TeacherQuestion, ctx: RunContextWrapper[Any] | None = None
+    ) -> StudentReply:
+        return input(inp.question)
+
+
+class FinalResponse(AgentPayload):
+    problem: str
+
+
+teacher = LLMAgent[Any, FinalResponse, None](
+    agent_id="teacher",
+    llm=OpenAILLM(
+        model_name="gpt-4.1",
+        api_provider="openai",
+        llm_settings=OpenAILLMSettings(temperature=0.1),
+    ),
+    tools=[AskStudentTool()],
+    max_turns=20,
+    react_mode=True,
+    sys_prompt=sys_prompt_react,
+    out_schema=FinalResponse,
+    set_state_strategy="reset",
+)
+
+
+@teacher.tool_call_loop_exit_handler
+def exit_tool_call_loop(conversation: Conversation, ctx, **kwargs) -> None:
+    message_text = conversation[-1].content
+
+    return re.search(r"<PROBLEM>", message_text)
+
+
+@teacher.parse_output_handler
+def parse_output(conversation: Conversation, ctx, **kwargs) -> FinalResponse:
+    message_text = conversation[-1].content
+    matches = re.findall(r"<PROBLEM>(.*?)</PROBLEM>", message_text, re.DOTALL)
+
+    return FinalResponse(problem=matches[0])
+
+
+async def main():
+    ctx = RunContextWrapper(print_messages=True)
+    out = await teacher.run(ctx=ctx)
+    print(out.payloads[0].problem)
+    print(ctx.usage_tracker.total_usage)
+
+
+asyncio.run(main())
+```
+
+Run your script:
+
+```bash
+uv run problem_recommender.py
+```
+
+You can find more examples in [src/grasp_agents/examples/notebooks/agents_demo.ipynb](src/grasp_agents/examples/notebooks/agents_demo.ipynb).

{grasp_agents-0.1.15 → grasp_agents-0.1.17}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "grasp_agents"
-version = "0.1.15"
+version = "0.1.17"
 description = "Grasp Agents Library"
 readme = "README.md"
 requires-python = ">=3.11.4,<4"
@@ -12,6 +12,7 @@ dependencies = [
     "tqdm>=4.66.2,<5",
     "dotenv>=0.9.9",
     "pyyaml>=6.0.2",
+    "pydantic>=2",
 ]
 
 [dependency-groups]
@@ -22,7 +23,6 @@ dev = [
     "ipywidgets>=8.0.4,<9",
     "widgetsnbextension>=4.0.5,<5",
     "types-cachetools>=5.0.1,<6",
-    "pydantic>=2",
     "pre-commit-uv>=4.1.4",
     "twine>=5.1.1,<6",
     "ruff>=0.11.8",

{grasp_agents-0.1.15 → grasp_agents-0.1.17}/src/grasp_agents/agent_message.py

@@ -4,7 +4,6 @@ from uuid import uuid4
 
 from pydantic import BaseModel, ConfigDict, Field
 
-# from .base_agent import StateT
 from .typing.io import AgentID, AgentPayload, AgentState
 
 _PayloadT = TypeVar("_PayloadT", bound=AgentPayload, covariant=True)  # noqa: PLC0105

{grasp_agents-0.1.15 → grasp_agents-0.1.17}/src/grasp_agents/base_agent.py

@@ -68,5 +68,5 @@ class BaseAgent(ABC, Generic[OutT, StateT, CtxT]):
     @abstractmethod
     def as_tool(
         self, tool_name: str, tool_description: str, tool_strict: bool = True
-    ) -> BaseTool[BaseModel, BaseModel, CtxT]:
+    ) -> BaseTool[BaseModel, Any, CtxT]:
         pass