Add an example of Structured Outputs

Author: RussellLuo

examples/structured-outputs/README.md

@@ -0,0 +1,94 @@
+# Structured Outputs
+
+This example demonstrates how to enable structured outputs when chatting with an agent. As a comparison, please also refer to the [original example from Ollama][1].
+
+To learn more about structured outputs, see [OpenAI's Structured Outputs][2].
+
+
+## Prerequisites
+
+- Install `coagent` (see [Installation](../../README.md#installation)).
+- Start a NATS server (see [Distributed](../../README.md#distributed)).
+
+
+## Quick Start
+
+Run [llama3.1][3] by using [Ollama][4]:
+
+```bash
+ollama run llama3.1
+```
+
+### Run the local agent
+
+Run the agent as a script:
+
+```bash
+python examples/structured-outputs/local_agent.py
+```
+
+### Run the daemon agent
+
+Run the agent as a daemon:
+
+```bash
+python examples/structured-outputs/daemon_agent.py
+```
+
+Then communicate with the agent using the `coagent` CLI:
+
+```bash
+coagent structured -H type:StructuredOutput --chat -d '{
+  "input": {
+    "role": "user",
+    "content": "I have two friends. The first is Ollama 22 years old busy saving the world, and the second is Alonso 23 years old and wants to hang out. Return a list of friends in JSON format"
+  },
+  "output_schema": {
+    "type": "json_schema",
+    "json_schema": {
+      "name": "FriendList",
+      "strict": true,
+      "schema": {
+        "type": "object",
+        "properties": {
+          "friends": {
+            "items": {
+              "$ref": "#/$defs/FriendInfo"
+            },
+            "type": "array"
+          }
+        },
+        "required": [
+          "friends"
+        ],
+        "$defs": {
+          "FriendInfo": {
+            "type": "object",
+            "properties": {
+              "name": {
+                "type": "string"
+              },
+              "age": {
+                "type": "integer"
+              },
+              "is_available": {
+                "type": "boolean"
+              }
+            },
+            "required": [
+              "name",
+              "age",
+              "is_available"
+            ]
+          }
+        }
+      }
+    }
+  }
+}'
+```
+
+[1]: https://github.com/ollama/ollama/blob/main/docs/openai.md#structured-outputs
+[2]: https://platform.openai.com/docs/guides/structured-outputs
+[3]: https://ollama.com/library/llama3.1
+[4]: https://github.com/ollama/ollama

examples/structured-outputs/daemon_agent.py

@@ -0,0 +1,43 @@
+import asyncio
+
+from coagent.agents import ChatAgent, ModelClient
+from coagent.core import AgentSpec, idle_loop, new, set_stderr_logger
+from coagent.runtimes import NATSRuntime
+from pydantic import BaseModel
+
+
+class FriendInfo(BaseModel):
+    name: str
+    age: int
+    is_available: bool
+
+
+class FriendList(BaseModel):
+    friends: list[FriendInfo]
+
+
+client = ModelClient(
+    model="openai/llama3.1",
+    api_base="http://localhost:11434/v1",
+    api_key="ollama",
+)
+
+
+structured = AgentSpec(
+    "structured",
+    new(
+        ChatAgent,
+        client=client,
+    ),
+)
+
+
+async def main():
+    async with NATSRuntime.from_servers("nats://127.0.0.1:4222") as runtime:
+        await runtime.register(structured)
+        await idle_loop()
+
+
+if __name__ == "__main__":
+    set_stderr_logger()
+    asyncio.run(main())

examples/structured-outputs/local_agent.py

@@ -0,0 +1,59 @@
+import asyncio
+
+from coagent.agents import ChatAgent, ChatMessage, ModelClient, StructuredOutput
+from coagent.core import AgentSpec, new, set_stderr_logger
+from coagent.runtimes import LocalRuntime
+from pydantic import BaseModel
+
+
+class FriendInfo(BaseModel):
+    name: str
+    age: int
+    is_available: bool
+
+
+class FriendList(BaseModel):
+    friends: list[FriendInfo]
+
+
+client = ModelClient(
+    model="openai/llama3.1",
+    api_base="http://localhost:11434/v1",
+    api_key="ollama",
+)
+
+
+structured = AgentSpec(
+    "structured",
+    new(
+        ChatAgent,
+        client=client,
+    ),
+)
+
+
+async def main():
+    async with LocalRuntime() as runtime:
+        await runtime.register(structured)
+
+        result = await structured.run(
+            StructuredOutput(
+                input=ChatMessage(
+                    role="user",
+                    content="\
+I have two friends. The first is Ollama 22 years old busy saving the world, \
+and the second is Alonso 23 years old and wants to hang out. Return a list \
+of friends in JSON format",
+                ),
+                output_type=FriendList,
+            ).encode(),
+            stream=True,
+        )
+        async for chunk in result:
+            msg = ChatMessage.decode(chunk)
+            print(msg.content, end="", flush=True)
+
+
+if __name__ == "__main__":
+    set_stderr_logger()
+    asyncio.run(main())