tinyagent-py 0.0.1__tar.gz → 0.0.3__tar.gz

tinyagent_py-0.0.3/PKG-INFO

@@ -0,0 +1,207 @@
+Metadata-Version: 2.4
+Name: tinyagent-py
+Version: 0.0.3
+Summary: Tiny Agent with MCP Client
+Author-email: Mahdi Golchin <golchin@askdev.ai>
+Project-URL: Homepage, https://github.com/askbudi/tinyagent
+Project-URL: Bug Tracker, https://github.com/askbudi/tinyagent/issues
+Project-URL: Chat, https://askdev.ai/github/askbudi/tinyagent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp
+Requires-Dist: litellm
+Requires-Dist: openai
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Dynamic: license-file
+
+# tinyagent
+Tiny Agent: 100 lines Agent with MCP
+![TinyAgent Logo](https://raw.githubusercontent.com/askbudi/tinyagent/main/public/logo.png)
+
+
+
+Inspired by:
+- [Tiny Agents blog post](https://huggingface.co/blog/tiny-agents)
+- [12-factor-agents repository](https://github.com/humanlayer/12-factor-agents)
+- Created by chatting to the source code of JS Tiny Agent using [AskDev.ai](https://askdev.ai/search)
+
+## Quick Links
+- [Build your own Tiny Agent](https://askdev.ai/github/askbudi/tinyagent)
+
+## Overview
+This is a tiny agent that uses MCP and LiteLLM to interact with a model. You have full control over the agent, you can add any tools you like from MCP and extend the agent using its event system.
+
+## Installation
+
+### Using pip
+```bash
+pip install tinyagent-py
+```
+
+### Using uv
+```bash
+uv pip install tinyagent-py
+```
+
+## Usage
+
+```python
+from tinyagent import TinyAgent
+from textwrap import dedent
+import asyncio
+import os
+
+async def test_agent(task, model="o4-mini", api_key=None):
+    # Initialize the agent with model and API key
+    agent = TinyAgent(
+        model=model,  # Or any model supported by LiteLLM
+        api_key=os.environ.get("OPENAI_API_KEY") if not api_key else api_key  # Set your API key as an env variable
+    )
+    
+    try:
+        # Connect to an MCP server
+        # Replace with your actual server command and args
+        await agent.connect_to_server("npx", ["@openbnb/mcp-server-airbnb", "--ignore-robots-txt"])
+        
+        # Run the agent with a user query
+        result = await agent.run(task)
+        print("\nFinal result:", result)
+        return result
+    finally:
+        # Clean up resources
+        await agent.close()
+
+# Example usage
+task = dedent("""
+I need accommodation in Toronto between 15th to 20th of May. Give me 5 options for 2 adults.
+""")
+await test_agent(task, model="gpt-4.1-mini")
+```
+
+## How the TinyAgent Hook System Works
+
+TinyAgent is designed to be **extensible** via a simple, event-driven hook (callback) system. This allows you to add custom logic, logging, UI, memory, or any other behavior at key points in the agent's lifecycle.
+
+### How Hooks Work
+
+- **Hooks** are just callables (functions or classes with `__call__`) that receive events from the agent.
+- You register hooks using `agent.add_callback(hook)`.
+- Hooks are called with:  
+  `event_name, agent, **kwargs`
+- Events include:  
+  - `"agent_start"`: Agent is starting a new run
+  - `"message_add"`: A new message is added to the conversation
+  - `"llm_start"`: LLM is about to be called
+  - `"llm_end"`: LLM call finished
+  - `"agent_end"`: Agent is done (final result)
+  - (MCPClient also emits `"tool_start"` and `"tool_end"` for tool calls)
+
+Hooks can be **async** or regular functions. If a hook is a class with an async `__call__`, it will be awaited.
+
+#### Example: Adding a Custom Hook
+
+```python
+def my_logger_hook(event_name, agent, **kwargs):
+    print(f"[{event_name}] {kwargs}")
+
+agent.add_callback(my_logger_hook)
+```
+
+#### Example: Async Hook
+
+```python
+async def my_async_hook(event_name, agent, **kwargs):
+    if event_name == "agent_end":
+        print("Agent finished with result:", kwargs.get("result"))
+
+agent.add_callback(my_async_hook)
+```
+
+#### Example: Class-based Hook
+
+```python
+class MyHook:
+    async def __call__(self, event_name, agent, **kwargs):
+        if event_name == "llm_start":
+            print("LLM is starting...")
+
+agent.add_callback(MyHook())
+```
+
+### How to Extend the Hook System
+
+- **Create your own hook**: Write a function or class as above.
+- **Register it**: Use `agent.add_callback(your_hook)`.
+- **Listen for events**: Check `event_name` and use `**kwargs` for event data.
+- **See examples**: Each official hook (see below) includes a `run_example()` in its file.
+
+---
+
+## List of Available Hooks
+
+You can import and use these hooks from `tinyagent.hooks`:
+
+| Hook Name                | Description                                      | Example Import                                  |
+|--------------------------|--------------------------------------------------|-------------------------------------------------|
+| `LoggingManager`         | Granular logging control for all modules         | `from tinyagent.hooks.logging_manager import LoggingManager` |
+| `RichUICallback`         | Rich terminal UI (with [rich](https://github.com/Textualize/rich)) | `from tinyagent.hooks.rich_ui_callback import RichUICallback` |
+| `GradioCallback` | Interactive browser-based chat UI: file uploads, live thinking, tool calls, token stats | `from tinyagent.hooks.gradio_callback import GradioCallback`         |
+
+To see more details and usage, check the docstrings and `run_example()` in each hook file.
+
+## Using the GradioCallback Hook
+
+The `GradioCallback` hook lets you spin up a full-featured web chat interface for your agent in just a few lines. You get:
+
+Features:
+- **Browser-based chat** with streaming updates  
+- **File uploads** (\*.pdf, \*.docx, \*.txt) that the agent can reference  
+- **Live “thinking” view** so you see intermediate thoughts  
+- **Collapsible tool-call sections** showing inputs & outputs  
+- **Real-time token usage** (prompt, completion, total)  
+- **Toggleable display options** for thinking & tool calls  
+- **Non-blocking launch** for asyncio apps (`prevent_thread_lock=True`)
+
+```python
+import asyncio
+from tinyagent import TinyAgent
+from tinyagent.hooks.gradio_callback import GradioCallback
+async def main():
+    # 1. Initialize your agent
+    agent = TinyAgent(model="gpt-4.1-mini", api_key="YOUR_API_KEY")
+    # 2. (Optional) Add tools or connect to MCP servers
+    # await agent.connect_to_server("npx", ["-y","@openbnb/mcp-server-airbnb","--ignore-robots-txt"])
+    # 3. Instantiate the Gradio UI callback
+    gradio_ui = GradioCallback(
+    file_upload_folder="uploads/",
+    show_thinking=True,
+    show_tool_calls=True
+    )
+    # 4. Register the callback with the agent
+    agent.add_callback(gradio_ui)
+    # 5. Launch the web interface (non-blocking)
+    gradio_ui.launch(
+    agent,
+    title="TinyAgent Chat",
+    description="Ask me to plan a trip or fetch data!",
+    share=False,
+    prevent_thread_lock=True
+    )
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+---
+
+## Contributing Hooks
+
+- Place new hooks in the `tinyagent/hooks/` directory.
+- Add an example usage as `async def run_example()` in the same file.
+- Use `"gpt-4.1-mini"` as the default model in examples.
+
+---
+
+## License
+
+MIT License. See [LICENSE](LICENSE).

tinyagent_py-0.0.3/README.md

@@ -0,0 +1,189 @@
+# tinyagent
+Tiny Agent: 100 lines Agent with MCP
+![TinyAgent Logo](https://raw.githubusercontent.com/askbudi/tinyagent/main/public/logo.png)
+
+
+
+Inspired by:
+- [Tiny Agents blog post](https://huggingface.co/blog/tiny-agents)
+- [12-factor-agents repository](https://github.com/humanlayer/12-factor-agents)
+- Created by chatting to the source code of JS Tiny Agent using [AskDev.ai](https://askdev.ai/search)
+
+## Quick Links
+- [Build your own Tiny Agent](https://askdev.ai/github/askbudi/tinyagent)
+
+## Overview
+This is a tiny agent that uses MCP and LiteLLM to interact with a model. You have full control over the agent, you can add any tools you like from MCP and extend the agent using its event system.
+
+## Installation
+
+### Using pip
+```bash
+pip install tinyagent-py
+```
+
+### Using uv
+```bash
+uv pip install tinyagent-py
+```
+
+## Usage
+
+```python
+from tinyagent import TinyAgent
+from textwrap import dedent
+import asyncio
+import os
+
+async def test_agent(task, model="o4-mini", api_key=None):
+    # Initialize the agent with model and API key
+    agent = TinyAgent(
+        model=model,  # Or any model supported by LiteLLM
+        api_key=os.environ.get("OPENAI_API_KEY") if not api_key else api_key  # Set your API key as an env variable
+    )
+    
+    try:
+        # Connect to an MCP server
+        # Replace with your actual server command and args
+        await agent.connect_to_server("npx", ["@openbnb/mcp-server-airbnb", "--ignore-robots-txt"])
+        
+        # Run the agent with a user query
+        result = await agent.run(task)
+        print("\nFinal result:", result)
+        return result
+    finally:
+        # Clean up resources
+        await agent.close()
+
+# Example usage
+task = dedent("""
+I need accommodation in Toronto between 15th to 20th of May. Give me 5 options for 2 adults.
+""")
+await test_agent(task, model="gpt-4.1-mini")
+```
+
+## How the TinyAgent Hook System Works
+
+TinyAgent is designed to be **extensible** via a simple, event-driven hook (callback) system. This allows you to add custom logic, logging, UI, memory, or any other behavior at key points in the agent's lifecycle.
+
+### How Hooks Work
+
+- **Hooks** are just callables (functions or classes with `__call__`) that receive events from the agent.
+- You register hooks using `agent.add_callback(hook)`.
+- Hooks are called with:  
+  `event_name, agent, **kwargs`
+- Events include:  
+  - `"agent_start"`: Agent is starting a new run
+  - `"message_add"`: A new message is added to the conversation
+  - `"llm_start"`: LLM is about to be called
+  - `"llm_end"`: LLM call finished
+  - `"agent_end"`: Agent is done (final result)
+  - (MCPClient also emits `"tool_start"` and `"tool_end"` for tool calls)
+
+Hooks can be **async** or regular functions. If a hook is a class with an async `__call__`, it will be awaited.
+
+#### Example: Adding a Custom Hook
+
+```python
+def my_logger_hook(event_name, agent, **kwargs):
+    print(f"[{event_name}] {kwargs}")
+
+agent.add_callback(my_logger_hook)
+```
+
+#### Example: Async Hook
+
+```python
+async def my_async_hook(event_name, agent, **kwargs):
+    if event_name == "agent_end":
+        print("Agent finished with result:", kwargs.get("result"))
+
+agent.add_callback(my_async_hook)
+```
+
+#### Example: Class-based Hook
+
+```python
+class MyHook:
+    async def __call__(self, event_name, agent, **kwargs):
+        if event_name == "llm_start":
+            print("LLM is starting...")
+
+agent.add_callback(MyHook())
+```
+
+### How to Extend the Hook System
+
+- **Create your own hook**: Write a function or class as above.
+- **Register it**: Use `agent.add_callback(your_hook)`.
+- **Listen for events**: Check `event_name` and use `**kwargs` for event data.
+- **See examples**: Each official hook (see below) includes a `run_example()` in its file.
+
+---
+
+## List of Available Hooks
+
+You can import and use these hooks from `tinyagent.hooks`:
+
+| Hook Name                | Description                                      | Example Import                                  |
+|--------------------------|--------------------------------------------------|-------------------------------------------------|
+| `LoggingManager`         | Granular logging control for all modules         | `from tinyagent.hooks.logging_manager import LoggingManager` |
+| `RichUICallback`         | Rich terminal UI (with [rich](https://github.com/Textualize/rich)) | `from tinyagent.hooks.rich_ui_callback import RichUICallback` |
+| `GradioCallback` | Interactive browser-based chat UI: file uploads, live thinking, tool calls, token stats | `from tinyagent.hooks.gradio_callback import GradioCallback`         |
+
+To see more details and usage, check the docstrings and `run_example()` in each hook file.
+
+## Using the GradioCallback Hook
+
+The `GradioCallback` hook lets you spin up a full-featured web chat interface for your agent in just a few lines. You get:
+
+Features:
+- **Browser-based chat** with streaming updates  
+- **File uploads** (\*.pdf, \*.docx, \*.txt) that the agent can reference  
+- **Live “thinking” view** so you see intermediate thoughts  
+- **Collapsible tool-call sections** showing inputs & outputs  
+- **Real-time token usage** (prompt, completion, total)  
+- **Toggleable display options** for thinking & tool calls  
+- **Non-blocking launch** for asyncio apps (`prevent_thread_lock=True`)
+
+```python
+import asyncio
+from tinyagent import TinyAgent
+from tinyagent.hooks.gradio_callback import GradioCallback
+async def main():
+    # 1. Initialize your agent
+    agent = TinyAgent(model="gpt-4.1-mini", api_key="YOUR_API_KEY")
+    # 2. (Optional) Add tools or connect to MCP servers
+    # await agent.connect_to_server("npx", ["-y","@openbnb/mcp-server-airbnb","--ignore-robots-txt"])
+    # 3. Instantiate the Gradio UI callback
+    gradio_ui = GradioCallback(
+    file_upload_folder="uploads/",
+    show_thinking=True,
+    show_tool_calls=True
+    )
+    # 4. Register the callback with the agent
+    agent.add_callback(gradio_ui)
+    # 5. Launch the web interface (non-blocking)
+    gradio_ui.launch(
+    agent,
+    title="TinyAgent Chat",
+    description="Ask me to plan a trip or fetch data!",
+    share=False,
+    prevent_thread_lock=True
+    )
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+---
+
+## Contributing Hooks
+
+- Place new hooks in the `tinyagent/hooks/` directory.
+- Add an example usage as `async def run_example()` in the same file.
+- Use `"gpt-4.1-mini"` as the default model in examples.
+
+---
+
+## License
+
+MIT License. See [LICENSE](LICENSE).

{tinyagent_py-0.0.1 → tinyagent_py-0.0.3}/pyproject.toml

@@ -1,13 +1,16 @@
 [build-system]
-requires = ["setuptools>=61.0", "wheel"]
+requires = ["setuptools>=77.0", "wheel"]
 build-backend = "setuptools.build_meta"
 
+[tool.setuptools.packages.find]
+where = ["tinyagent"]
+exclude = ["public", "public.*"]
+
 [project]
 name = "tinyagent-py"
-version = "0.0.1"
+version = "0.0.3"
 description = "Tiny Agent with MCP Client"
 readme = "README.md"
-license = {text = "MIT"}
 authors = [
   {name="Mahdi Golchin", email="golchin@askdev.ai"}
 ]

tinyagent_py-0.0.3/tinyagent/hooks/__init__.py

@@ -0,0 +1,4 @@
+#from .rich_ui_agent import RichUICallback
+from .rich_ui_callback import RichUICallback
+from .logging_manager import LoggingManager
+__all__ = ["RichUICallback", "LoggingManager"]

tinyagent_py-0.0.3/tinyagent/hooks/agno_storage_hook.py

@@ -0,0 +1,128 @@
+try:
+    import agno
+    from agno.storage.postgres import PostgresStorage
+    from agno.storage.sqlite import SqliteStorage
+    from agno.storage.session.agent import AgentSession
+except ImportError as e:
+    raise ImportError("agno is not installed. Please install it with `pip install agno`.", e)
+
+import asyncio
+from typing import Optional
+from agno.storage.postgres import PostgresStorage
+from agno.storage.sqlite import SqliteStorage
+from agno.storage.session.agent import AgentSession
+
+class PostgresStorageHook:
+    def __init__(
+        self,
+        table_name: str,
+        db_url: Optional[str] = None,
+        db_engine=None,
+        schema: Optional[str] = "ai",
+        schema_version: int = 1,
+        auto_upgrade_schema: bool = True,
+        mode: str = "agent",
+    ):
+        self.storage = PostgresStorage(
+            table_name=table_name,
+            db_url=db_url,
+            db_engine=db_engine,
+            schema=schema,
+            schema_version=schema_version,
+            auto_upgrade_schema=auto_upgrade_schema,
+            mode=mode,
+        )
+
+    async def __call__(self, event_name: str, agent, **kwargs):
+        if event_name == "agent_start":
+            # Load session from storage
+            session_id = getattr(agent, "session_id", None)
+            user_id = getattr(agent, "user_id", None)
+            if session_id:
+                session = self.storage.read(session_id=session_id, user_id=user_id)
+                if session:
+                    # Populate agent state from session
+                    agent.messages = session.session_data.get("messages", [])
+                    agent.memory = session.memory
+                    agent.metadata = session.extra_data
+                    # You may need to adapt this depending on tinyagent's state structure
+
+        elif event_name in ("llm_end", "agent_end"):
+            # Save session to storage
+            session_id = getattr(agent, "session_id", None)
+            user_id = getattr(agent, "user_id", None)
+            if session_id:
+                # Create AgentSession from agent state
+                session_data = {
+                    "messages": getattr(agent, "messages", []),
+                }
+                session = AgentSession(
+                    session_id=session_id,
+                    user_id=user_id,
+                    memory=getattr(agent, "memory", {}),
+                    session_data=session_data,
+                    extra_data=getattr(agent, "metadata", {}),
+                    agent_id=getattr(agent, "agent_id", None),
+                    team_session_id=None,
+                    agent_data=None,
+                )
+                await asyncio.to_thread(self.storage.upsert, session)
+
+class SqliteStorageHook:
+    def __init__(
+        self,
+        table_name: str,
+        db_url: Optional[str] = None,
+        db_file: Optional[str] = None,
+        db_engine=None,
+        schema_version: int = 1,
+        auto_upgrade_schema: bool = True,
+        mode: str = "agent",
+    ):
+        self.storage = SqliteStorage(
+            table_name=table_name,
+            db_url=db_url,
+            db_file=db_file,
+            db_engine=db_engine,
+            schema_version=schema_version,
+            auto_upgrade_schema=auto_upgrade_schema,
+            mode=mode,
+        )
+
+    async def __call__(self, event_name: str, agent, **kwargs):
+        if event_name == "agent_start":
+            # Load session from storage
+            session_id = getattr(agent, "session_id", None)
+            user_id = getattr(agent, "user_id", None)
+            print("Session ID",session_id)
+            print("User ID",user_id)
+            if session_id:
+                session = self.storage.read(session_id=session_id, user_id=user_id)
+                print(f"Session: {session}")
+                if session:
+                    # Populate agent state from session
+                    agent.messages = session.memory.get("messages", [])
+                    agent.memory = session.memory
+                    agent.metadata = session.extra_data
+
+        elif event_name in ("llm_end", "agent_end"):
+            # Save session to storage
+            print("Agent metadata",getattr(agent, "metadata", {}))
+            session_id = getattr(agent, "session_id", None)
+            user_id = getattr(agent, "user_id", None)
+            if session_id:
+                session_data = {
+                    "messages": getattr(agent, "messages", []),
+                }
+                session = AgentSession(
+                    session_id=session_id,
+                    user_id=user_id,
+                    memory=getattr(agent, "memory", {}),
+                    session_data=session_data,
+                    extra_data=getattr(agent, "metadata", {}),
+                    agent_id=getattr(agent, "agent_id", None),
+                    team_session_id=None,
+                    agent_data=None,
+                )
+                await asyncio.to_thread(self.storage.upsert, session)
+