feat: support cli to parse swagger (#122)

* support cli to parse swagger and bugfix for agno tools

* more examples and tests

* fix lint

Author: ponytailer

README.md

@@ -37,6 +37,18 @@ supporting both synchronous and asynchronous operations.
 pip install https://github.com/ponytailer/pydantic-client.git
 ```
 
+
+## Examples
+
+See the [`example/`](./example/) directory for real-world usage of this library, including:
+
+- `example_requests.py`: Synchronous usage with RequestsWebClient
+- `example_httpx.py`: Async usage with HttpxWebClient
+- `example_aiohttp.py`: Async usage with AiohttpWebClient
+- `example_tools.py`: How to register and use Agno tools
+
+Each file is fully commented in English and can be run directly for reference.
+
 ## Quick Start
 
 ```python
@@ -82,7 +94,11 @@ class MyAPIClient(RequestsWebClient):
         # will get raw content, bytes type.
         ...
 
-    @delete("/users", agno_tool=True, tool_description="this is the function to delete user")
+    @delete(
+        "/users",
+        agno_tool=True,
+        tool_description="description or use function annotation."
+    )
     def delete_user(self, user_id: str, request_headers: Dict[str, Any]):
         ...
 

example/example_aiohttp.py

@@ -0,0 +1,42 @@
+"""
+Example: Async API client with AiohttpWebClient and Agno tools
+"""
+import asyncio
+from pydantic import BaseModel
+from pydantic_client import AiohttpWebClient, get, post
+
+class Order(BaseModel):
+    id: int
+    item: str
+    quantity: int
+
+class MyAiohttpClient(AiohttpWebClient):
+    def __init__(self):
+        super().__init__(base_url="https://api.example.com")
+
+    @get("/orders/{order_id}", agno_tool=True, tool_description="Get order info by ID")
+    async def get_order(self, order_id: int) -> Order:
+        """
+        :param order_id: Order ID
+        """
+        ...
+
+    @post("/orders", agno_tool=True, tool_description="Create a new order")
+    async def create_order(self, order: Order) -> Order:
+        """
+        :param order: Order object
+        """
+        ...
+
+async def main():
+    client = MyAiohttpClient()
+    # order = await client.get_order(555)
+    # print("Order info:", order)
+    class DummyAgent:
+        def register_tool(self, name, description, parameters, call):
+            print(f"Register tool: {name}, desc: {description}, params: {parameters}")
+    agent = DummyAgent()
+    client.register_agno_tools(agent)
+
+if __name__ == "__main__":
+    asyncio.run(main())

example/example_httpx.py

@@ -0,0 +1,42 @@
+"""
+Example: Async API client with HttpxWebClient and Agno tools
+"""
+import asyncio
+from pydantic import BaseModel
+from pydantic_client import HttpxWebClient, get, post
+
+class Product(BaseModel):
+    id: int
+    name: str
+    price: float
+
+class MyHttpxClient(HttpxWebClient):
+    def __init__(self):
+        super().__init__(base_url="https://api.example.com")
+
+    @get("/products/{product_id}", agno_tool=True, tool_description="Get product info by ID")
+    async def get_product(self, product_id: int) -> Product:
+        """
+        :param product_id: Product ID
+        """
+        ...
+
+    @post("/products", agno_tool=True, tool_description="Create a new product")
+    async def create_product(self, product: Product) -> Product:
+        """
+        :param product: Product object
+        """
+        ...
+
+async def main():
+    client = MyHttpxClient()
+    # product = await client.get_product(101)
+    # print("Product info:", product)
+    class DummyAgent:
+        def register_tool(self, name, description, parameters, call):
+            print(f"Register tool: {name}, desc: {description}, params: {parameters}")
+    agent = DummyAgent()
+    client.register_agno_tools(agent)
+
+if __name__ == "__main__":
+    asyncio.run(main())

example/example_requests.py

@@ -0,0 +1,40 @@
+"""
+Example: Synchronous API client with RequestsWebClient and Agno tools
+"""
+from pydantic import BaseModel
+from pydantic_client import RequestsWebClient, get, post
+
+class User(BaseModel):
+    id: int
+    name: str
+    email: str
+
+class MyAPIClient(RequestsWebClient):
+    def __init__(self):
+        super().__init__(base_url="https://api.example.com")
+
+    @get("/users/{user_id}", agno_tool=True, tool_description="Get user info by ID")
+    def get_user(self, user_id: int) -> User:
+        """
+        :param user_id: User ID
+        """
+        ...
+
+    @post("/users", agno_tool=True, tool_description="Create a new user")
+    def create_user(self, user: User) -> User:
+        """
+        :param user: User object
+        """
+        ...
+
+if __name__ == "__main__":
+    client = MyAPIClient()
+    # Call as normal API
+    # user = client.get_user(1)
+    # print("User info:", user)
+    # Register as agno tools
+    class DummyAgent:
+        def register_tool(self, name, description, parameters, call):
+            print(f"Register tool: {name}, desc: {description}, params: {parameters}")
+    agent = DummyAgent()
+    client.register_agno_tools(agent)

example/example_tools.py

@@ -0,0 +1,38 @@
+"""
+Example: Registering multiple API endpoints as Agno tools
+"""
+from pydantic import BaseModel
+from pydantic_client import RequestsWebClient, get, post
+
+class MathResult(BaseModel):
+    result: int
+
+class ToolClient(RequestsWebClient):
+    def __init__(self):
+        super().__init__(base_url="https://api.example.com")
+
+    @get("/add", agno_tool=True, tool_description="Add two numbers")
+    def add(self, a: int, b: int) -> MathResult:
+        """
+        :param a: First number
+        :param b: Second number
+        """
+        ...
+
+    @post("/multiply", agno_tool=True, tool_description="Multiply two numbers")
+    def multiply(self, a: int, b: int) -> MathResult:
+        """
+        :param a: First number
+        :param b: Second number
+        """
+        ...
+
+if __name__ == "__main__":
+    client = ToolClient()
+    # result = client.add(2, 3)
+    # print("Add result:", result)
+    class DummyAgent:
+        def register_tool(self, name, description, parameters, call):
+            print(f"Register tool: {name}, desc: {description}, params: {parameters}")
+    agent = DummyAgent()
+    client.register_agno_tools(agent)

example/example_usage.py

@@ -0,0 +1,31 @@
+from pydantic import BaseModel
+from pydantic_client.base import BaseWebClient
+from pydantic_client.tools.agno import register_agno_tool
+
+
+class User(BaseModel):
+    id: int
+    name: str
+    email: str
+
+
+class ExampleClient(BaseWebClient):
+
+    @register_agno_tool("Get user info")
+    def get_user(self, user_id: int) -> User:
+        """
+        :param user_id: User ID
+        """
+        return User(id=user_id, name="John", email="john@example.com")
+
+
+if __name__ == "__main__":
+    client = ExampleClient(base_url="http://api.example.com")
+    user = client.get_user(1)
+    print("User info:", user)
+    # Register agno tool to a dummy agent
+    class DummyAgent:
+        def register_tool(self, name, description, parameters, call):
+            print(f"Register tool: {name}, desc: {description}, params: {parameters}")
+    agent = DummyAgent()
+    client.register_agno_tools(agent)

pydantic_client/base.py

@@ -58,7 +58,8 @@ def from_config(cls, config: Dict[str, Any]) -> 'BaseWebClient':
             base_url=config['base_url'],
             headers=config.get('headers'),
             timeout=config.get('timeout', 30),
-            session=config.get('session', None)
+            session=config.get('session', None),
+            statsd_address=config.get('statsd_address')
         )
 
     def before_request(self, request_params: Dict[str, Any]) -> Dict[str, Any]: