grasp_agents 0.1.10

Grasp Agents Library

Grasp Agents

Overview

Grasp Agents is a modular Python framework for building agentic AI pipelines and applications. It provides reusable agent classes, message handling, LLM integration, memory, and orchestration utilities. The framework is designed for flexibility, composability, and clarity, enabling rapid prototyping and robust development of multi-agent systems.

Features

• Modular agent base classes
• Message and memory management
• LLM and tool orchestration
• Logging and usage tracking
• Extensible architecture

Project Structure

• src/grasp_agents/ — Core framework modules
  • base_agent.py, llm_agent.py, comm_agent.py: Agent classes
  • agent_message.py, agent_message_pool.py: Messaging
  • memory.py: Memory management
  • cloud_llm.py, llm.py: LLM integration
  • tool_orchestrator.py: Tool orchestration
  • usage_tracker.py, grasp_logging.py: Usage and logging
  • data_retrieval/, openai/, typing/, workflow/: Extensions and utilities
• configs/ — Configuration files
• data/ — Logs and datasets

Quickstart & Installation Variants

Option 1: UV Package Manager Project

Note: You can check this sample project code in the src/grasp_agents/examples/demo/uv folder. Feel free to copy and paste the code from there to a separate project.

1. Prerequisites

Install the UV Package Manager:

curl -LsSf https://astral.sh/uv/install.sh | sh

2. Create Project & Install Dependencies

mkdir my-test-uv-app
cd my-test-uv-app
uv init .

Create and activate a virtual environment:

uv venv
source .venv/bin/activate

Add and sync dependencies:

uv add grasp_agents
uv sync

3. Example Usage

Create a file, e.g., hello.py:

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

import asyncio
from typing import Any

from grasp_agents.llm_agent import LLMAgent
from grasp_agents.openai.openai_llm import (
    OpenAILLM,
    OpenAILLMSettings,
)
from grasp_agents.typing.io import (
    AgentPayload,
)
from grasp_agents.run_context import RunContextWrapper

from dotenv import load_dotenv

load_dotenv()

class Response(AgentPayload):
    response: str


chatbot = LLMAgent[Any, Response, None](
    agent_id="chatbot",
    llm=OpenAILLM(
        model_name="gpt-4o",
        llm_settings=OpenAILLMSettings(),
    ),
    sys_prompt=None,
    out_schema=Response,
)


@chatbot.parse_output_handler
def output_handler(conversation, ctx, **kwargs) -> Response:
    return Response(response=conversation[-1].content)


async def main():
    ctx = RunContextWrapper(print_messages=True)
    out = await chatbot.run("Hello, agent!", ctx=ctx)
    print(out.payloads[0].response)


asyncio.run(main())

Run your script:

uv run hello.py

---

Option 2: PIP-only (requirements.txt-based) Project

Note: You can check this sample project code in the src/grasp_agents/examples/demo/pip folder. Feel free to copy and paste the code from there to a separate project.

1. Create Project Folder

mkdir my-test-pip-app
cd my-test-pip-app

2. Install Python 3.11.9 (Recommended)

If using pyenv:

brew install pyenv
pyenv install 3.11.9
pyenv local 3.11.9

Open a new terminal after setting the Python version.

3. Create & Activate Virtual Environment

python -m venv .venv
source .venv/bin/activate

4. Install Grasp Agents SDK

If you have a requirements.txt file:

pip install -r requirements.txt

Or install directly:

pip install grasp-agents

5. Example Usage

Create a file, e.g., hello.py, and use the same code as above.

6. Run the App

python hello.py

---

Option 3: Poetry-based Project

Note: You can check this sample project code in the src/grasp_agents/examples/demo/poetry folder. Feel free to copy and paste the code from there to a separate project.

1. Create Project Folder

mkdir my-test-poetry-app
cd my-test-poetry-app

2. Install Python 3.11.9 via pyenv

brew install pyenv
pyenv install 3.11.9
pyenv local 3.11.9

3. Install Poetry Package Manager

If you don't have Poetry, install it:

curl -sSL https://install.python-poetry.org | python3 -

Open a new terminal after installing Poetry.

4. Create and Activate a Virtual Environment

python -m venv .venv
source .venv/bin/activate

5. Make Poetry Use the Virtual Environment's Python

poetry env use $(which python)

6. Install the Grasp Agents SDK

poetry install

7. Example Usage

Create a file, e.g., hello.py, and use the same code as above.

8. Environment Variables

Ensure you have a .env file with your OpenAI API key set:

OPENAI_API_KEY=your_openai_api_key

9. Run the App

poetry run python hello.py

Development

To develop and test the library locally, follow these steps:

1. Install UV Package Manager

Make sure UV is installed on your system:

curl -LsSf https://astral.sh/uv/install.sh | sh

2. Install Dependencies

Create a new virtual environment and install dependencies:

uv venv
source .venv/bin/activate
uv sync

3. Test Example for VS Code

• Install the Jupyter Notebook extension.

• Ensure you have a .env file with your OpenAI and Google AI Studio API keys set (see .env.example).

OPENAI_API_KEY=your_openai_api_key
GOOGLE_AI_STUDIO_API_KEY=your_google_ai_studio_api_key

• Open src/grasp_agents/examples/notebooks/agents_demo.ipynb.

You're now ready to run and experiment with the example notebook.

4. Recommended VS Code Extensions

• Ruff -- for formatting and code analysis
• Pylint -- for linting
• Pylance -- for type checking