copilotkit 0.1.51__tar.gz → 0.1.51a2__tar.gz

{copilotkit-0.1.51 → copilotkit-0.1.51a2}/PKG-INFO

@@ -1,23 +1,28 @@
 Metadata-Version: 2.3
 Name: copilotkit
-Version: 0.1.51
+Version: 0.1.51a2
 Summary: CopilotKit python SDK
 License: MIT
 Keywords: copilot,copilotkit,langgraph,langchain,ai,langsmith,langserve
 Author: Markus Ecker
 Author-email: markus.ecker@gmail.com
-Requires-Python: >=3.10,<3.13
+Requires-Python: >=3.10,<3.15
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Provides-Extra: crewai
-Requires-Dist: crewai (==0.118.0) ; extra == "crewai"
-Requires-Dist: fastapi (>=0.115.0,<0.116.0)
-Requires-Dist: langchain (==0.3.21)
-Requires-Dist: langgraph (==0.3.18)
+Requires-Dist: ag-ui-langgraph[fastapi] (==0.0.42-alpha.0)
+Requires-Dist: ag-ui-protocol (>=0.1.15)
+Requires-Dist: crewai (>=0.118.0) ; (python_version >= "3.10" and python_version < "3.14") and (extra == "crewai")
+Requires-Dist: fastapi (>=0.115.0,<1.0.0)
+Requires-Dist: langchain (>=0.3.0)
+Requires-Dist: langgraph (>=0.3.25,<2)
 Requires-Dist: partialjson (>=0.0.8,<0.0.9)
+Requires-Dist: pydantic-core (>=2.35.0)
 Requires-Dist: toml (>=0.10.2,<0.11.0)
 Project-URL: Homepage, https://copilotkit.ai
 Project-URL: Repository, https://github.com/CopilotKit/CopilotKit/tree/main/sdk-python

copilotkit-0.1.51a2/copilotkit/__init__.py

@@ -0,0 +1,57 @@
+"""CopilotKit SDK"""
+
+from .sdk import (
+    CopilotKitRemoteEndpoint,
+    CopilotKitContext,
+    CopilotKitSDK,
+    CopilotKitSDKContext,
+)
+from .action import Action
+from .exc import (
+    CopilotKitError,
+    CopilotKitMisuseError,
+    ActionNotFoundException,
+    AgentNotFoundException,
+    ActionExecutionException,
+    AgentExecutionException,
+)
+from .langgraph import CopilotKitState
+from .parameter import Parameter
+from .agent import Agent
+from .langgraph_agui_agent import LangGraphAGUIAgent
+from .copilotkit_lg_middleware import CopilotKitMiddleware
+from ag_ui_langgraph.middlewares.state_streaming import (
+    StateStreamingMiddleware,
+    StateItem,
+)
+from .header_propagation import (
+    set_forwarded_headers,
+    get_forwarded_headers,
+    install_httpx_hook,
+)
+
+
+__all__ = [
+    "CopilotKitRemoteEndpoint",
+    "CopilotKitSDK",
+    "Action",
+    "CopilotKitState",
+    "Parameter",
+    "Agent",
+    "CopilotKitContext",
+    "CopilotKitSDKContext",
+    "CopilotKitError",
+    "CopilotKitMisuseError",
+    "ActionNotFoundException",
+    "AgentNotFoundException",
+    "ActionExecutionException",
+    "AgentExecutionException",
+    "CrewAIAgent",  # pyright: ignore[reportUnsupportedDunderAll] pylint: disable=undefined-all-variable
+    "LangGraphAGUIAgent",
+    "CopilotKitMiddleware",
+    "StateStreamingMiddleware",
+    "StateItem",
+    "set_forwarded_headers",
+    "get_forwarded_headers",
+    "install_httpx_hook",
+]

copilotkit-0.1.51a2/copilotkit/a2ui.py

@@ -0,0 +1,240 @@
+"""
+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:
+- Exactly one component MUST have id="root". This is the surface's entry
+  point — the renderer begins at "root" and walks the child/children tree
+  from there. Every other component must be reachable from "root". If no
+  component has id="root", the surface renders an empty loading placeholder
+  and none of your components will be shown.
+- 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.51 → copilotkit-0.1.51a2}/copilotkit/action.py

@@ -5,26 +5,32 @@ from inspect import iscoroutinefunction
 from typing import Optional, List, Callable, TypedDict, Any, cast
 from .parameter import Parameter, normalize_parameters
 
+
 class ActionDict(TypedDict):
     """Dict representation of an action"""
+
     name: str
     description: str
     parameters: List[Parameter]
 
+
 class ActionResultDict(TypedDict):
     """Dict representation of an action result"""
+
     result: Any
 
+
 class Action:  # pylint: disable=too-few-public-methods
     """Action class for CopilotKit"""
+
     def __init__(
-            self,
-            *,
-            name: str,
-            handler: Callable,
-            description: Optional[str] = None,
-            parameters: Optional[List[Parameter]] = None,
-        ):
+        self,
+        *,
+        name: str,
+        handler: Callable,
+        description: Optional[str] = None,
+        parameters: Optional[List[Parameter]] = None,
+    ):
         self.name = name
         self.description = description
         self.parameters = parameters
@@ -32,26 +38,20 @@ class Action:  # pylint: disable=too-few-public-methods
 
         if not re.match(r"^[a-zA-Z0-9_-]+$", name):
             raise ValueError(
-                f"Invalid action name '{name}': " +
-                "must consist of alphanumeric characters, underscores, and hyphens only"
+                f"Invalid action name '{name}': "
+                + "must consist of alphanumeric characters, underscores, and hyphens only"
             )
 
-    async def execute(
-            self,
-            *,
-            arguments: dict
-        ) -> ActionResultDict:
+    async def execute(self, *, arguments: dict) -> ActionResultDict:
         """Execute the action"""
         result = self.handler(**arguments)
 
-        return {
-            "result": await result if iscoroutinefunction(self.handler) else result
-        }
+        return {"result": await result if iscoroutinefunction(self.handler) else result}
 
     def dict_repr(self) -> ActionDict:
         """Dict representation of the action"""
         return {
-            'name': self.name,
-            'description': self.description or '',
-            'parameters': normalize_parameters(cast(Any, self.parameters)),
+            "name": self.name,
+            "description": self.description or "",
+            "parameters": normalize_parameters(cast(Any, self.parameters)),
         }

{copilotkit-0.1.51 → copilotkit-0.1.51a2}/copilotkit/agent.py

@@ -7,30 +7,34 @@ from .types import Message
 from .action import ActionDict
 from .types import MetaEvent
 
+
 class AgentDict(TypedDict):
     """Agent dictionary"""
+
     name: str
     description: Optional[str]
 
+
 class Agent(ABC):
     """Agent class for CopilotKit"""
+
     def __init__(
-            self,
-            *,
-            name: str,
-            description: Optional[str] = None,
-        ):
+        self,
+        *,
+        name: str,
+        description: Optional[str] = None,
+    ):
         self.name = name
         self.description = description
 
         if not re.match(r"^[a-zA-Z0-9_-]+$", name):
             raise ValueError(
-                f"Invalid agent name '{name}': " +
-                "must consist of alphanumeric characters, underscores, and hyphens only"
+                f"Invalid agent name '{name}': "
+                + "must consist of alphanumeric characters, underscores, and hyphens only"
             )
 
     @abstractmethod
-    def execute( # pylint: disable=too-many-arguments
+    def execute(  # pylint: disable=too-many-arguments
         self,
         *,
         state: dict,
@@ -54,13 +58,9 @@ class Agent(ABC):
             "threadId": thread_id or "",
             "threadExists": False,
             "state": {},
-            "messages": []
+            "messages": [],
         }
 
-
     def dict_repr(self) -> AgentDict:
         """Dict representation of the action"""
-        return {
-            'name': self.name,
-            'description': self.description or ''
-        }
+        return {"name": self.name, "description": self.description or ""}