Add OpenSERP SDK usage examples

examples/ai/python-agent-tool/README.md

@@ -0,0 +1,11 @@
+# Agent search tool (Python)
+
+A `web_search(query)` function shaped to register as a tool for an LLM agent.
+It returns compact JSON-serializable results the model can read and cite.
+
+```bash
+pip install -r requirements.txt
+python main.py
+```
+
+Import `web_search` from [main.py](main.py) and register it with your agent framework.

examples/ai/python-agent-tool/main.py

@@ -0,0 +1,29 @@
+import json
+
+from openserp import OpenSERP
+
+# A search function shaped for use as an LLM / agent tool: it takes a query
+# and returns plain JSON-serializable results the model can read.
+
+
+def web_search(query: str, limit: int = 10) -> list[dict]:
+    """Search the web and return a compact list of results."""
+    # Hosted API instead? Get a key at https://openserp.org/dashboard/keys:
+    #   with OpenSERP(api_key="<YOUR_API_TOKEN>") as client:
+    with OpenSERP(base_url="http://localhost:7000") as client:
+        response = client.search(engine="google", text=query, limit=limit)
+        return [
+            {
+                "rank": item.rank,
+                "title": item.title,
+                "url": item.url,
+                "snippet": item.snippet,
+            }
+            for item in response.results
+        ]
+
+
+if __name__ == "__main__":
+    # Register web_search as a tool with your LLM; here we just call it directly.
+    results = web_search("what is retrieval augmented generation")
+    print(json.dumps(results, indent=2))

examples/ai/python-agent-tool/requirements.txt

@@ -0,0 +1 @@
+openserp>=0.2.0,<1