grasp_agents 0.1.15__py3-none-any.whl → 0.1.17__py3-none-any.whl

grasp_agents/utils.py

@@ -1,57 +1,38 @@
 import ast
 import asyncio
-from datetime import datetime
 import functools
 import json
 import re
 from collections.abc import Callable, Coroutine
 from copy import deepcopy
+from datetime import datetime
+from logging import getLogger
 from pathlib import Path
 from typing import Any, TypeVar, cast
 
-from pydantic import BaseModel, create_model
+from pydantic import BaseModel, GetCoreSchemaHandler, TypeAdapter, create_model
 from pydantic.fields import FieldInfo
+from pydantic_core import core_schema
 from tqdm.autonotebook import tqdm
 
+logger = getLogger(__name__)
 
-def read_contents_from_file(
-    file_path: str | Path,
-    binary_mode: bool = False,
-) -> str:
-    """Reads and returns contents of file"""
-    try:
-        if binary_mode:
-            with open(file_path, "rb") as file:
-                return file.read()
-        else:
-            with open(file_path) as file:
-                return file.read()
-    except FileNotFoundError:
-        print(f"File {file_path} not found.")
-        return ""
-
-
-async def asyncio_gather_with_pbar(
-    *corouts: Coroutine[Any, Any, Any],
-    no_tqdm: bool = False,
-    desc: str | None = None,
-) -> list[Any]:
-    pbar = tqdm(total=len(corouts), desc=desc, disable=no_tqdm)
 
-    async def run_and_update(coro: Coroutine[Any, Any, Any]) -> Any:
-        result = await coro
-        pbar.update(1)
-        return result
-
-    wrapped_tasks = [run_and_update(c) for c in corouts]
-    results = await asyncio.gather(*wrapped_tasks)
-    pbar.close()
+def merge_pydantic_models(*models: type[BaseModel]) -> type[BaseModel]:
+    fields_dict: dict[str, FieldInfo] = {}
+    for model in models:
+        for field_name, field_info in model.model_fields.items():
+            if field_name in fields_dict:
+                raise ValueError(
+                    f"Field conflict detected: '{field_name}' exists in multiple models"
+                )
+            fields_dict[field_name] = field_info
 
-    return results
+    return create_model("MergedModel", __module__=__name__, **fields_dict)  # type: ignore
 
 
-def get_timestamp() -> str:
-    return datetime.now().strftime("%Y%m%d_%H%M%S")
+def filter_fields(data: dict[str, Any], model: type[BaseModel]) -> dict[str, Any]:
+    return {key: data[key] for key in model.model_fields if key in data}
 
 
 def read_txt(file_path: str) -> str:
@@ -73,26 +54,32 @@ def format_json_string(text: str) -> str:
                 pass
         i += 1
 
-    return ""
+    return text
 
 
-def read_json_string(json_str: str) -> dict[str, Any] | list[Any]:
+def read_json_string(
+    json_str: str, return_none_on_failure: bool = False
+) -> dict[str, Any] | list[Any] | None:
     try:
         json_response = ast.literal_eval(json_str)
     except (ValueError, SyntaxError):
         try:
             json_response = json.loads(json_str)
         except json.JSONDecodeError as exc:
+            if return_none_on_failure:
+                return None
             raise ValueError(
                 "Invalid JSON - Both ast.literal_eval and json.loads "
                 f"failed to parse the following response:\n{json_str}"
             ) from exc
 
-    return json_response  # type: ignore
+    return json_response
 
 
-def extract_json(json_str: str) -> dict[str, Any] | list[Any]:
-    return read_json_string(format_json_string(json_str))
+def extract_json(
+    json_str: str, return_none_on_failure: bool = False
+) -> dict[str, Any] | list[Any] | None:
+    return read_json_string(format_json_string(json_str), return_none_on_failure)
 
 
 def extract_xml_list(text: str) -> list[str]:
@@ -105,32 +92,43 @@ def extract_xml_list(text: str) -> list[str]:
     return chunks
 
 
-def get_prompt(prompt_text: str | None, prompt_path: str | Path | None) -> str | None:
-    if prompt_text is None:
-        prompt = (
-            read_contents_from_file(prompt_path) if prompt_path is not None else None
-        )
-    else:
-        prompt = prompt_text
-
-    return prompt
-
-
-def merge_pydantic_models(*models: type[BaseModel]) -> type[BaseModel]:
-    fields_dict: dict[str, FieldInfo] = {}
-    for model in models:
-        for field_name, field_info in model.model_fields.items():
-            if field_name in fields_dict:
-                raise ValueError(
-                    f"Field conflict detected: '{field_name}' exists in multiple models"
-                )
-            fields_dict[field_name] = field_info
-
-    return create_model("MergedModel", __module__=__name__, **fields_dict)  # type: ignore
+def make_conditional_parsed_output_type(
+    response_format: type, marker: str = "<DONE>"
+) -> type:
+    class ParsedOutput:
+        """
+        * Accepts any **str**.
+        * If the string contains `marker`, it must contain a valid JSON for
+        `response_format` → we return that a response_format instance.
+        * Otherwise we leave the string untouched.
+        """
+
+        @classmethod
+        def __get_pydantic_core_schema__(
+            cls,
+            _source_type: Any,
+            _handler: GetCoreSchemaHandler,
+        ) -> core_schema.CoreSchema:
+            def validator(v: Any) -> Any:
+                if isinstance(v, str) and marker in v:
+                    v_json_str = format_json_string(v)
+                    response_format_adapter = TypeAdapter[Any](response_format)
+
+                    return response_format_adapter.validate_json(v_json_str)
+
+                return v
+
+            return core_schema.no_info_after_validator_function(
+                validator, core_schema.any_schema()
+            )
 
+        @classmethod
+        def __get_pydantic_json_schema__(
+            cls, core_schema: core_schema.CoreSchema, handler: GetCoreSchemaHandler
+        ):
+            return handler(core_schema)
 
-def filter_fields(data: dict[str, Any], model: type[BaseModel]) -> dict[str, Any]:
-    return {key: data[key] for key in model.model_fields if key in data}
+    return ParsedOutput
 
 
 T = TypeVar("T", bound=Callable[..., Any])
@@ -149,3 +147,54 @@ def forbid_state_change(method: T) -> T:
         return result
 
     return cast("T", wrapper)
+
+
+def read_contents_from_file(
+    file_path: str | Path,
+    binary_mode: bool = False,
+) -> str | bytes:
+    """Reads and returns contents of file"""
+    try:
+        if binary_mode:
+            with open(file_path, "rb") as file:
+                return file.read()
+        else:
+            with open(file_path) as file:
+                return file.read()
+    except FileNotFoundError:
+        logger.error(f"File {file_path} not found.")
+        return ""
+
+
+def get_prompt(prompt_text: str | None, prompt_path: str | Path | None) -> str | None:
+    if prompt_text is None:
+        prompt = (
+            read_contents_from_file(prompt_path) if prompt_path is not None else None
+        )
+    else:
+        prompt = prompt_text
+
+    return prompt  # type: ignore[assignment]
+
+
+async def asyncio_gather_with_pbar(
+    *corouts: Coroutine[Any, Any, Any],
+    no_tqdm: bool = False,
+    desc: str | None = None,
+) -> list[Any]:
+    pbar = tqdm(total=len(corouts), desc=desc, disable=no_tqdm)
+
+    async def run_and_update(coro: Coroutine[Any, Any, Any]) -> Any:
+        result = await coro
+        pbar.update(1)
+        return result
+
+    wrapped_tasks = [run_and_update(c) for c in corouts]
+    results = await asyncio.gather(*wrapped_tasks)
+    pbar.close()
+
+    return results
+
+
+def get_timestamp() -> str:
+    return datetime.now().strftime("%Y%m%d_%H%M%S")

grasp_agents-0.1.17.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,44 @@
+grasp_agents/agent_message.py,sha256=Z-czIHNSe7eAo5r6q2Zu10HFpUjQjVbayyglGyyj4Lw,911
+grasp_agents/agent_message_pool.py,sha256=4O4xz-aZ_I5m3iLAUiMAQcVn5AGRP4daUM8XME03Xsw,3250
+grasp_agents/base_agent.py,sha256=4mNMyWdt9MTzg64JhrVjcU_FSYDj0ED_AKpRZXCRVb4,1870
+grasp_agents/cloud_llm.py,sha256=JJmIUu8SOJ4TElQ4B19mPgXJ1SiapZdPFFhA2YVRKRw,13015
+grasp_agents/comm_agent.py,sha256=ukkT0zXgE8-yt63fyi3MQ_3Q0QjwIDHKz4MbHt9FBxw,7323
+grasp_agents/costs_dict.yaml,sha256=EW6XxRXLZobMwQEEiUNYALbDzfbZFb2zEVCaTSAqYjw,2334
+grasp_agents/grasp_logging.py,sha256=H1GYhXdQvVkmauFDZ-KDwvVmPQHZUUm9sRqX_ObK2xI,1111
+grasp_agents/http_client.py,sha256=KZva2MjJjuI5ohUeU8RdTAImUnQYaqBrV2jDH8smbJw,738
+grasp_agents/llm.py,sha256=RZY25UNJEdPUmqOHifUrrQTgfoDCAVtZN9WQvvxnLC4,3004
+grasp_agents/llm_agent.py,sha256=_D16rA8LDhALZKYYuWxB-E75g3uBgzM04EcJyuRMKZA,12619
+grasp_agents/llm_agent_state.py,sha256=91K1-8Uodbe-t_I6nu0xBzHfQjssZYCHjMuDbu5aCr0,2327
+grasp_agents/memory.py,sha256=X1YtVX8XxP5KnGPMW8BqjID8QK4hTG2obxoyhnnZ4pU,5575
+grasp_agents/printer.py,sha256=Jk6OJExio53gbKBod5Dd8Y3CWYrVb4K5q4UJ8i9cQvo,5024
+grasp_agents/prompt_builder.py,sha256=rYVIY4adJwBitjrTYvpEh5x8C7cLbIiXxT1F-vQuvEM,7393
+grasp_agents/run_context.py,sha256=hyETO3-p0azPFws75kX6rrUDLf58Ar6jmyt6TQ5Po78,2589
+grasp_agents/tool_orchestrator.py,sha256=6VX8FGYeUHiSt9GpUjOga7KGP55Kzs1jEiNcOZysIAo,5501
+grasp_agents/usage_tracker.py,sha256=5YuN6hpg6HASdg-hOylgWzhCiORmDMnZuQtbISfhm_4,3378
+grasp_agents/utils.py,sha256=-OdCs27FKek8owGbwmAVWwLXDgEzoTu-B5_EwRLEsz4,5869
+grasp_agents/openai/__init__.py,sha256=qN8HMAatSJKOsA6v-JwakMYguwkswCVHqrmK1gFy9wI,3096
+grasp_agents/openai/completion_converters.py,sha256=lX9h1kaGAo5ttsl-4V7l4x8IpjxJaJJtyU2cKu3-EOc,1871
+grasp_agents/openai/content_converters.py,sha256=6GI0D7xJalzsiawAJOyCUzTJTo0NQdpv87YKmfN0LYQ,2631
+grasp_agents/openai/converters.py,sha256=DBXBxow9oRG6pc8inpZBLiuUqHzVfpscmHFpN9bAdvc,5276
+grasp_agents/openai/message_converters.py,sha256=KjF6FbXzwlWdM-1YT3cswUV-74sjiwOhLFPMY4sJ5Xk,4593
+grasp_agents/openai/openai_llm.py,sha256=dscGlVhH4v1yAw4NRPgJdww9toOoMRpIqA6HD4IGWOs,6132
+grasp_agents/openai/tool_converters.py,sha256=KhWRETkjhjocISUo_HBZ8QfBiyTOoC5WurPNAR4BYxc,1027
+grasp_agents/rate_limiting/__init__.py,sha256=KRgtF_E7R3YfA2cpYcFcZ7wycV0pWVJ0xRQC7YhiIEQ,158
+grasp_agents/rate_limiting/rate_limiter_chunked.py,sha256=jp6bqWGq2qYAxbmyU_bAGeBXM_nEmSrR6VabDutcTA0,5800
+grasp_agents/rate_limiting/types.py,sha256=JbLYJC-gmzcHH_4-YNTz9IcIwVpcpDyDGvljxNznf5k,1389
+grasp_agents/rate_limiting/utils.py,sha256=yrqboDWWqeekDcs0xaeOPOvelhgAlywDpQpscpPqlhg,1995
+grasp_agents/typing/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+grasp_agents/typing/completion.py,sha256=_KDLx3Gtz7o-pEZrvAFgCZwDmkr2oQkxrL-2LSXHHsw,657
+grasp_agents/typing/content.py,sha256=13nLNZqZgtpo9sM0vCRQmZ4bQjjZqUSElMQOwjL7bO8,3651
+grasp_agents/typing/converters.py,sha256=EbGur_Ngx-wINfyOEHa7JqmKnMAxZ5vJjhAPoqBf_AM,3048
+grasp_agents/typing/io.py,sha256=M294tNROa9gJ_I38c9pLekEbUK2p3qirYdE_QGpuw1c,624
+grasp_agents/typing/message.py,sha256=oCpqD_CV2Da-M-l-e5liFJSwK8267fxfcU68LIc7C1E,3801
+grasp_agents/typing/tool.py,sha256=t40vr3ljQY_Qx0f0KZIc151bYlHUF7Bf7JfOkiJOi2c,1657
+grasp_agents/workflow/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+grasp_agents/workflow/looped_agent.py,sha256=YBOgOIvy3_NwKvEoGgzQJ2fY9SNG66MQk6obSBGWvCc,3896
+grasp_agents/workflow/sequential_agent.py,sha256=yDt2nA-b1leVByD8jsKrWD6bHe0o9z33jrOJGOLwbyk,2004
+grasp_agents/workflow/workflow_agent.py,sha256=9U94IQ39Vb1W_5u8aoqHb65ikdarEhEJkexDz8xwHD4,2294
+grasp_agents-0.1.17.dist-info/METADATA,sha256=YG_CGwTAOAQFAOA_Aqi6pqwF_ODYtzY_nQEgf2IRMFM,7001
+grasp_agents-0.1.17.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+grasp_agents-0.1.17.dist-info/licenses/LICENSE.md,sha256=Kfeo0gdlLS6tLQiWwO9UWhjp9-f93a5kShSiBp2FG-c,1201
+grasp_agents-0.1.17.dist-info/RECORD,,

grasp_agents-0.1.15.dist-info/METADATA

@@ -1,152 +0,0 @@
-Metadata-Version: 2.4
-Name: grasp_agents
-Version: 0.1.15
-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: 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 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 (UV Package manager)
-
-### Option 1: UV Package Manager Project
-
-> **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
-
-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
-```
-
-```python
-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:
-
-```bash
-uv run hello.py
-```