copilotkit 0.1.86a0__tar.gz → 0.1.87__tar.gz

{copilotkit-0.1.86a0 → copilotkit-0.1.87}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: copilotkit
-Version: 0.1.86a0
+Version: 0.1.87
 Summary: CopilotKit python SDK
 License: MIT
 Keywords: copilot,copilotkit,langgraph,langchain,ai,langsmith,langserve
@@ -13,7 +13,7 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Provides-Extra: crewai
-Requires-Dist: ag-ui-langgraph[fastapi] (>=0.0.30)
+Requires-Dist: ag-ui-langgraph[fastapi] (>=0.0.29)
 Requires-Dist: ag-ui-protocol (>=0.1.11)
 Requires-Dist: crewai (==0.118.0) ; extra == "crewai"
 Requires-Dist: fastapi (>=0.115.0,<1.0.0)

copilotkit-0.1.87/copilotkit/a2ui.py

@@ -0,0 +1,237 @@
+"""
+A2UI helpers — build v0.9 A2UI operations from schema + data.
+
+Usage:
+    from copilotkit import a2ui
+
+    schema = a2ui.load_schema("flight_card.json")
+
+    @tool
+    def search_flights(flights: list[Flight]) -> str:
+        return a2ui.render([
+            a2ui.create_surface("my-surface"),
+            a2ui.update_components("my-surface", schema),
+            a2ui.update_data_model("my-surface", {"flights": flights}),
+        ])
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+
+def load_schema(path: str | Path) -> list[dict[str, Any]]:
+    """Load an A2UI component schema from a JSON file."""
+    with open(path) as f:
+        return json.load(f)
+
+
+def update_components(
+    surface_id: str,
+    components: list[dict[str, Any]],
+) -> dict[str, Any]:
+    """Build a v0.9 updateComponents operation."""
+    return {
+        "version": "v0.9",
+        "updateComponents": {
+            "surfaceId": surface_id,
+            "components": components,
+        }
+    }
+
+
+def update_data_model(
+    surface_id: str,
+    data: Any,
+    path: str = "/",
+) -> dict[str, Any]:
+    """Build a v0.9 updateDataModel operation with plain JSON value."""
+    return {
+        "version": "v0.9",
+        "updateDataModel": {
+            "surfaceId": surface_id,
+            "path": path,
+            "value": data,
+        }
+    }
+
+
+BASIC_CATALOG_ID = "https://a2ui.org/specification/v0_9/basic_catalog.json"
+"""The catalog ID for the standard v0.9 basic catalog."""
+
+
+def create_surface(
+    surface_id: str,
+    catalog_id: str = BASIC_CATALOG_ID,
+) -> dict[str, Any]:
+    """Build a v0.9 createSurface operation."""
+    return {
+        "version": "v0.9",
+        "createSurface": {
+            "surfaceId": surface_id,
+            "catalogId": catalog_id,
+        }
+    }
+
+
+A2UI_OPERATIONS_KEY = "a2ui_operations"
+"""The container key used to wrap A2UI operations for explicit detection."""
+
+
+def render(
+    operations: list[dict[str, Any]]
+) -> str:
+    """Wrap operations in the a2ui_operations container and serialize to JSON.
+
+    Args:
+        operations: The A2UI v0.9 operations (createSurface, updateComponents, updateDataModel).
+
+    Example::
+        render(
+            operations=[...],
+        )
+    """
+    result: dict[str, Any] = {A2UI_OPERATIONS_KEY: operations}
+    return json.dumps(result)
+
+
+# ---------------------------------------------------------------------------
+# Dynamic A2UI prompt builder
+# ---------------------------------------------------------------------------
+
+DEFAULT_GENERATION_GUIDELINES = """\
+Generate A2UI v0.9 JSON.
+
+## A2UI Protocol Instructions
+
+A2UI (Agent to UI) is a protocol for rendering rich UI surfaces from agent responses.
+
+CRITICAL: You MUST call the render_a2ui tool with ALL of these arguments:
+- surfaceId: A unique ID for the surface (e.g. "product-comparison")
+- components: REQUIRED — the A2UI component array. NEVER omit this. Use a List with
+  children: { componentId: "card-id", path: "/items" } for repeating cards.
+- data: OPTIONAL — a JSON object written to the root of the surface data model.
+  Use for pre-filling form values or providing data for path-bound components.
+- every component must have the "component" field specifying the component type (e.g. "Text", "Image", "Row", "Column", "List", "Button", etc.)
+
+COMPONENT ID RULES:
+- Every component ID must be unique within the surface.
+- A component MUST NOT reference itself as child/children. This causes a
+  circular dependency error. For example, if a component has id="avatar",
+  its child must be a DIFFERENT id (e.g. "avatar-img"), never "avatar".
+- The child/children tree must be a DAG — no cycles allowed.
+
+PATH RULES FOR TEMPLATES:
+Components inside a repeating List use RELATIVE paths (no leading slash).
+The path is resolved relative to each array item automatically.
+If List has children: { componentId: "card", path: "/items" } and item has key "name",
+use { "path": "name" } (NO leading slash — relative to item).
+CRITICAL: Do NOT use "/name" (absolute) inside templates — use "name" (relative).
+The List's own path ("/items") uses a leading slash (absolute), but all
+components INSIDE the template card use paths WITHOUT leading slash.
+Do NOT use "/items/0/name" or "/items/{@key}/name" — just "name".
+
+COMPONENT VALUES — DEFAULT RULE:
+Use inline literal values for ALL component properties. Pass strings, numbers,
+arrays, and objects directly on the component. Do NOT use { "path": "..." }
+objects unless the property's schema explicitly allows it (see exception below).
+CRITICAL: USING { "path": "..." } ON A PROPERTY THAT DOES NOT DECLARE PATH
+SUPPORT IN ITS SCHEMA WILL CAUSE A RUNTIME CRASH AND BREAK THE ENTIRE UI.
+ALWAYS CHECK THE COMPONENT SCHEMA FIRST — IF THE PROPERTY ONLY ACCEPTS A
+PLAIN TYPE, YOU MUST USE A LITERAL VALUE.
+VERY IMPORTANT: THE APPLICATION WILL BREAK IF YOU DO NOT FOLLOW THIS RULE!
+
+For example, a chart's "data" must always be an inline array:
+  "data": [{"label": "Jan", "value": 100}, {"label": "Feb", "value": 200}]
+A metric's "value" must always be an inline string:
+  "value": "$1,200"
+
+PATH BINDING EXCEPTION — SCHEMA-DRIVEN:
+A few properties accept { "path": "/some/path" } as an alternative to a literal
+value. You can identify these in the Available Components schema: the property
+will list BOTH a literal type AND an object-with-path option. If a property only
+shows a single type (string, number, array, etc.), it does NOT support path
+binding — use a literal value only.
+
+Path binding is typically used for editable form inputs so the client can write
+user input back to the data model. When building forms:
+- Bind input "value" to a data model path: "value": { "path": "/form/name" }
+- Pre-fill via the "data" tool argument: "data": { "form": { "name": "Alice" } }
+- Capture values on submit via button action context:
+    "action": { "event": { "name": "submit", "context": { "name": { "path": "/form/name" } } } }
+
+REPEATING CONTENT uses a structural children format (not the same as value binding):
+  children: { componentId: "card-id", path: "/items" }
+Components inside templates use RELATIVE paths (no leading slash): { "path": "name" }."""
+
+DEFAULT_DESIGN_GUIDELINES = """\
+Create polished, visually appealing interfaces:
+- Always include a title heading (h2) for the surface, outside the List.
+  Wrap in a Column: [title, list] as root.
+- For card templates, create clear visual hierarchy:
+  - h3 for primary text (names, titles)
+  - h2 for featured numbers (prices, scores) — makes them stand out
+  - caption for secondary info (ratings, categories, metadata)
+  - body for descriptions
+- Use Divider between logical sections within cards.
+- Use Row with justify="spaceBetween" for label-value pairs
+  (e.g. "Rating" on left, "4.5/5" on right).
+- Include images when relevant (logos, icons, product photos):
+  - Use Image component with variant="smallFeature" or "avatar"
+  - Prefer company logos for branded products — Google favicons are reliable:
+    https://www.google.com/s2/favicons?domain=sony.com&sz=128
+    https://www.google.com/s2/favicons?domain=bose.com&sz=128
+  - For generic icons: https://placehold.co/128x128/EEE/999?text=🎧
+  - Do NOT invent Unsplash photo-IDs — they will 404. Only use real, known URLs.
+- Use horizontal List direction for side-by-side comparison cards.
+- Keep cards clean — avoid clutter. Whitespace is good.
+- Use consistent surfaceIds (lowercase, hyphenated).
+- NEVER use the same ID for a component and its child — this creates a
+  circular dependency. E.g. if id="avatar", child must NOT be "avatar".
+- Both Row and Column support "justify" and "align".
+- Add Button for interactivity. Button needs child (Text ID) + action.
+  Action MUST use this exact nested format:
+    "action": { "event": { "name": "myAction", "context": { "key": "value" } } }
+  The "event" key holds an OBJECT with "name" (required) and "context" (optional).
+  Do NOT use a flat format like {"event": "name"} — "event" must be an object.
+  Use variant="primary" for main action buttons, variant="borderless" for links.
+- For forms: wrap fields in a Card with a Column. Place the submit button in a
+  Row with justify="end". Every input MUST use path binding on the "value" property
+  (e.g. "value": { "path": "/form/name" }) to be editable. The submit button's action
+  context MUST reference the same paths to capture the user's input.
+
+Use the SAME surfaceId as the main surface. Match action names to Button action event names."""
+
+
+def a2ui_prompt(
+    component_schema: str,
+    generation_guidelines: str = DEFAULT_GENERATION_GUIDELINES,
+    design_guidelines: str = DEFAULT_DESIGN_GUIDELINES,
+) -> str:
+    """Build the system prompt for dynamic A2UI generation.
+
+    Args:
+        component_schema: JSON string of available components and their props.
+            Read from state["ag-ui"]["a2ui_schema"].
+        generation_guidelines: Instructions for how to call the render_a2ui
+            tool, path rules, and data format.
+        design_guidelines: Visual design rules, component hierarchy tips,
+            and action handler patterns.
+
+    Returns:
+        Complete system prompt string.
+    """
+    return f"""\
+{generation_guidelines}
+
+## DESIGN GUIDELINES:
+{design_guidelines}
+
+## AVAILABLE COMPONENTS:
+The following components are available for building UI surfaces.
+Use ONLY these components with the specified props.
+
+{component_schema}
+"""

{copilotkit-0.1.86a0 → copilotkit-0.1.87}/copilotkit/copilotkit_lg_middleware.py

@@ -26,7 +26,6 @@ from langchain.agents.middleware import (
     ModelResponse,
 )
 from langgraph.runtime import Runtime
-from ag_ui_langgraph import make_json_safe
 
 from .langgraph import CopilotKitProperties
 
@@ -263,7 +262,15 @@ class CopilotKitMiddleware(AgentMiddleware[StateSchema, Any]):
         if isinstance(app_context, str):
             context_content = app_context
         else:
-            context_content = json.dumps(make_json_safe(app_context), indent=2)
+            # Handle Pydantic models (e.g. ag_ui Context)
+            if hasattr(app_context, "model_dump"):
+                app_context = app_context.model_dump()
+            elif isinstance(app_context, list):
+                app_context = [
+                    item.model_dump() if hasattr(item, "model_dump") else item
+                    for item in app_context
+                ]
+            context_content = json.dumps(app_context, indent=2)
 
         context_message_content = f"App Context:\n{context_content}"
         context_message_prefix = "App Context:\n"
@@ -301,8 +308,15 @@ class CopilotKitMiddleware(AgentMiddleware[StateSchema, Any]):
                     existing_context_index = i
                     break
 
-        # Create the context message
-        context_message = SystemMessage(content=context_message_content)
+        # Create the context message.
+        # When replacing an existing context message, reuse its ID so the
+        # add_messages reducer updates in-place instead of appending a
+        # duplicate at the end of the message list.
+        if existing_context_index != -1:
+            existing_id = getattr(messages[existing_context_index], "id", None)
+            context_message = SystemMessage(content=context_message_content, id=existing_id)
+        else:
+            context_message = SystemMessage(content=context_message_content)
 
         if existing_context_index != -1:
             # Replace existing context message

{copilotkit-0.1.86a0 → copilotkit-0.1.87}/copilotkit/langgraph.py

@@ -142,9 +142,19 @@ def langchain_messages_to_copilotkit(
         if hasattr(message, "content"):
             content = message.content
 
-            # Check if content is a list and use the first element
+            # Content can be a list of content blocks (e.g. Anthropic models).
+            # Extract and concatenate all text parts instead of only taking
+            # the first element.
             if isinstance(content, list):
-                content = content[0] if content else ""
+                text_parts = []
+                for part in content:
+                    if isinstance(part, str):
+                        text_parts.append(part)
+                    elif isinstance(part, dict) and part.get("type") == "text":
+                        text_parts.append(part.get("text", ""))
+                    elif isinstance(part, dict) and "text" in part:
+                        text_parts.append(part.get("text", ""))
+                content = "".join(text_parts)
 
             # Anthropic models return a dict with a "text" key
             if isinstance(content, dict):

{copilotkit-0.1.86a0 → copilotkit-0.1.87}/copilotkit/langgraph_agent.py

@@ -2,6 +2,7 @@
 
 import uuid
 import json
+import math
 from typing import Optional, List, Callable, Any, cast, Union, TypedDict, Literal
 
 from langgraph.graph.state import CompiledStateGraph
@@ -18,6 +19,22 @@ except ImportError:
     from langchain_core.messages import BaseMessage, SystemMessage
     
 from langchain_core.runnables import RunnableConfig, ensure_config
+
+def _serialize_state(state):
+    """Recursively convert Pydantic BaseModel instances to dicts for serialization."""
+    try:
+        from pydantic import BaseModel as PydanticBaseModel
+    except ImportError:
+        return state
+
+    if isinstance(state, PydanticBaseModel):
+        return state.model_dump()
+    elif isinstance(state, dict):
+        return {k: _serialize_state(v) for k, v in state.items()}
+    elif isinstance(state, (list, tuple)):
+        return type(state)(_serialize_state(item) for item in state)
+    return state
+
 from langchain_core.messages import HumanMessage
 
 from partialjson.json_parser import JSONParser
@@ -31,6 +48,20 @@ from .logging import get_logger
 
 logger = get_logger(__name__)
 
+
+def _sanitize_for_json(obj):
+    """Replace NaN and Infinity float values with None for valid JSON serialization."""
+    if isinstance(obj, float):
+        if math.isnan(obj) or math.isinf(obj):
+            return None
+        return obj
+    if isinstance(obj, dict):
+        return {k: _sanitize_for_json(v) for k, v in obj.items()}
+    if isinstance(obj, (list, tuple)):
+        return [_sanitize_for_json(item) for item in obj]
+    return obj
+
+
 class CopilotKitConfig(TypedDict):
     """
     CopilotKit config for LangGraphAgent
@@ -236,7 +267,12 @@ class LangGraphAgent(Agent):
             actions=actions,
             agent_name=self.name
         )
-        current_graph_state.update(state)
+        # Only update graph state with keys that merge_state explicitly produced,
+        # not keys that were simply passed through from state_input unchanged.
+        # This preserves graph-owned state keys that the frontend may have sent stale values for.
+        for key, value in state.items():
+            if key not in state_input or value is not state_input.get(key):
+                current_graph_state[key] = value
         lg_interrupt_meta_event = next((ev for ev in (meta_events or []) if ev.get("name") == "LangGraphInterruptEvent"), None)
         has_active_interrupts = active_interrupts is not None and len(active_interrupts) > 0
 
@@ -435,7 +471,9 @@ class LangGraphAgent(Agent):
                     manually_emitted_state = None
 
                 if manually_emit_intermediate_state:
-                    manually_emitted_state = cast(Any, event["data"])
+                    manually_emitted_state = _merge_emit_state(current_graph_state, cast(Any, event["data"]))
+                    if isinstance(manually_emitted_state, dict):
+                        current_graph_state.update(manually_emitted_state)
                     yield self._emit_state_sync_event(
                         thread_id=thread_id,
                         run_id=run_id,
@@ -489,7 +527,7 @@ class LangGraphAgent(Agent):
                         active=not exiting_node
                     ) + "\n"
 
-                yield langchain_dumps(event) + "\n"
+                yield langchain_dumps(_sanitize_for_json(event)) + "\n"
         except Exception as error:
             # Emit error information through streaming protocol before terminating
             # This preserves the semantic error details that would otherwise be lost
@@ -591,6 +629,9 @@ class LangGraphAgent(Agent):
         # Filter by schema keys if available
         state = self.filter_state_on_schema_keys(state, 'output')
 
+        # Convert Pydantic BaseModel instances to dicts for serialization
+        state = _serialize_state(state)
+
         return langchain_dumps({
             "event": "on_copilotkit_state_sync",
             "thread_id": thread_id,
@@ -598,7 +639,7 @@ class LangGraphAgent(Agent):
             "agent_name": self.name,
             "node_name": node_name,
             "active": active,
-            "state": state,
+            "state": _sanitize_for_json(state),
             "running": running,
             "role": "assistant"
         })
@@ -636,10 +677,13 @@ class LangGraphAgent(Agent):
         state_copy = state.copy()
         state_copy.pop("messages", None)
 
+        # Convert Pydantic BaseModel instances to dicts for serialization
+        state_copy = _serialize_state(state_copy)
+
         return {
             "threadId": thread_id,
             "threadExists": True,
-            "state": state_copy,
+            "state": _sanitize_for_json(state_copy),
             "messages": messages
         }
 
@@ -687,7 +731,8 @@ class LangGraphAgent(Agent):
             if hasattr(self, schema_keys_name) and getattr(self, schema_keys_name):
                 return filter_by_schema_keys(state, getattr(self, schema_keys_name))
         except Exception:
-            return state
+            pass
+        return state
 
     def get_interrupt_event(self, value):
         if not isinstance(value, str) and "__copilotkit_interrupt_value__" in value:
@@ -724,6 +769,13 @@ class LangGraphAgent(Agent):
 
         raise ValueError("Message ID not found in history")
 
+
+def _merge_emit_state(current_state: dict, emitted_state: Any) -> dict:
+    """Merge emitted state on top of current graph state instead of replacing it."""
+    if isinstance(emitted_state, dict):
+        return {**current_state, **emitted_state}
+    return cast(Any, emitted_state)
+
 class _StreamingStateExtractor:
     def __init__(self, emit_intermediate_state: List[dict]):
         self.emit_intermediate_state = emit_intermediate_state

{copilotkit-0.1.86a0 → copilotkit-0.1.87}/copilotkit/langgraph_agui_agent.py

@@ -1,7 +1,7 @@
 import json
 from typing import Dict, Any, List, Optional, Union, AsyncGenerator
 from enum import Enum
-from ag_ui_langgraph import LangGraphAgent, make_json_safe
+from ag_ui_langgraph import LangGraphAgent
 from ag_ui.core import (
     EventType,
     CustomEvent,
@@ -108,7 +108,7 @@ class LangGraphAGUIAgent(LangGraphAgent):
                         type=EventType.TOOL_CALL_ARGS,
                         tool_call_id=custom_event.value["id"],
                         delta=custom_event.value["args"] if isinstance(custom_event.value["args"], str) else json.dumps(
-                            make_json_safe(custom_event.value["args"])),
+                            custom_event.value["args"]),
                         raw_event=event,
                     )
                 )

{copilotkit-0.1.86a0 → copilotkit-0.1.87}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "copilotkit"
-version = "0.1.86-alpha.0"
+version = "0.1.87"
 description = "CopilotKit python SDK"
 authors = ["Markus Ecker <markus.ecker@gmail.com>"]
 license = "MIT"
@@ -16,13 +16,15 @@ keywords = [
   "langsmith",
   "langserve",
 ]
+packages = [{ include = "copilotkit" }]
+include = ["copilotkit/*.json"]
 
 [tool.poetry.dependencies]
 python = ">=3.10,<3.13"
 langgraph = { version = ">=0.3.25,<2" }
 langchain = { version = ">=0.3.0" }
 crewai = { version = "0.118.0", optional = true }
-ag-ui-langgraph = { version = ">=0.0.30", extras = ["fastapi"] }
+ag-ui-langgraph = { version = ">=0.0.29", extras = ["fastapi"] }
 ag-ui-protocol = ">=0.1.11"
 fastapi = ">=0.115.0,<1.0.0"
 partialjson = "^0.0.8"