fix: cleaning up app_id and other terminology

examples/agno/python/README.md

@@ -89,13 +89,13 @@ from honcho_agno import HonchoTools
 
 # Creates its own Honcho client internally
 tools = HonchoTools(
-    app_id="my-app",              # Workspace ID (used to create internal client)
+    workspace_id="my-app",        # Workspace ID (used to create internal client)
     peer_id="assistant",          # Identity for this agent
     session_id="session-456",     # Optional: auto-generated if not provided
 )
 ```
 
-Note: When `honcho_client` is provided, `app_id` is ignored since the client already has its workspace configured.
+Note: When `honcho_client` is provided, `workspace_id` is ignored since the client already has its workspace configured.
 
 ### Environment Variables
 
@@ -211,6 +211,15 @@ uv sync
 uv run pytest
 ```
 
+### Run Examples
+
+Examples require additional dependencies:
+
+```bash
+uv sync --extra examples
+uv run python examples/simple_example.py
+```
+
 ## License
 
 AGPL-3.0-or-later

examples/agno/python/examples/multi_peer_example.py

@@ -48,7 +48,6 @@ def create_advisory_session(session_id: str):
 
     # === TECH BRO ADVISOR ===
     tech_bro_tools = HonchoTools(
-        app_id="advisory-trio",
         peer_id="tech-bro",
         session_id=session_id,
         honcho_client=honcho,
@@ -72,7 +71,6 @@ def create_advisory_session(session_id: str):
 
     # === PHILOSOPHY MEDITATION GURU ===
     guru_tools = HonchoTools(
-        app_id="advisory-trio",
         peer_id="philosophy-guru",
         session_id=session_id,
         honcho_client=honcho,

examples/agno/python/examples/multi_tool_example.py

@@ -42,7 +42,6 @@ def main():
 
     # Setup Honcho tools - creates peer and session internally
     honcho_tools = HonchoTools(
-        app_id="travel-app",
         peer_id="travel-assistant",
         session_id="trip-planning-session",
         honcho_client=honcho,

examples/agno/python/examples/simple_example.py

@@ -32,7 +32,6 @@ def main():
 
     # Initialize HonchoTools - creates peer and session internally
     honcho_tools = HonchoTools(
-        app_id="agno-demo",
         peer_id="assistant",
         session_id=session_id,
         honcho_client=honcho,

examples/agno/python/pyproject.toml

@@ -35,6 +35,10 @@ classifiers = [
 dependencies = [
     "agno>=1.4.0",
     "honcho-ai>=1.6.0",
+]
+
+[project.optional-dependencies]
+examples = [
     "openai>=1.0.0",
     "python-dotenv>=1.0.0",
 ]

examples/agno/python/src/honcho_agno/__init__.py

@@ -25,6 +25,9 @@ Example:
         honcho_client=honcho,
     )
 
+    # Create user peer for orchestration
+    user_peer = honcho.peer("user")
+
     # Create agent with memory
     agent = Agent(
         name="Memory Agent",
@@ -33,10 +36,13 @@ Example:
         description="An assistant with persistent memory powered by Honcho.",
     )
 
-    # Run the agent
-    response = agent.run("What do you know about the user?")
+    # Save user message via orchestration
+    honcho_tools.session.add_messages([user_peer.message("I prefer Python over JavaScript")])
 
-    # Save messages via orchestration (not the toolkit)
+    # Run the agent
+    response = agent.run("What programming language does the user prefer?")
+
+    # Save assistant response via orchestration
     honcho_tools.session.add_messages([honcho_tools.peer.message(str(response.content))])
     ```
 """

examples/agno/python/src/honcho_agno/tools.py

@@ -41,7 +41,7 @@ class HonchoTools(Toolkit):
         from honcho_agno import HonchoTools
 
         honcho_tools = HonchoTools(
-            app_id="my-app",
+            workspace_id="my-app",
             peer_id="assistant",
             session_id="shared-session",
         )
@@ -55,7 +55,7 @@ class HonchoTools(Toolkit):
 
     def __init__(
         self,
-        app_id: str = "default",
+        workspace_id: str = "default",
         peer_id: str = "assistant",
         session_id: str | None = None,
         honcho_client: Honcho | None = None,
@@ -64,7 +64,7 @@ class HonchoTools(Toolkit):
         Initialize the Honcho toolkit for a specific agent identity.
 
         Args:
-            app_id: Workspace ID for creating an internal Honcho client.
+            workspace_id: Workspace ID for creating an internal Honcho client.
                 Ignored if honcho_client is provided.
             peer_id: The identity this toolkit represents. This is who
                 the agent "is" when querying peer knowledge.
@@ -72,7 +72,7 @@ class HonchoTools(Toolkit):
                 will be generated. Share this across toolkits for multi-peer
                 conversations.
             honcho_client: Optional pre-configured Honcho client instance.
-                When provided, uses this client directly (app_id is ignored).
+                When provided, uses this client directly (workspace_id is ignored).
         """
         super().__init__(name="honcho")
 
@@ -80,7 +80,7 @@ class HonchoTools(Toolkit):
         if honcho_client is not None:
             self.honcho = honcho_client
         else:
-            self.honcho = Honcho(workspace_id=app_id)
+            self.honcho = Honcho(workspace_id=workspace_id)
 
         self.peer_id: str = peer_id
         self.session_id: str = session_id or str(uuid.uuid4())

examples/agno/python/uv.lock

@@ -174,6 +174,10 @@ source = { editable = "." }
 dependencies = [
     { name = "agno" },
     { name = "honcho-ai" },
+]
+
+[package.optional-dependencies]
+examples = [
     { name = "openai" },
     { name = "python-dotenv" },
 ]
@@ -188,9 +192,10 @@ dev = [
 requires-dist = [
     { name = "agno", specifier = ">=1.4.0" },
     { name = "honcho-ai", specifier = ">=1.6.0" },
-    { name = "openai", specifier = ">=1.0.0" },
-    { name = "python-dotenv", specifier = ">=1.0.0" },
+    { name = "openai", marker = "extra == 'examples'", specifier = ">=1.0.0" },
+    { name = "python-dotenv", marker = "extra == 'examples'", specifier = ">=1.0.0" },
 ]
+provides-extras = ["examples"]
 
 [package.metadata.requires-dev]
 dev = [