Renaming Execute to Invoke, update mcp (#49)

* rename execute to invoke

update mcp

* update version

* fix lint

Author: GuanyiLi-Craig

README.md

@@ -19,7 +19,7 @@ Graphite is a flexible, event-driven framework for building AI agents using modu
    By treating events as the single source of truth, Graphite automatically logs every state change and decision path. This level of detailed recordkeeping is indispensable for users working in regulated sectors or who need full traceability for debugging and compliance.
 
 4. **Restorability**  
-   Long-running AI tasks risk substantial rework if they fail mid-execution. In Graphite, checkpoints and event-based playback enable workflows to resume from the precise point of interruption, minimizing downtime and maximizing resource efficiency ([Example](/tests_integration/react_assistant/react_assistant_recovery_example.py)).
+   Long-running AI tasks risk substantial rework if they fail mid-invoke. In Graphite, checkpoints and event-based playback enable workflows to resume from the precise point of interruption, minimizing downtime and maximizing resource efficiency ([Example](/tests_integration/react_assistant/react_assistant_recovery_example.py)).
 
 Graphite is based on:
 
@@ -43,7 +43,7 @@ Graphite is structured into three conceptual layers — *Assistants*, *Nodes*, a
 
 - **Assistants**: High-level orchestration layer that manages AI agent workflows and user interactions. Assistants handle the complete lifecycle of requests, from initial input to final response.
 - **Nodes**: A node is a discrete component in a graph-based agent system that operates under an event-driven model. Its primary role is to represent its position within a workflow graph, manage event subscriptions, and designate topics for publishing.
-- **Tools**:  In our platform, tools represent the execution components within a workflow. A Tool is essentially a function designed to transform input data into output based on specified rules or logic.
+- **Tools**:  In our platform, tools represent the invoke components within a workflow. A Tool is essentially a function designed to transform input data into output based on specified rules or logic.
 - **Workflow**: Orchestrates interactions among nodes using a Pub/Sub pattern with in-memory message queuing.
 
 ![graphite_architecture](/assets/graphite_architecture.png)
@@ -53,11 +53,11 @@ Additionally, Graphite offers modules that support essential architectural patte
 - **Event**: Core to Graphite’s event-driven architecture. Events represent every state change, stored in a durable event store, serving as the single source of truth for downstream processing, auditing, workflow restoration, and more.
 - **Topic**: Implements lightweight FIFO message queuing, essential for Pub/Sub interactions.
 - **Command**: Implements the Command pattern, clearly separating request initiators from executors through defined Command objects and handlers. Commands carry all necessary context, allowing nodes to invoke tools independently and cleanly.
-- **Decorators**: Automatically capture execution details (inputs, outputs, and errors) as events without altering core business logic, facilitating auditability and traceability.
-- **Execution Context**: Manages identifiers across message life cycles:
-  - `conversation_id`: Manages conversations, which may include multiple executions.
+- **Decorators**: Automatically capture invoke details (inputs, outputs, and errors) as events without altering core business logic, facilitating auditability and traceability.
+- **Invoke Context**: Manages identifiers across message life cycles:
+  - `conversation_id`: Manages conversations, which may include multiple invokes.
   - `assistant_request_id`: Tracks requests at the assistant level, facilitating complex multi-node workflows.
-  - `execution_id`: Handles individual user requests, potentially involving multiple assistants in complex scenarios.
+  - `invoke_id`: Handles individual user requests, potentially involving multiple assistants in complex scenarios.
   - `user_id`: Identifies individual users, supporting multiple conversations per user.
 
 For more details, visit the Graphite [documentation](https://binome-dev.github.io/graphite/).

assets/overall-design.excalidraw

@@ -8540,11 +8540,11 @@
       "locked": false,
       "fontSize": 20,
       "fontFamily": 1,
-      "text": "Each node in the directed graph aggregates the data from all of \nits ancestor nodes—i.e., any nodes from which it can be reached by \nfollowing the graph’s edges backward—so that when the node executes, \nit has the complete set of data from every path leading into it.",
+      "text": "Each node in the directed graph aggregates the data from all of \nits ancestor nodes—i.e., any nodes from which it can be reached by \nfollowing the graph’s edges backward—so that when the node invokes, \nit has the complete set of data from every path leading into it.",
       "textAlign": "left",
       "verticalAlign": "top",
       "containerId": null,
-      "originalText": "Each node in the directed graph aggregates the data from all of \nits ancestor nodes—i.e., any nodes from which it can be reached by \nfollowing the graph’s edges backward—so that when the node executes, \nit has the complete set of data from every path leading into it.",
+      "originalText": "Each node in the directed graph aggregates the data from all of \nits ancestor nodes—i.e., any nodes from which it can be reached by \nfollowing the graph’s edges backward—so that when the node invokes, \nit has the complete set of data from every path leading into it.",
       "lineHeight": 1.25,
       "baseline": 93,
       "index": "b2I",
@@ -10193,11 +10193,11 @@
       "locked": false,
       "fontSize": 20,
       "fontFamily": 1,
-      "text": "Execution Unit",
+      "text": "Invoke Unit",
       "textAlign": "center",
       "verticalAlign": "middle",
       "containerId": "l1G2fX06bDsOHxQP4EDK-",
-      "originalText": "Execution Unit",
+      "originalText": "Invoke Unit",
       "lineHeight": 1.25,
       "baseline": 21,
       "index": "b2v",

docs/docs/getting-started/features.md

@@ -2,8 +2,8 @@
 
 The core design principles that set Graphite apart from other agent frameworks are:
 
-1. **A Simple 3-Layer Execution Model**  
-   Three distinct layers—assistant, node, and tool—manage execution, while a dedicated workflow layer oversees orchestration.
+1. **A Simple 3-Layer Invoke Model**  
+   Three distinct layers—assistant, node, and tool—manage invoke, while a dedicated workflow layer oversees orchestration.
 
 2. **Pub/Sub Event-Driven Orchestration**  
    Communication relies on publishing and subscribing to events, ensuring a decoupled, modular flow of data throughout the system.
@@ -23,34 +23,34 @@ Combining these elements, **Graphite** provides a production-grade AI applicatio
    By treating events as the single source of truth, Graphite automatically logs every state change and decision path. This level of detailed recordkeeping is indispensable for users working in regulated sectors or who need full traceability for debugging and compliance.
 
 4. **Restorability**  
-   Long-running AI tasks risk substantial rework if they fail mid-execution. In Graphite, checkpoints and event-based playback enable workflows to resume from the precise point of interruption, minimizing downtime and maximizing resource efficiency.
+   Long-running AI tasks risk substantial rework if they fail mid-invoke. In Graphite, checkpoints and event-based playback enable workflows to resume from the precise point of interruption, minimizing downtime and maximizing resource efficiency.
 
 Together, these capabilities—observability, idempotency, auditability, and restorability—distinguish **Graphite** as a framework for building robust and trustworthy AI applications. Below is a detailed breakdown of how Graphite implements each feature.
 
 ## Observability
 
-The system leverages event sourcing to record all operations, combined with OpenTelemetry for standardized tracing. Thanks to the clearly defined three-layer execution model (assistant, node, tool) plus an orchestration workflow, each execution function is decorated to capture inputs, outputs, and any exceptions. These captures are converted into events (stored in the event store) and traces (exported to platforms like Arize or other OpenTelemetry services).
+The system leverages event sourcing to record all operations, combined with OpenTelemetry for standardized tracing. Thanks to the clearly defined three-layer invoke model (assistant, node, tool) plus an orchestration workflow, each invoke function is decorated to capture inputs, outputs, and any exceptions. These captures are converted into events (stored in the event store) and traces (exported to platforms like Arize or other OpenTelemetry services).
 
-Meanwhile, each Topic instance logs pub/sub interactions in the event store after processing. Coupled with the ExecutionContext object, this approach makes the entire data flow within the agentic workflow fully transparent. Because every node and tool has a unique name and ID, and each operation is stamped with execution context IDs, locating specific inputs and outputs is straightforward. Then given pub/sub events, the framework can build a directed data flows between nodes. Even there are circles, the data flow can form a DAG with publishing and consuming offset in each topic.
+Meanwhile, each Topic instance logs pub/sub interactions in the event store after processing. Coupled with the InvokeContext object, this approach makes the entire data flow within the agentic workflow fully transparent. Because every node and tool has a unique name and ID, and each operation is stamped with invoke context IDs, locating specific inputs and outputs is straightforward. Then given pub/sub events, the framework can build a directed data flows between nodes. Even there are circles, the data flow can form a DAG with publishing and consuming offset in each topic.
 
 ## Idempotency
 
 Graphite adopts an event-driven architecture where topics function as logical message queues, storing each event exactly once in an event store. When a workflow fails, needs to be retried, or is paused (e.g., for a human-in-the-loop intervention), it can resume from the last known valid state by replaying events that were produced but not yet consumed by downstream nodes.
 
-Consumption events are only recorded once the entire node processing completes successfully. Until that point, the system treats partial or failed node executions as if they never happened, preventing duplicated outputs or broken states. Should a node encounter an error (e.g., an LLM connection failure, external API issue, or function exception), Graphite detects the unconsumed events upon restoration and places the associated node(s) back into the execution queue. This design ensures the node can safely retry from the same input without creating conflicting or duplicated consumption records.
+Consumption events are only recorded once the entire node processing completes successfully. Until that point, the system treats partial or failed node invokes as if they never happened, preventing duplicated outputs or broken states. Should a node encounter an error (e.g., an LLM connection failure, external API issue, or function exception), Graphite detects the unconsumed events upon restoration and places the associated node(s) back into the invoke queue. This design ensures the node can safely retry from the same input without creating conflicting or duplicated consumption records.
 
 By storing each event exactly once and withholding consumption records until success, Graphite guarantees idempotent behavior. Even if a node issues multiple invocations due to an error, the event logs and consumption rules still reconstruct a single, consistent path from invocation to response. This approach produces correct outcomes on retries while maintaining a complete, conflict-free audit trail.
 
 ## Auditability
 
-Auditability in Graphite emerges naturally from its observability. By automatically persisting all execution events and pub/sub events in a centralized event store, the platform provides a complete historical record of every action taken. Function decorators capture each execution (including inputs, outputs, and exceptions), while Topic operations log every publish and consume operation, and effectively acting as a “cache” layer of orchestration events.
+Auditability in Graphite emerges naturally from its observability. By automatically persisting all invoke events and pub/sub events in a centralized event store, the platform provides a complete historical record of every action taken. Function decorators capture each invoke (including inputs, outputs, and exceptions), while Topic operations log every publish and consume operation, and effectively acting as a “cache” layer of orchestration events.
 
 Moreover, Graphite’s modular design and clear separation of concerns simplify the process of examining specific components—such as an LLM node and its associated tool. Each module has well-defined responsibilities, ensuring that every action is accurately documented in the event store and easily traceable. This end-to-end audit trail not only supports today’s nascent AI regulations but positions Graphite to adapt to evolving compliance requirements. By preserving all relevant data in a consistent, verifiable format, Graphite provides the transparency and accountability that organizations demand from AI solutions.
 
 ## Restorability
 
 Restorability in Graphite builds on top of idempotency, ensuring that whenever a workflow stops—due to an exception, human intervention, or any other cause—it always concludes at a point where an event has been successfully published. This guarantees that upon resuming the workflow for an unfinished assistant_request_id, any node subscribed to that newly published event is reactivated, effectively restarting the process from where it left off.
 
-Internally, Graphite uses offset-based consumption in each topic. Whenever a node publishes an event (including self-loops or circular dependencies), the system records the publish offset in `PublishToTopicEvent` instance. When a node later consumes that event, it updates a corresponding consumption offset in topic, and store the offset in `ConsumeFromTopicEvent`. If a workflow is interrupted before consumption offsets are written, the node remains subscribed to the “unconsumed” event. As a result, when the workflow recovers, the engine identifies these outstanding events and places the node(s) back into the execution queue.
+Internally, Graphite uses offset-based consumption in each topic. Whenever a node publishes an event (including self-loops or circular dependencies), the system records the publish offset in `PublishToTopicEvent` instance. When a node later consumes that event, it updates a corresponding consumption offset in topic, and store the offset in `ConsumeFromTopicEvent`. If a workflow is interrupted before consumption offsets are written, the node remains subscribed to the “unconsumed” event. As a result, when the workflow recovers, the engine identifies these outstanding events and places the node(s) back into the invoke queue.
 
 This mechanism effectively transforms cyclical or looping dependencies into a directed acyclic graph. The event store, combined with offset tracking, reveals which events have been fully processed and which remain pending, letting Graphite re-trigger only the incomplete parts of the workflow. The result is a resilient system that can resume from exactly where it stopped—without reprocessing entire segments or risking inconsistent states.

docs/docs/getting-started/quickstart.md

@@ -90,7 +90,7 @@ from pydantic import Field
 from pydantic import model_validator
 
 from grafi.assistants.assistant import Assistant
-from grafi.common.models.execution_context import ExecutionContext
+from grafi.common.models.invoke_context import InvokeContext
 from grafi.common.models.message import Message
 from grafi.common.topics.output_topic import agent_output_topic
 from grafi.common.topics.subscription_builder import SubscriptionBuilder
@@ -250,17 +250,17 @@ Create a `main.py` that will call the assistant created previously.
 import os
 import uuid
 
-from grafi.common.models.execution_context import ExecutionContext
+from grafi.common.models.invoke_context import InvokeContext
 from grafi.common.models.message import Message
 from <your react assistant path> import ReactAssistant
 
 api_key = "<your openai api key>"
 
 react_assistant = ReactAssistant.builder().api_key(api_key).build()
 
-execution_context = ExecutionContext(
+invoke_context = InvokeContext(
             conversation_id=uuid.uuid4().hex,
-            execution_id=uuid.uuid4().hex,
+            invoke_id=uuid.uuid4().hex,
             assistant_request_id=uuid.uuid4().hex,
         )
 
@@ -273,13 +273,13 @@ input_data = [
             )
         ]
 
-output = react_assistant.execute(execution_context, input_data)
+output = react_assistant.invoke(invoke_context, input_data)
 print(output[0].content)
 ```
 
 ## 5. Run the Application
 
-Use Poetry to execute the script inside the virtual environment:
+Use Poetry to invoke the script inside the virtual environment:
 
 <!-- ```bash
 poetry run python main.py

docs/docs/index.md

@@ -2,7 +2,7 @@
 
 **Graphite** is an open-source framework for creating **domain-specific AI assistants** via composable, agentic workflows. It emphasizes loose coupling and well-defined interfaces, enabling developers to construct flexible, modular systems. Each major layer – **assistant, node, tool,** and **workflow** – has a clear role in orchestrating or executing tasks, with events serving as the single source of truth for every state change or data exchange.
 
-This documentation details how **Graphite’s event-driven architecture** seamlessly supports complex business logic, from initial user requests through advanced tool integrations (e.g., LLM calls, function calls, RAG retrieval). Dedicated topics manage pub/sub operations, providing mechanisms for input, output, and human-in-the-loop interactions. Meanwhile, commands encapsulate execution logic for each tool, allowing nodes to delegate work without tight coupling.
+This documentation details how **Graphite’s event-driven architecture** seamlessly supports complex business logic, from initial user requests through advanced tool integrations (e.g., LLM calls, function calls, RAG retrieval). Dedicated topics manage pub/sub operations, providing mechanisms for input, output, and human-in-the-loop interactions. Meanwhile, commands encapsulate invoke logic for each tool, allowing nodes to delegate work without tight coupling.
 
 Four critical capabilities—**observability, idempotency, auditability,** and **restorability**—underpin Graphite’s suitability for production AI environments. Observability is achieved via event sourcing and OpenTelemetry-based tracing, idempotency through carefully managed event stores and retry logic, auditability by logging every action and data flow, and restorability by maintaining offset-based consumption records that let workflows resume exactly where they left off.