Gl/improve code base

docs/docs/getting-started/quickstart.md

@@ -77,11 +77,11 @@ You also need the following two dependencies for this guide.
 
 ---
 
-## Use Build-in ReAct Agent
+## Use Built-in ReAct Agent
 
 In graphite an agent is a specialized assistant that can handle events and perform actions based on the input it receives. We will create a ReAct agent that uses OpenAI's language model to process input, make function calls, and generate responses.
 
-Create a file named `react_agent_app.py` and create a build-in react-agent:
+Create a file named `react_agent_app.py` and create a built-in react-agent:
 
 ```python
 # react_agent_app.py

docs/docs/guide/configuring-event-store.md

@@ -172,8 +172,8 @@ import uuid
 from grafi.agents.react_agent import create_react_agent
 from grafi.common.containers.container import container
 from grafi.common.event_stores.event_store_postgres import EventStorePostgres
-from grafi.models.invoke_context import InvokeContext
-from grafi.models.message import Message
+from grafi.common.models.invoke_context import InvokeContext
+from grafi.common.models.message import Message
 
 postgres_event_store = EventStorePostgres(
     db_url="postgresql://postgres:postgres@localhost:5432/grafi_test_db",

docs/docs/guide/connecting-to-an-mcp-server.md

@@ -19,7 +19,7 @@ Before getting started, make sure you have:
 - OpenAI API key
 - Basic understanding of Python and AI concepts
 - Basic understanding of what MCP Servers are
-- Understand [Graphtie Assistants](../guide/getting-started-with-assistants.md)
+- Understand [Graphite Assistants](../guide/getting-started-with-assistants.md)
 
 ## Code Walkthrough
 
@@ -337,7 +337,7 @@ class StockAssistantBuilder(
 ```
 
 
-Graphtie is natively asychrnous, but you can chose to run syncrhous coroutines as well. For this case we are making a fully asynchronous workflow by overrding the  `async def run()` method of the `Assistant` class. In order to run this create a `main.py` that will instantiate the assistant and execute it asynchrnously.
+Graphite is natively asynchronous, but you can choose to run synchronous coroutines as well. For this case we are making a fully asynchronous workflow by overriding the `async def run()` method of the `Assistant` class. In order to run this create a `main.py` that will instantiate the assistant and execute it asynchronously.
 
 ```python
 #main.py
@@ -348,9 +348,9 @@ from typing import Dict
 
 from grafi.common.containers.container import container
 from grafi.common.events.topic_events.publish_to_topic_event import PublishToTopicEvent
-from grafi.models.invoke_context import InvokeContext
-from grafi.models.mcp_connections import StreamableHttpConnection
-from grafi.models.message import Message
+from grafi.common.models.invoke_context import InvokeContext
+from grafi.common.models.mcp_connections import StreamableHttpConnection
+from grafi.common.models.message import Message
 from grafi.tools.function_calls.impl.mcp_tool import MCPTool
 
 from assistant import StockAssistant

docs/docs/guide/creating-a-simple-workflow.md

@@ -43,8 +43,8 @@ The main function orchestrates the entire workflow. We start by defining a sampl
 
 ```python linenums="9"
 import uuid
-from grafi.models.message import Message
-from grafi.models.invoke_context import InvokeContext
+from grafi.common.models.message import Message
+from grafi.common.models.invoke_context import InvokeContext
 
 def main():
     user_input = "What is the capital of the United Kingdom"

docs/docs/guide/getting-started-with-assistants.md

@@ -108,7 +108,7 @@ class FinanceAssistantBuilder(AssistantBaseBuilder[FinanceAssistant]):
 - Provides methods for setting API key, model, and system message
 - Returns `self` for method chaining
 
-This class is used to set the fields from the `FinanceAssistant` the magic happens on the `builer` method up next.
+This class is used to set the fields from the `FinanceAssistant`. The magic happens in the `builder` method up next.
 
 ### Builder Pattern Implementation
 
@@ -189,9 +189,9 @@ Prepare input data and context for workflow execution:
 
 ```python
 from grafi.common.events.topic_events.publish_to_topic_event import PublishToTopicEvent
-from grafi.models.invoke_context import InvokeContext
+from grafi.common.models.invoke_context import InvokeContext
 from typing import Optional
-from grafi.models.message import Message
+from grafi.common.models.message import Message
 
 class FinanceAssistant(Assistant):
 

docs/docs/index.md

@@ -2,56 +2,47 @@
 
 **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 invoke 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, MCP servers, and external APIs). 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.
 
 Overall, **Graphite** offers a powerful, extensible foundation for building AI solutions that scale, adapt to evolving compliance needs, and gracefully handle failures or user-driven pauses. By combining a robust workflow engine, well-structured nodes and tools, and a complete event model, Graphite enables teams to develop sophisticated conversational agents and automated pipelines with confidence.
 
-## What is Graphite
-
-Graphite is an open-source platform that treats data as interconnected nodes and relationships, allowing you to:
-
-- **Process complex data relationships** with graph-based algorithms
-- **Visualize data connections** through interactive network diagrams
-- **Build analytical pipelines** that leverage graph structures
-- **Scale efficiently** with distributed processing capabilities
-
-Whether you're analyzing social networks, tracking data lineage, exploring knowledge graphs, or building recommendation systems, Graphite provides the tools and abstractions you need to work effectively with connected data.
-
 ## Key Features
 
-**Graph-Native Processing**: Built from the ground up to handle graph data structures efficiently, with optimized algorithms for common graph operations like traversals, clustering, and pathfinding.
+**Event-Driven Architecture**: Built on a pub/sub pattern where Topics manage message flow between Nodes, enabling loose coupling and flexible workflow composition.
 
-**Visual Analytics**: Interactive visualization tools that help you explore and understand complex data relationships through customizable network diagrams and graph layouts.
+**Modular Workflow Components**: Construct AI agents using composable layers - Assistants orchestrate Workflows, Workflows coordinate Nodes, and Nodes execute Tools.
 
-**Flexible Data Integration**: Connect to various data sources including databases, APIs, and file formats, with built-in support for common graph data formats like GraphML, GEXF, and JSON.
+**Multiple LLM Integrations**: Out-of-the-box support for OpenAI, Claude, Gemini, Ollama, DeepSeek, and OpenRouter, with a consistent interface across all providers.
 
-**Extensible Architecture**: Plugin-based system that allows you to extend functionality with custom algorithms, data connectors, and visualization components.
+**Function Calling Support**: Seamlessly integrate custom Python functions with LLMs through the FunctionCallTool, enabling agents to interact with external APIs and services.
 
-**Performance Optimized**: Efficient memory management and parallel processing capabilities designed to handle large-scale graph datasets.
+**MCP Server Integration**: Connect to Model Context Protocol servers for dynamic tool discovery and external data source access.
+
+**Production-Ready Features**: Built-in observability via OpenTelemetry, event sourcing for auditability, idempotent operations, and workflow restorability for fault tolerance.
 
 ## Who Should Use Graphite?
 
-Graphite is designed for data scientists, analysts, researchers, and developers who work with interconnected data, including:
+Graphite is designed for developers and teams building AI-powered applications, including:
 
-- **Data Scientists** building recommendation engines or fraud detection systems
-- **Business Analysts** exploring customer journey maps or organizational networks  
-- **Researchers** analyzing citation networks, protein interactions, or social structures
-- **Developers** building applications that require graph-based computations
+- **AI Engineers** building conversational agents with complex reasoning capabilities
+- **Backend Developers** integrating LLM functionality into production systems
+- **MLOps Teams** deploying observable, auditable AI workflows
+- **Researchers** prototyping multi-step AI agents with tool use
 
 ## Getting Started
 
 This documentation will guide you through:
 
 1. **Installation and Setup** - Get Graphite running in your environment
-2. **Core Concepts** - Understand graphs, nodes, edges, and data models
-3. **Data Import** - Load your data from various sources
-4. **Processing and Analysis** - Apply algorithms and transformations
-5. **Visualization** - Create interactive graph visualizations
-6. **Advanced Topics** - Custom plugins, performance tuning, and deployment
+2. **Core Concepts** - Understand the architecture: Assistants, Workflows, Nodes, and Tools
+3. **Building Workflows** - Create event-driven AI pipelines
+4. **Tool Integration** - Add LLMs, function calls, and MCP servers
+5. **Observability** - Configure tracing with Arize and Phoenix
+6. **Advanced Topics** - Event stores, workflow recovery, and custom tools
 
-Ready to dive in? Start with our [Quick Start Guide](./getting-started/quickstart.md) to get Graphite up and running in minutes, or explore the [Core Concepts](./user-guide/architecture.md) to understand the fundamentals of graph-based data processing.
+Ready to dive in? Start with our [Quick Start Guide](./getting-started/quickstart.md) to build your first AI agent, or explore the [Architecture](./user-guide/architecture.md) to understand how Graphite components work together.
 
 ## Community and Support
 
@@ -61,7 +52,3 @@ Graphite is actively developed and maintained by the open-source community. Join
 - **Issues and Feature Requests**: Use GitHub Issues for bug reports and feature requests
 - **Discussions**: Join community discussions and get help from other users
 - **Contributing**: Check out our contribution guidelines to help improve Graphite
-
----
-
-*This documentation covers Graphite v0.0.x.*

docs/docs/user-guide/command.md

@@ -258,7 +258,7 @@ Both commands enable a node to delegate specialized retrieval operations to thei
 Register custom commands for specific tool types:
 
 ```python
-from grafi.models.command import use_command
+from grafi.common.models.command import use_command
 
 @use_command(MyCustomCommand)
 class MySpecialTool(Tool):
@@ -306,10 +306,10 @@ Create custom commands when you need:
 
 ```python
 from typing import List
-from grafi.models.command import Command
+from grafi.common.models.command import Command
 from grafi.common.events.topic_events.consume_from_topic_event import ConsumeFromTopicEvent
-from grafi.models.invoke_context import InvokeContext
-from grafi.models.message import Messages
+from grafi.common.models.invoke_context import InvokeContext
+from grafi.common.models.message import Messages
 
 class DatabaseQueryCommand(Command):
     """Command for database query tools with caching and optimization."""

docs/docs/user-guide/event-interfaces.md

@@ -39,8 +39,8 @@ Published when a component sends data to a topic:
 
 ```python
 from grafi.common.events.topic_events.publish_to_topic_event import PublishToTopicEvent
-from grafi.models.invoke_context import InvokeContext
-from grafi.models.message import Message
+from grafi.common.models.invoke_context import InvokeContext
+from grafi.common.models.message import Message
 
 event = PublishToTopicEvent(
     publisher_name="ProcessorNode",
@@ -94,7 +94,7 @@ class MyAssistant(Assistant):
 
 ```python
 from grafi.nodes.node import Node
-from grafi.models.invoke_context import InvokeContext
+from grafi.common.models.invoke_context import InvokeContext
 from grafi.common.events.topic_events.consume_from_topic_event import ConsumeFromTopicEvent
 from grafi.common.events.topic_events.publish_to_topic_event import PublishToTopicEvent
 from typing import List, AsyncGenerator

docs/docs/user-guide/events/events.md

@@ -80,7 +80,7 @@ Emitted when an assistant is invoked with input data.
 
 ```python
 from grafi.common.events.assistant_events.assistant_invoke_event import AssistantInvokeEvent
-from grafi.models.message import Message
+from grafi.common.models.message import Message
 
 event = AssistantInvokeEvent(
     invoke_context=context,
@@ -307,8 +307,8 @@ The primary event used when consuming data from topics. This is the input format
 
 ```python
 from grafi.common.events.tool_events.tool_invoke_event import ToolInvokeEvent
-from grafi.models.invoke_context import InvokeContext
-from grafi.models.message import Message
+from grafi.common.models.invoke_context import InvokeContext
+from grafi.common.models.message import Message
 
 # Create invoke context
 context = InvokeContext(assistant_request_id="req_123")

docs/docs/user-guide/invoke-decorators.md

@@ -116,7 +116,7 @@ Records synchronous node invocations in event-driven workflows.
 
 ```python
 from grafi.common.decorators.record_node_invoke import record_node_invoke
-from grafi.models.invoke_context import InvokeContext
+from grafi.common.models.invoke_context import InvokeContext
 from grafi.common.events.topic_events.consume_from_topic_event import ConsumeFromTopicEvent
 from grafi.common.events.topic_events.publish_to_topic_event import PublishToTopicEvent
 from typing import List, AsyncGenerator

docs/docs/user-guide/models.md

@@ -32,7 +32,7 @@ In Graphite, various models provide the fundamental data structures that underpi
 ### Usage Example
 
 ```python
-from grafi.models.message import Message
+from grafi.common.models.message import Message
 
 # Creating a user message
 user_message = Message(
@@ -64,7 +64,7 @@ assistant_message = Message(
 ### InvokeContext Usage Example
 
 ```python
-from grafi.models.invoke_context import InvokeContext
+from grafi.common.models.invoke_context import InvokeContext
 
 context = InvokeContext(
     conversation_id="conv_123",
@@ -96,7 +96,7 @@ context = InvokeContext(
 ### Command Usage Example
 
 ```python
-from grafi.models.command import Command
+from grafi.common.models.command import Command
 from grafi.tools.tool import Tool
 
 # Create command from tool

docs/docs/user-guide/node.md

@@ -93,7 +93,7 @@ node = Node.builder()
     .build()
 
 # Node invoke signature
-from grafi.models.invoke_context import InvokeContext
+from grafi.common.models.invoke_context import InvokeContext
 from grafi.common.events.topic_events.consume_from_topic_event import ConsumeFromTopicEvent
 from grafi.common.events.topic_events.publish_to_topic_event import PublishToTopicEvent
 

docs/docs/user-guide/tools/function.md

@@ -65,7 +65,7 @@ function_tool = (
 
 ```python
 from grafi.tools.functions.function_tool import FunctionTool
-from grafi.models.message import Messages
+from grafi.common.models.message import Messages
 from pydantic import BaseModel
 
 class ProcessResult(BaseModel):

docs/docs/user-guide/tools/llm.md

@@ -53,7 +53,7 @@ llm_tool = (
 ### Function Calling Setup
 
 ```python
-from grafi.models.function_spec import FunctionSpec
+from grafi.common.models.function_spec import FunctionSpec
 
 # Create function specifications
 function_specs = [

docs/docs/user-guide/tools/ollama.md

@@ -70,7 +70,7 @@ ollama_tool = (
 
 ```python
 from grafi.tools.llms.impl.ollama_tool import OllamaTool
-from grafi.models.message import Message
+from grafi.common.models.message import Message
 
 # Create the tool
 ollama_tool = (
@@ -112,7 +112,7 @@ async def stream_example():
 ### Function Calling
 
 ```python
-from grafi.models.function_spec import FunctionSpec
+from grafi.common.models.function_spec import FunctionSpec
 
 # Add function specifications
 function_spec = FunctionSpec(

docs/docs/user-guide/tools/openai.md

@@ -68,7 +68,7 @@ openai_tool = (
 
 ```python
 from grafi.tools.llms.impl.openai_tool import OpenAITool
-from grafi.models.message import Message
+from grafi.common.models.message import Message
 
 # Create the tool
 openai_tool = (
@@ -110,7 +110,7 @@ async def stream_example():
 ### Function Calling
 
 ```python
-from grafi.models.function_spec import FunctionSpec
+from grafi.common.models.function_spec import FunctionSpec
 
 # Add function specifications
 function_spec = FunctionSpec(

docs/docs/user-guide/tools/tool.md

@@ -132,8 +132,8 @@ from pydantic import Field
 from openinference.semconv.trace import OpenInferenceSpanKindValues
 
 from grafi.tools.tool import Tool, ToolBuilder
-from grafi.models.invoke_context import InvokeContext
-from grafi.models.message import Message, Messages, MsgsAGen
+from grafi.common.models.invoke_context import InvokeContext
+from grafi.common.models.message import Message, Messages, MsgsAGen
 
 class TextProcessorTool(Tool):
     """A tool for processing text data."""
@@ -309,8 +309,8 @@ async def invoke(self, invoke_context: InvokeContext, input_data: Messages) -> M
 
 ```python
 import pytest
-from grafi.models.message import Message
-from grafi.models.invoke_context import InvokeContext
+from grafi.common.models.message import Message
+from grafi.common.models.invoke_context import InvokeContext
 
 @pytest.mark.asyncio
 async def test_tool_invoke():
@@ -332,7 +332,7 @@ async def test_tool_invoke():
 Tools integrate with Graphite's command system:
 
 ```python
-from grafi.models.command import use_command
+from grafi.common.models.command import use_command
 from grafi.tools.tool_command import ToolCommand
 
 @use_command(ToolCommand)

docs/docs/user-guide/topics/input_topics.md

@@ -87,8 +87,8 @@ Builder for constructing InWorkflowInputTopic instances.
 
 ```python
 from grafi.topics.topic import InputTopic
-from grafi.models.message import Message
-from grafi.models.invoke_context import InvokeContext
+from grafi.common.models.message import Message
+from grafi.common.models.invoke_context import InvokeContext
 
 # Create input topic
 input_topic = InputTopic(name="agent_input_topic")