Release/v1.2 (#457)

* Bump setup.py versions for 1.1

* PoC MCP server (#419)

* Very initial MCP server PoC for TrustGraph

* Put service on port 8000

* Add MCP container and packages to buildout

* Update docs for API/CLI changes in 1.0 (#421)

* Update some API basics for the 0.23/1.0 API change

* Add MCP container push (#425)

* Add command args to the MCP server (#426)

* Host and port parameters

* Added websocket arg

* More docs

* MCP client support (#427)

- MCP client service
- Tool request/response schema
- API gateway support for mcp-tool
- Message translation for tool request & response
- Make mcp-tool using configuration service for information
  about where the MCP services are.

* Feature/react call mcp (#428)

Key Features

  - MCP Tool Integration: Added core MCP tool support with ToolClientSpec and ToolClient classes
  - API Enhancement: New mcp_tool method for flow-specific tool invocation
  - CLI Tooling: New tg-invoke-mcp-tool command for testing MCP integration
  - React Agent Enhancement: Fixed and improved multi-tool invocation capabilities
  - Tool Management: Enhanced CLI for tool configuration and management

Changes

  - Added MCP tool invocation to API with flow-specific integration
  - Implemented ToolClientSpec and ToolClient for tool call handling
  - Updated agent-manager-react to invoke MCP tools with configurable types
  - Enhanced CLI with new commands and improved help text
  - Added comprehensive documentation for new CLI commands
  - Improved tool configuration management

Testing

  - Added tg-invoke-mcp-tool CLI command for isolated MCP integration testing
  - Enhanced agent capability to invoke multiple tools simultaneously

* Test suite executed from CI pipeline (#433)

* Test strategy & test cases

* Unit tests

* Integration tests

* Extending test coverage (#434)

* Contract tests

* Testing embeedings

* Agent unit tests

* Knowledge pipeline tests

* Turn on contract tests

* Increase storage test coverage (#435)

* Fixing storage and adding tests

* PR pipeline only runs quick tests

* Empty configuration is returned as empty list, previously was not in response (#436)

* Update config util to take files as well as command-line text (#437)

* Updated CLI invocation and config model for tools and mcp (#438)

* Updated CLI invocation and config model for tools and mcp

* CLI anomalies

* Tweaked the MCP tool implementation for new model

* Update agent implementation to match the new model

* Fix agent tools, now all tested

* Fixed integration tests

* Fix MCP delete tool params

* Update Python deps to 1.2

* Update to enable knowledge extraction using the agent framework (#439)

* Implement KG extraction agent (kg-extract-agent)

* Using ReAct framework (agent-manager-react)
 
* ReAct manager had an issue when emitting JSON, which conflicts which ReAct manager's own JSON messages, so refactored ReAct manager to use traditional ReAct messages, non-JSON structure.
 
* Minor refactor to take the prompt template client out of prompt-template so it can be more readily used by other modules. kg-extract-agent uses this framework.

* Migrate from setup.py to pyproject.toml (#440)

* Converted setup.py to pyproject.toml

* Modern package infrastructure as recommended by py docs

* Install missing build deps (#441)

* Install missing build deps (#442)

* Implement logging strategy (#444)

* Logging strategy and convert all prints() to logging invocations

* Fix/startup failure (#445)

* Fix loggin startup problems

* Fix logging startup problems (#446)

* Fix logging startup problems (#447)

* Fixed Mistral OCR to use current API (#448)

* Fixed Mistral OCR to use current API

* Added PDF decoder tests

* Fix Mistral OCR ident to be standard pdf-decoder (#450)

* Fix Mistral OCR ident to be standard pdf-decoder

* Correct test

* Schema structure refactor (#451)

* Write schema refactor spec

* Implemented schema refactor spec

* Structure data mvp (#452)

* Structured data tech spec

* Architecture principles

* New schemas

* Updated schemas and specs

* Object extractor

* Add .coveragerc

* New tests

* Cassandra object storage

* Trying to object extraction working, issues exist

* Validate librarian collection (#453)

* Fix token chunker, broken API invocation (#454)

* Fix token chunker, broken API invocation (#455)

* Knowledge load utility CLI (#456)

* Knowledge loader

* More tests

tests/README.prompts

@@ -1,27 +0,0 @@
-
-test-prompt-... is tested with this prompt set...
-
-prompt-template \
-    -p pulsar://localhost:6650 \
-    --system-prompt 'You are a {{attitude}}, you are called {{name}}' \
-    --global-term \
-        'name=Craig' \
-        'attitude=LOUD, SHOUTY ANNOYING BOT' \
-    --prompt \
-        'question={{question}}' \
-        'french-question={{question}}' \
-        "analyze=Find the name and age in this text, and output a JSON structure containing just the name and age fields: {{description}}.  Don't add markup, just output the raw JSON object." \
-        "graph-query=Study the following knowledge graph, and then answer the question.\\n\nGraph:\\n{% for edge in knowledge %}({{edge.0}})-[{{edge.1}}]->({{edge.2}})\\n{%endfor%}\\nQuestion:\\n{{question}}" \
-        "extract-definition=Analyse the text provided, and then return a list of terms and definitions.  The output should be a JSON array, each item in the array is an object with fields 'term' and 'definition'.Don't add markup, just output the raw JSON object.  Here is the text:\\n{{text}}" \
-    --prompt-response-type \
-        'question=text' \
-        'analyze=json' \
-        'graph-query=text' \
-        'extract-definition=json' \
-    --prompt-term \
-        'question=name:Bonny' \
-        'french-question=attitude:French-speaking bot' \
-    --prompt-schema \
-        'analyze={ "type" : "object", "properties" : { "age": { "type" : "number" }, "name": { "type" : "string" } } }' \
-        'extract-definition={ "type": "array", "items": { "type": "object", "properties": { "term": { "type": "string" }, "definition": { "type": "string" } }, "required": [ "term", "definition" ] } }'
-    

tests/__init__.py

@@ -0,0 +1,3 @@
+"""
+TrustGraph test suite
+"""

tests/contract/README.md

@@ -0,0 +1,243 @@
+# Contract Tests for TrustGraph
+
+This directory contains contract tests that verify service interface contracts, message schemas, and API compatibility across the TrustGraph microservices architecture.
+
+## Overview
+
+Contract tests ensure that:
+- **Message schemas remain compatible** across service versions
+- **API interfaces stay stable** for consumers
+- **Service communication contracts** are maintained
+- **Schema evolution** doesn't break existing integrations
+
+## Test Categories
+
+### 1. Pulsar Message Schema Contracts (`test_message_contracts.py`)
+
+Tests the contracts for all Pulsar message schemas used in TrustGraph service communication.
+
+#### **Coverage:**
+- ✅ **Text Completion Messages**: `TextCompletionRequest` ↔ `TextCompletionResponse`
+- ✅ **Document RAG Messages**: `DocumentRagQuery` ↔ `DocumentRagResponse`
+- ✅ **Agent Messages**: `AgentRequest` ↔ `AgentResponse` ↔ `AgentStep`
+- ✅ **Graph Messages**: `Chunk` → `Triple` → `Triples` → `EntityContext`
+- ✅ **Common Messages**: `Metadata`, `Value`, `Error` schemas
+- ✅ **Message Routing**: Properties, correlation IDs, routing keys
+- ✅ **Schema Evolution**: Backward/forward compatibility testing
+- ✅ **Serialization**: Schema validation and data integrity
+
+#### **Key Features:**
+- **Schema Validation**: Ensures all message schemas accept valid data and reject invalid data
+- **Field Contracts**: Validates required vs optional fields and type constraints
+- **Nested Schema Support**: Tests complex schemas with embedded objects and arrays
+- **Routing Contracts**: Validates message properties and routing conventions
+- **Evolution Testing**: Backward compatibility and schema versioning support
+
+## Running Contract Tests
+
+### Run All Contract Tests
+```bash
+pytest tests/contract/ -m contract
+```
+
+### Run Specific Contract Test Categories
+```bash
+# Message schema contracts
+pytest tests/contract/test_message_contracts.py -v
+
+# Specific test class
+pytest tests/contract/test_message_contracts.py::TestTextCompletionMessageContracts -v
+
+# Schema evolution tests
+pytest tests/contract/test_message_contracts.py::TestSchemaEvolutionContracts -v
+```
+
+### Run with Coverage
+```bash
+pytest tests/contract/ -m contract --cov=trustgraph.schema --cov-report=html
+```
+
+## Contract Test Patterns
+
+### 1. Schema Validation Pattern
+```python
+@pytest.mark.contract
+def test_schema_contract(self, sample_message_data):
+    """Test that schema accepts valid data and rejects invalid data"""
+    # Arrange
+    valid_data = sample_message_data["SchemaName"]
+    
+    # Act & Assert
+    assert validate_schema_contract(SchemaClass, valid_data)
+    
+    # Test field constraints
+    instance = SchemaClass(**valid_data)
+    assert hasattr(instance, 'required_field')
+    assert isinstance(instance.required_field, expected_type)
+```
+
+### 2. Serialization Contract Pattern
+```python
+@pytest.mark.contract  
+def test_serialization_contract(self, sample_message_data):
+    """Test schema serialization/deserialization contracts"""
+    # Arrange
+    data = sample_message_data["SchemaName"]
+    
+    # Act & Assert
+    assert serialize_deserialize_test(SchemaClass, data)
+```
+
+### 3. Evolution Contract Pattern
+```python
+@pytest.mark.contract
+def test_backward_compatibility_contract(self, schema_evolution_data):
+    """Test that new schema versions accept old data formats"""
+    # Arrange
+    old_version_data = schema_evolution_data["SchemaName_v1"]
+    
+    # Act - Should work with current schema
+    instance = CurrentSchema(**old_version_data)
+    
+    # Assert - Required fields maintained
+    assert instance.required_field == expected_value
+```
+
+## Schema Registry
+
+The contract tests maintain a registry of all TrustGraph schemas:
+
+```python
+schema_registry = {
+    # Text Completion
+    "TextCompletionRequest": TextCompletionRequest,
+    "TextCompletionResponse": TextCompletionResponse,
+    
+    # Document RAG  
+    "DocumentRagQuery": DocumentRagQuery,
+    "DocumentRagResponse": DocumentRagResponse,
+    
+    # Agent
+    "AgentRequest": AgentRequest,
+    "AgentResponse": AgentResponse,
+    
+    # Graph/Knowledge
+    "Chunk": Chunk,
+    "Triple": Triple,
+    "Triples": Triples,
+    "Value": Value,
+    
+    # Common
+    "Metadata": Metadata,
+    "Error": Error,
+}
+```
+
+## Message Contract Specifications
+
+### Text Completion Service Contract
+```yaml
+TextCompletionRequest:
+  required_fields: [system, prompt]
+  field_types:
+    system: string
+    prompt: string
+
+TextCompletionResponse:
+  required_fields: [error, response, model]  
+  field_types:
+    error: Error | null
+    response: string | null
+    in_token: integer | null
+    out_token: integer | null
+    model: string
+```
+
+### Document RAG Service Contract
+```yaml
+DocumentRagQuery:
+  required_fields: [query, user, collection]
+  field_types:
+    query: string
+    user: string
+    collection: string
+    doc_limit: integer
+
+DocumentRagResponse:
+  required_fields: [error, response]
+  field_types:
+    error: Error | null
+    response: string | null
+```
+
+### Agent Service Contract
+```yaml
+AgentRequest:
+  required_fields: [question, history]
+  field_types:
+    question: string
+    plan: string
+    state: string
+    history: Array<AgentStep>
+
+AgentResponse:
+  required_fields: [error]
+  field_types:
+    answer: string | null
+    error: Error | null
+    thought: string | null
+    observation: string | null
+```
+
+## Best Practices
+
+### Contract Test Design
+1. **Test Both Valid and Invalid Data**: Ensure schemas accept valid data and reject invalid data
+2. **Verify Field Constraints**: Test type constraints, required vs optional fields
+3. **Test Nested Schemas**: Validate complex objects with embedded schemas
+4. **Test Array Fields**: Ensure array serialization maintains order and content
+5. **Test Optional Fields**: Verify optional field handling in serialization
+
+### Schema Evolution
+1. **Backward Compatibility**: New schema versions must accept old message formats
+2. **Required Field Stability**: Required fields should never become optional or be removed
+3. **Additive Changes**: New fields should be optional to maintain compatibility
+4. **Deprecation Strategy**: Plan deprecation path for schema changes
+
+### Error Handling
+1. **Error Schema Consistency**: All error responses use consistent Error schema
+2. **Error Type Contracts**: Error types follow naming conventions
+3. **Error Message Format**: Error messages provide actionable information
+
+## Adding New Contract Tests
+
+When adding new message schemas or modifying existing ones:
+
+1. **Add to Schema Registry**: Update `conftest.py` schema registry
+2. **Add Sample Data**: Create valid sample data in `conftest.py`
+3. **Create Contract Tests**: Follow existing patterns for validation
+4. **Test Evolution**: Add backward compatibility tests
+5. **Update Documentation**: Document schema contracts in this README
+
+## Integration with CI/CD
+
+Contract tests should be run:
+- **On every commit** to detect breaking changes early
+- **Before releases** to ensure API stability
+- **On schema changes** to validate compatibility
+- **In dependency updates** to catch breaking changes
+
+```bash
+# CI/CD pipeline command
+pytest tests/contract/ -m contract --junitxml=contract-test-results.xml
+```
+
+## Contract Test Results
+
+Contract tests provide:
+- ✅ **Schema Compatibility Reports**: Which schemas pass/fail validation
+- ✅ **Breaking Change Detection**: Identifies contract violations
+- ✅ **Evolution Validation**: Confirms backward compatibility
+- ✅ **Field Constraint Verification**: Validates data type contracts
+
+This ensures that TrustGraph services can evolve independently while maintaining stable, compatible interfaces for all service communication.

tests/contract/conftest.py

@@ -0,0 +1,224 @@
+"""
+Contract test fixtures and configuration
+
+This file provides common fixtures for contract testing, focusing on
+message schema validation, API interface contracts, and service compatibility.
+"""
+
+import pytest
+import json
+from typing import Dict, Any, Type
+from pulsar.schema import Record
+from unittest.mock import MagicMock
+
+from trustgraph.schema import (
+    TextCompletionRequest, TextCompletionResponse,
+    DocumentRagQuery, DocumentRagResponse,
+    AgentRequest, AgentResponse, AgentStep,
+    Chunk, Triple, Triples, Value, Error,
+    EntityContext, EntityContexts,
+    GraphEmbeddings, EntityEmbeddings,
+    Metadata
+)
+
+
+@pytest.fixture
+def schema_registry():
+    """Registry of all Pulsar schemas used in TrustGraph"""
+    return {
+        # Text Completion
+        "TextCompletionRequest": TextCompletionRequest,
+        "TextCompletionResponse": TextCompletionResponse,
+        
+        # Document RAG
+        "DocumentRagQuery": DocumentRagQuery,
+        "DocumentRagResponse": DocumentRagResponse,
+        
+        # Agent
+        "AgentRequest": AgentRequest,
+        "AgentResponse": AgentResponse,
+        "AgentStep": AgentStep,
+        
+        # Graph
+        "Chunk": Chunk,
+        "Triple": Triple,
+        "Triples": Triples,
+        "Value": Value,
+        "Error": Error,
+        "EntityContext": EntityContext,
+        "EntityContexts": EntityContexts,
+        "GraphEmbeddings": GraphEmbeddings,
+        "EntityEmbeddings": EntityEmbeddings,
+        
+        # Common
+        "Metadata": Metadata,
+    }
+
+
+@pytest.fixture
+def sample_message_data():
+    """Sample message data for contract testing"""
+    return {
+        "TextCompletionRequest": {
+            "system": "You are a helpful assistant.",
+            "prompt": "What is machine learning?"
+        },
+        "TextCompletionResponse": {
+            "error": None,
+            "response": "Machine learning is a subset of artificial intelligence.",
+            "in_token": 50,
+            "out_token": 100,
+            "model": "gpt-3.5-turbo"
+        },
+        "DocumentRagQuery": {
+            "query": "What is artificial intelligence?",
+            "user": "test_user",
+            "collection": "test_collection",
+            "doc_limit": 10
+        },
+        "DocumentRagResponse": {
+            "error": None,
+            "response": "Artificial intelligence is the simulation of human intelligence in machines."
+        },
+        "AgentRequest": {
+            "question": "What is machine learning?",
+            "plan": "",
+            "state": "",
+            "history": []
+        },
+        "AgentResponse": {
+            "answer": "Machine learning is a subset of AI.",
+            "error": None,
+            "thought": "I need to provide information about machine learning.",
+            "observation": None
+        },
+        "Metadata": {
+            "id": "test-doc-123",
+            "user": "test_user",
+            "collection": "test_collection",
+            "metadata": []
+        },
+        "Value": {
+            "value": "http://example.com/entity",
+            "is_uri": True,
+            "type": ""
+        },
+        "Triple": {
+            "s": Value(
+                value="http://example.com/subject",
+                is_uri=True,
+                type=""
+            ),
+            "p": Value(
+                value="http://example.com/predicate", 
+                is_uri=True,
+                type=""
+            ),
+            "o": Value(
+                value="Object value",
+                is_uri=False,
+                type=""
+            )
+        }
+    }
+
+
+@pytest.fixture
+def invalid_message_data():
+    """Invalid message data for contract validation testing"""
+    return {
+        "TextCompletionRequest": [
+            {"system": None, "prompt": "test"},  # Invalid system (None)
+            {"system": "test", "prompt": None},  # Invalid prompt (None)
+            {"system": 123, "prompt": "test"},   # Invalid system (not string)
+            {},  # Missing required fields
+        ],
+        "DocumentRagQuery": [
+            {"query": None, "user": "test", "collection": "test", "doc_limit": 10},  # Invalid query
+            {"query": "test", "user": None, "collection": "test", "doc_limit": 10},  # Invalid user
+            {"query": "test", "user": "test", "collection": "test", "doc_limit": -1},  # Invalid doc_limit
+            {"query": "test"},  # Missing required fields
+        ],
+        "Value": [
+            {"value": None, "is_uri": True, "type": ""},  # Invalid value (None)
+            {"value": "test", "is_uri": "not_boolean", "type": ""},  # Invalid is_uri
+            {"value": 123, "is_uri": True, "type": ""},  # Invalid value (not string)
+        ]
+    }
+
+
+@pytest.fixture
+def message_properties():
+    """Standard message properties for contract testing"""
+    return {
+        "id": "test-message-123",
+        "routing_key": "test.routing.key",
+        "timestamp": "2024-01-01T00:00:00Z",
+        "source_service": "test-service",
+        "correlation_id": "correlation-123"
+    }
+
+
+@pytest.fixture
+def schema_evolution_data():
+    """Data for testing schema evolution and backward compatibility"""
+    return {
+        "TextCompletionRequest_v1": {
+            "system": "You are helpful.",
+            "prompt": "Test prompt"
+        },
+        "TextCompletionRequest_v2": {
+            "system": "You are helpful.",
+            "prompt": "Test prompt",
+            "temperature": 0.7,  # New field
+            "max_tokens": 100    # New field
+        },
+        "TextCompletionResponse_v1": {
+            "error": None,
+            "response": "Test response",
+            "model": "gpt-3.5-turbo"
+        },
+        "TextCompletionResponse_v2": {
+            "error": None,
+            "response": "Test response",
+            "in_token": 50,      # New field
+            "out_token": 100,    # New field
+            "model": "gpt-3.5-turbo"
+        }
+    }
+
+
+def validate_schema_contract(schema_class: Type[Record], data: Dict[str, Any]) -> bool:
+    """Helper function to validate schema contracts"""
+    try:
+        # Create instance from data
+        instance = schema_class(**data)
+        
+        # Verify all fields are accessible
+        for field_name in data.keys():
+            assert hasattr(instance, field_name)
+            assert getattr(instance, field_name) == data[field_name]
+        
+        return True
+    except Exception:
+        return False
+
+
+def serialize_deserialize_test(schema_class: Type[Record], data: Dict[str, Any]) -> bool:
+    """Helper function to test serialization/deserialization"""
+    try:
+        # Create instance
+        instance = schema_class(**data)
+        
+        # This would test actual Pulsar serialization if we had the client
+        # For now, we test the schema construction and field access
+        for field_name, field_value in data.items():
+            assert getattr(instance, field_name) == field_value
+        
+        return True
+    except Exception:
+        return False
+
+
+# Test markers for contract tests
+pytestmark = pytest.mark.contract

tests/contract/test_message_contracts.py

@@ -0,0 +1,614 @@
+"""
+Contract tests for Pulsar Message Schemas
+
+These tests verify the contracts for all Pulsar message schemas used in TrustGraph,
+ensuring schema compatibility, serialization contracts, and service interface stability.
+Following the TEST_STRATEGY.md approach for contract testing.
+"""
+
+import pytest
+import json
+from typing import Dict, Any, Type
+from pulsar.schema import Record
+
+from trustgraph.schema import (
+    TextCompletionRequest, TextCompletionResponse,
+    DocumentRagQuery, DocumentRagResponse,
+    AgentRequest, AgentResponse, AgentStep,
+    Chunk, Triple, Triples, Value, Error,
+    EntityContext, EntityContexts,
+    GraphEmbeddings, EntityEmbeddings,
+    Metadata, Field, RowSchema,
+    StructuredDataSubmission, ExtractedObject,
+    NLPToStructuredQueryRequest, NLPToStructuredQueryResponse,
+    StructuredQueryRequest, StructuredQueryResponse,
+    StructuredObjectEmbedding
+)
+from .conftest import validate_schema_contract, serialize_deserialize_test
+
+
+@pytest.mark.contract
+class TestTextCompletionMessageContracts:
+    """Contract tests for Text Completion message schemas"""
+
+    def test_text_completion_request_schema_contract(self, sample_message_data):
+        """Test TextCompletionRequest schema contract"""
+        # Arrange
+        request_data = sample_message_data["TextCompletionRequest"]
+
+        # Act & Assert
+        assert validate_schema_contract(TextCompletionRequest, request_data)
+        
+        # Test required fields
+        request = TextCompletionRequest(**request_data)
+        assert hasattr(request, 'system')
+        assert hasattr(request, 'prompt')
+        assert isinstance(request.system, str)
+        assert isinstance(request.prompt, str)
+
+    def test_text_completion_response_schema_contract(self, sample_message_data):
+        """Test TextCompletionResponse schema contract"""
+        # Arrange
+        response_data = sample_message_data["TextCompletionResponse"]
+
+        # Act & Assert
+        assert validate_schema_contract(TextCompletionResponse, response_data)
+        
+        # Test required fields
+        response = TextCompletionResponse(**response_data)
+        assert hasattr(response, 'error')
+        assert hasattr(response, 'response')
+        assert hasattr(response, 'in_token')
+        assert hasattr(response, 'out_token')
+        assert hasattr(response, 'model')
+
+    def test_text_completion_request_serialization_contract(self, sample_message_data):
+        """Test TextCompletionRequest serialization/deserialization contract"""
+        # Arrange
+        request_data = sample_message_data["TextCompletionRequest"]
+
+        # Act & Assert
+        assert serialize_deserialize_test(TextCompletionRequest, request_data)
+
+    def test_text_completion_response_serialization_contract(self, sample_message_data):
+        """Test TextCompletionResponse serialization/deserialization contract"""
+        # Arrange
+        response_data = sample_message_data["TextCompletionResponse"]
+
+        # Act & Assert
+        assert serialize_deserialize_test(TextCompletionResponse, response_data)
+
+    def test_text_completion_request_field_constraints(self):
+        """Test TextCompletionRequest field type constraints"""
+        # Test valid data
+        valid_request = TextCompletionRequest(
+            system="You are helpful.",
+            prompt="Test prompt"
+        )
+        assert valid_request.system == "You are helpful."
+        assert valid_request.prompt == "Test prompt"
+
+    def test_text_completion_response_field_constraints(self):
+        """Test TextCompletionResponse field type constraints"""
+        # Test valid response with no error
+        valid_response = TextCompletionResponse(
+            error=None,
+            response="Test response",
+            in_token=50,
+            out_token=100,
+            model="gpt-3.5-turbo"
+        )
+        assert valid_response.error is None
+        assert valid_response.response == "Test response"
+        assert valid_response.in_token == 50
+        assert valid_response.out_token == 100
+        assert valid_response.model == "gpt-3.5-turbo"
+
+        # Test response with error
+        error_response = TextCompletionResponse(
+            error=Error(type="rate-limit", message="Rate limit exceeded"),
+            response=None,
+            in_token=None,
+            out_token=None,
+            model=None
+        )
+        assert error_response.error is not None
+        assert error_response.error.type == "rate-limit"
+        assert error_response.response is None
+
+
+@pytest.mark.contract
+class TestDocumentRagMessageContracts:
+    """Contract tests for Document RAG message schemas"""
+
+    def test_document_rag_query_schema_contract(self, sample_message_data):
+        """Test DocumentRagQuery schema contract"""
+        # Arrange
+        query_data = sample_message_data["DocumentRagQuery"]
+
+        # Act & Assert
+        assert validate_schema_contract(DocumentRagQuery, query_data)
+        
+        # Test required fields
+        query = DocumentRagQuery(**query_data)
+        assert hasattr(query, 'query')
+        assert hasattr(query, 'user')
+        assert hasattr(query, 'collection')
+        assert hasattr(query, 'doc_limit')
+
+    def test_document_rag_response_schema_contract(self, sample_message_data):
+        """Test DocumentRagResponse schema contract"""
+        # Arrange
+        response_data = sample_message_data["DocumentRagResponse"]
+
+        # Act & Assert
+        assert validate_schema_contract(DocumentRagResponse, response_data)
+        
+        # Test required fields
+        response = DocumentRagResponse(**response_data)
+        assert hasattr(response, 'error')
+        assert hasattr(response, 'response')
+
+    def test_document_rag_query_field_constraints(self):
+        """Test DocumentRagQuery field constraints"""
+        # Test valid query
+        valid_query = DocumentRagQuery(
+            query="What is AI?",
+            user="test_user",
+            collection="test_collection",
+            doc_limit=5
+        )
+        assert valid_query.query == "What is AI?"
+        assert valid_query.user == "test_user"
+        assert valid_query.collection == "test_collection"
+        assert valid_query.doc_limit == 5
+
+    def test_document_rag_response_error_contract(self):
+        """Test DocumentRagResponse error handling contract"""
+        # Test successful response
+        success_response = DocumentRagResponse(
+            error=None,
+            response="AI is artificial intelligence."
+        )
+        assert success_response.error is None
+        assert success_response.response == "AI is artificial intelligence."
+
+        # Test error response
+        error_response = DocumentRagResponse(
+            error=Error(type="no-documents", message="No documents found"),
+            response=None
+        )
+        assert error_response.error is not None
+        assert error_response.error.type == "no-documents"
+        assert error_response.response is None
+
+
+@pytest.mark.contract
+class TestAgentMessageContracts:
+    """Contract tests for Agent message schemas"""
+
+    def test_agent_request_schema_contract(self, sample_message_data):
+        """Test AgentRequest schema contract"""
+        # Arrange
+        request_data = sample_message_data["AgentRequest"]
+
+        # Act & Assert
+        assert validate_schema_contract(AgentRequest, request_data)
+        
+        # Test required fields
+        request = AgentRequest(**request_data)
+        assert hasattr(request, 'question')
+        assert hasattr(request, 'plan')
+        assert hasattr(request, 'state')
+        assert hasattr(request, 'history')
+
+    def test_agent_response_schema_contract(self, sample_message_data):
+        """Test AgentResponse schema contract"""
+        # Arrange
+        response_data = sample_message_data["AgentResponse"]
+
+        # Act & Assert
+        assert validate_schema_contract(AgentResponse, response_data)
+        
+        # Test required fields
+        response = AgentResponse(**response_data)
+        assert hasattr(response, 'answer')
+        assert hasattr(response, 'error')
+        assert hasattr(response, 'thought')
+        assert hasattr(response, 'observation')
+
+    def test_agent_step_schema_contract(self):
+        """Test AgentStep schema contract"""
+        # Arrange
+        step_data = {
+            "thought": "I need to search for information",
+            "action": "knowledge_query",
+            "arguments": {"question": "What is AI?"},
+            "observation": "AI is artificial intelligence"
+        }
+
+        # Act & Assert
+        assert validate_schema_contract(AgentStep, step_data)
+        
+        step = AgentStep(**step_data)
+        assert step.thought == "I need to search for information"
+        assert step.action == "knowledge_query"
+        assert step.arguments == {"question": "What is AI?"}
+        assert step.observation == "AI is artificial intelligence"
+
+    def test_agent_request_with_history_contract(self):
+        """Test AgentRequest with conversation history contract"""
+        # Arrange
+        history_steps = [
+            AgentStep(
+                thought="First thought",
+                action="first_action",
+                arguments={"param": "value"},
+                observation="First observation"
+            ),
+            AgentStep(
+                thought="Second thought",
+                action="second_action", 
+                arguments={"param2": "value2"},
+                observation="Second observation"
+            )
+        ]
+
+        # Act
+        request = AgentRequest(
+            question="What comes next?",
+            plan="Multi-step plan",
+            state="processing",
+            history=history_steps
+        )
+
+        # Assert
+        assert len(request.history) == 2
+        assert request.history[0].thought == "First thought"
+        assert request.history[1].action == "second_action"
+
+
+@pytest.mark.contract
+class TestGraphMessageContracts:
+    """Contract tests for Graph/Knowledge message schemas"""
+
+    def test_value_schema_contract(self, sample_message_data):
+        """Test Value schema contract"""
+        # Arrange
+        value_data = sample_message_data["Value"]
+
+        # Act & Assert
+        assert validate_schema_contract(Value, value_data)
+        
+        # Test URI value
+        uri_value = Value(**value_data)
+        assert uri_value.value == "http://example.com/entity"
+        assert uri_value.is_uri is True
+
+        # Test literal value
+        literal_value = Value(
+            value="Literal text value",
+            is_uri=False,
+            type=""
+        )
+        assert literal_value.value == "Literal text value"
+        assert literal_value.is_uri is False
+
+    def test_triple_schema_contract(self, sample_message_data):
+        """Test Triple schema contract"""
+        # Arrange
+        triple_data = sample_message_data["Triple"]
+
+        # Act & Assert - Triple uses Value objects, not dict validation
+        triple = Triple(
+            s=triple_data["s"],
+            p=triple_data["p"], 
+            o=triple_data["o"]
+        )
+        assert triple.s.value == "http://example.com/subject"
+        assert triple.p.value == "http://example.com/predicate"
+        assert triple.o.value == "Object value"
+        assert triple.s.is_uri is True
+        assert triple.p.is_uri is True
+        assert triple.o.is_uri is False
+
+    def test_triples_schema_contract(self, sample_message_data):
+        """Test Triples (batch) schema contract"""
+        # Arrange
+        metadata = Metadata(**sample_message_data["Metadata"])
+        triple = Triple(**sample_message_data["Triple"])
+        
+        triples_data = {
+            "metadata": metadata,
+            "triples": [triple]
+        }
+
+        # Act & Assert
+        assert validate_schema_contract(Triples, triples_data)
+        
+        triples = Triples(**triples_data)
+        assert triples.metadata.id == "test-doc-123"
+        assert len(triples.triples) == 1
+        assert triples.triples[0].s.value == "http://example.com/subject"
+
+    def test_chunk_schema_contract(self, sample_message_data):
+        """Test Chunk schema contract"""
+        # Arrange
+        metadata = Metadata(**sample_message_data["Metadata"])
+        chunk_data = {
+            "metadata": metadata,
+            "chunk": b"This is a text chunk for processing"
+        }
+
+        # Act & Assert
+        assert validate_schema_contract(Chunk, chunk_data)
+        
+        chunk = Chunk(**chunk_data)
+        assert chunk.metadata.id == "test-doc-123"
+        assert chunk.chunk == b"This is a text chunk for processing"
+
+    def test_entity_context_schema_contract(self):
+        """Test EntityContext schema contract"""
+        # Arrange
+        entity_value = Value(value="http://example.com/entity", is_uri=True, type="")
+        entity_context_data = {
+            "entity": entity_value,
+            "context": "Context information about the entity"
+        }
+
+        # Act & Assert
+        assert validate_schema_contract(EntityContext, entity_context_data)
+        
+        entity_context = EntityContext(**entity_context_data)
+        assert entity_context.entity.value == "http://example.com/entity"
+        assert entity_context.context == "Context information about the entity"
+
+    def test_entity_contexts_batch_schema_contract(self, sample_message_data):
+        """Test EntityContexts (batch) schema contract"""
+        # Arrange
+        metadata = Metadata(**sample_message_data["Metadata"])
+        entity_value = Value(value="http://example.com/entity", is_uri=True, type="")
+        entity_context = EntityContext(
+            entity=entity_value,
+            context="Entity context"
+        )
+        
+        entity_contexts_data = {
+            "metadata": metadata,
+            "entities": [entity_context]
+        }
+
+        # Act & Assert
+        assert validate_schema_contract(EntityContexts, entity_contexts_data)
+        
+        entity_contexts = EntityContexts(**entity_contexts_data)
+        assert entity_contexts.metadata.id == "test-doc-123"
+        assert len(entity_contexts.entities) == 1
+        assert entity_contexts.entities[0].context == "Entity context"
+
+
+@pytest.mark.contract
+class TestMetadataMessageContracts:
+    """Contract tests for Metadata and common message schemas"""
+
+    def test_metadata_schema_contract(self, sample_message_data):
+        """Test Metadata schema contract"""
+        # Arrange
+        metadata_data = sample_message_data["Metadata"]
+
+        # Act & Assert
+        assert validate_schema_contract(Metadata, metadata_data)
+        
+        metadata = Metadata(**metadata_data)
+        assert metadata.id == "test-doc-123"
+        assert metadata.user == "test_user"
+        assert metadata.collection == "test_collection"
+        assert isinstance(metadata.metadata, list)
+
+    def test_metadata_with_triples_contract(self, sample_message_data):
+        """Test Metadata with embedded triples contract"""
+        # Arrange
+        triple = Triple(**sample_message_data["Triple"])
+        metadata_data = {
+            "id": "doc-with-triples",
+            "user": "test_user",
+            "collection": "test_collection",
+            "metadata": [triple]
+        }
+
+        # Act & Assert
+        assert validate_schema_contract(Metadata, metadata_data)
+        
+        metadata = Metadata(**metadata_data)
+        assert len(metadata.metadata) == 1
+        assert metadata.metadata[0].s.value == "http://example.com/subject"
+
+    def test_error_schema_contract(self):
+        """Test Error schema contract"""
+        # Arrange
+        error_data = {
+            "type": "validation-error",
+            "message": "Invalid input data provided"
+        }
+
+        # Act & Assert
+        assert validate_schema_contract(Error, error_data)
+        
+        error = Error(**error_data)
+        assert error.type == "validation-error"
+        assert error.message == "Invalid input data provided"
+
+
+@pytest.mark.contract
+class TestMessageRoutingContracts:
+    """Contract tests for message routing and properties"""
+
+    def test_message_property_contracts(self, message_properties):
+        """Test standard message property contracts"""
+        # Act & Assert
+        required_properties = ["id", "routing_key", "timestamp", "source_service"]
+        
+        for prop in required_properties:
+            assert prop in message_properties
+            assert message_properties[prop] is not None
+            assert isinstance(message_properties[prop], str)
+
+    def test_message_id_format_contract(self, message_properties):
+        """Test message ID format contract"""
+        # Act & Assert
+        message_id = message_properties["id"]
+        assert isinstance(message_id, str)
+        assert len(message_id) > 0
+        # Message IDs should follow a consistent format
+        assert "test-message-" in message_id
+
+    def test_routing_key_format_contract(self, message_properties):
+        """Test routing key format contract"""
+        # Act & Assert
+        routing_key = message_properties["routing_key"]
+        assert isinstance(routing_key, str)
+        assert "." in routing_key  # Should use dot notation
+        assert routing_key.count(".") >= 2  # Should have at least 3 parts
+
+    def test_correlation_id_contract(self, message_properties):
+        """Test correlation ID contract for request/response tracking"""
+        # Act & Assert
+        correlation_id = message_properties.get("correlation_id")
+        if correlation_id is not None:
+            assert isinstance(correlation_id, str)
+            assert len(correlation_id) > 0
+
+
+@pytest.mark.contract
+class TestSchemaEvolutionContracts:
+    """Contract tests for schema evolution and backward compatibility"""
+
+    def test_schema_backward_compatibility(self, schema_evolution_data):
+        """Test schema backward compatibility"""
+        # Test that v1 data can still be processed
+        v1_request = schema_evolution_data["TextCompletionRequest_v1"]
+        
+        # Should work with current schema (optional fields default)
+        request = TextCompletionRequest(**v1_request)
+        assert request.system == "You are helpful."
+        assert request.prompt == "Test prompt"
+
+    def test_schema_forward_compatibility(self, schema_evolution_data):
+        """Test schema forward compatibility with new fields"""
+        # Test that v2 data works with additional fields
+        v2_request = schema_evolution_data["TextCompletionRequest_v2"]
+        
+        # Current schema should handle new fields gracefully
+        # (This would require actual schema versioning implementation)
+        base_fields = {"system": v2_request["system"], "prompt": v2_request["prompt"]}
+        request = TextCompletionRequest(**base_fields)
+        assert request.system == "You are helpful."
+        assert request.prompt == "Test prompt"
+
+    def test_required_field_stability_contract(self):
+        """Test that required fields remain stable across versions"""
+        # These fields should never become optional or be removed
+        required_fields = {
+            "TextCompletionRequest": ["system", "prompt"],
+            "TextCompletionResponse": ["error", "response", "model"],
+            "DocumentRagQuery": ["query", "user", "collection"],
+            "DocumentRagResponse": ["error", "response"],
+            "AgentRequest": ["question", "history"],
+            "AgentResponse": ["error"],
+        }
+
+        # Verify required fields are present in schema definitions
+        for schema_name, fields in required_fields.items():
+            # This would be implemented with actual schema introspection
+            # For now, we verify by attempting to create instances
+            assert len(fields) > 0  # Ensure we have defined required fields
+
+
+@pytest.mark.contract
+class TestSerializationContracts:
+    """Contract tests for message serialization/deserialization"""
+
+    def test_all_schemas_serialization_contract(self, schema_registry, sample_message_data):
+        """Test serialization contract for all schemas"""
+        # Test each schema in the registry
+        for schema_name, schema_class in schema_registry.items():
+            if schema_name in sample_message_data:
+                # Skip Triple schema as it requires special handling with Value objects
+                if schema_name == "Triple":
+                    continue
+                    
+                # Act & Assert
+                data = sample_message_data[schema_name]
+                assert serialize_deserialize_test(schema_class, data), f"Serialization failed for {schema_name}"
+    
+    def test_triple_serialization_contract(self, sample_message_data):
+        """Test Triple schema serialization contract with Value objects"""
+        # Arrange
+        triple_data = sample_message_data["Triple"]
+        
+        # Act
+        triple = Triple(
+            s=triple_data["s"],
+            p=triple_data["p"], 
+            o=triple_data["o"]
+        )
+        
+        # Assert - Test that Value objects are properly constructed and accessible
+        assert triple.s.value == "http://example.com/subject"
+        assert triple.p.value == "http://example.com/predicate"
+        assert triple.o.value == "Object value"
+        assert isinstance(triple.s, Value)
+        assert isinstance(triple.p, Value)
+        assert isinstance(triple.o, Value)
+
+    def test_nested_schema_serialization_contract(self, sample_message_data):
+        """Test serialization of nested schemas"""
+        # Test Triples (contains Metadata and Triple objects)
+        metadata = Metadata(**sample_message_data["Metadata"])
+        triple = Triple(**sample_message_data["Triple"])
+        
+        triples = Triples(metadata=metadata, triples=[triple])
+        
+        # Verify nested objects maintain their contracts
+        assert triples.metadata.id == "test-doc-123"
+        assert triples.triples[0].s.value == "http://example.com/subject"
+
+    def test_array_field_serialization_contract(self):
+        """Test serialization of array fields"""
+        # Test AgentRequest with history array
+        steps = [
+            AgentStep(
+                thought=f"Step {i}",
+                action=f"action_{i}",
+                arguments={f"param_{i}": f"value_{i}"},
+                observation=f"Observation {i}"
+            )
+            for i in range(3)
+        ]
+        
+        request = AgentRequest(
+            question="Test with array",
+            plan="Test plan",
+            state="Test state",
+            history=steps
+        )
+        
+        # Verify array serialization maintains order and content
+        assert len(request.history) == 3
+        assert request.history[0].thought == "Step 0"
+        assert request.history[2].action == "action_2"
+
+    def test_optional_field_serialization_contract(self):
+        """Test serialization contract for optional fields"""
+        # Test with minimal required fields
+        minimal_response = TextCompletionResponse(
+            error=None,
+            response="Test",
+            in_token=None,  # Optional field
+            out_token=None,  # Optional field
+            model="test-model"
+        )
+        
+        assert minimal_response.response == "Test"
+        assert minimal_response.in_token is None
+        assert minimal_response.out_token is None

tests/contract/test_objects_cassandra_contracts.py

@@ -0,0 +1,306 @@
+"""
+Contract tests for Cassandra Object Storage
+
+These tests verify the message contracts and schema compatibility
+for the objects storage processor.
+"""
+
+import pytest
+import json
+from pulsar.schema import AvroSchema
+
+from trustgraph.schema import ExtractedObject, Metadata, RowSchema, Field
+from trustgraph.storage.objects.cassandra.write import Processor
+
+
+@pytest.mark.contract
+class TestObjectsCassandraContracts:
+    """Contract tests for Cassandra object storage messages"""
+
+    def test_extracted_object_input_contract(self):
+        """Test that ExtractedObject schema matches expected input format"""
+        # Create test object with all required fields
+        test_metadata = Metadata(
+            id="test-doc-001",
+            user="test_user",
+            collection="test_collection",
+            metadata=[]
+        )
+        
+        test_object = ExtractedObject(
+            metadata=test_metadata,
+            schema_name="customer_records",
+            values={
+                "customer_id": "CUST123",
+                "name": "Test Customer",
+                "email": "test@example.com"
+            },
+            confidence=0.95,
+            source_span="Customer data from document..."
+        )
+        
+        # Verify all required fields are present
+        assert hasattr(test_object, 'metadata')
+        assert hasattr(test_object, 'schema_name')
+        assert hasattr(test_object, 'values')
+        assert hasattr(test_object, 'confidence')
+        assert hasattr(test_object, 'source_span')
+        
+        # Verify metadata structure
+        assert hasattr(test_object.metadata, 'id')
+        assert hasattr(test_object.metadata, 'user')
+        assert hasattr(test_object.metadata, 'collection')
+        assert hasattr(test_object.metadata, 'metadata')
+        
+        # Verify types
+        assert isinstance(test_object.schema_name, str)
+        assert isinstance(test_object.values, dict)
+        assert isinstance(test_object.confidence, float)
+        assert isinstance(test_object.source_span, str)
+
+    def test_row_schema_structure_contract(self):
+        """Test RowSchema structure used for table definitions"""
+        # Create test schema
+        test_fields = [
+            Field(
+                name="id",
+                type="string",
+                size=50,
+                primary=True,
+                description="Primary key",
+                required=True,
+                enum_values=[],
+                indexed=False
+            ),
+            Field(
+                name="status",
+                type="string",
+                size=20,
+                primary=False,
+                description="Status field",
+                required=False,
+                enum_values=["active", "inactive", "pending"],
+                indexed=True
+            )
+        ]
+        
+        test_schema = RowSchema(
+            name="test_table",
+            description="Test table schema",
+            fields=test_fields
+        )
+        
+        # Verify schema structure
+        assert hasattr(test_schema, 'name')
+        assert hasattr(test_schema, 'description')
+        assert hasattr(test_schema, 'fields')
+        assert isinstance(test_schema.fields, list)
+        
+        # Verify field structure
+        for field in test_schema.fields:
+            assert hasattr(field, 'name')
+            assert hasattr(field, 'type')
+            assert hasattr(field, 'size')
+            assert hasattr(field, 'primary')
+            assert hasattr(field, 'description')
+            assert hasattr(field, 'required')
+            assert hasattr(field, 'enum_values')
+            assert hasattr(field, 'indexed')
+
+    def test_schema_config_format_contract(self):
+        """Test the expected configuration format for schemas"""
+        # Define expected config structure
+        config_format = {
+            "schema": {
+                "table_name": json.dumps({
+                    "name": "table_name",
+                    "description": "Table description",
+                    "fields": [
+                        {
+                            "name": "field_name",
+                            "type": "string",
+                            "size": 0,
+                            "primary_key": True,
+                            "description": "Field description",
+                            "required": True,
+                            "enum": [],
+                            "indexed": False
+                        }
+                    ]
+                })
+            }
+        }
+        
+        # Verify config can be parsed
+        schema_json = json.loads(config_format["schema"]["table_name"])
+        assert "name" in schema_json
+        assert "fields" in schema_json
+        assert isinstance(schema_json["fields"], list)
+        
+        # Verify field format
+        field = schema_json["fields"][0]
+        required_field_keys = {"name", "type"}
+        optional_field_keys = {"size", "primary_key", "description", "required", "enum", "indexed"}
+        
+        assert required_field_keys.issubset(field.keys())
+        assert set(field.keys()).issubset(required_field_keys | optional_field_keys)
+
+    def test_cassandra_type_mapping_contract(self):
+        """Test that all supported field types have Cassandra mappings"""
+        processor = Processor.__new__(Processor)
+        
+        # All field types that should be supported
+        supported_types = [
+            ("string", "text"),
+            ("integer", "int"),  # or bigint based on size
+            ("float", "float"),  # or double based on size
+            ("boolean", "boolean"),
+            ("timestamp", "timestamp"),
+            ("date", "date"),
+            ("time", "time"),
+            ("uuid", "uuid")
+        ]
+        
+        for field_type, expected_cassandra_type in supported_types:
+            cassandra_type = processor.get_cassandra_type(field_type)
+            # For integer and float, the exact type depends on size
+            if field_type in ["integer", "float"]:
+                assert cassandra_type in ["int", "bigint", "float", "double"]
+            else:
+                assert cassandra_type == expected_cassandra_type
+
+    def test_value_conversion_contract(self):
+        """Test value conversion for all supported types"""
+        processor = Processor.__new__(Processor)
+        
+        # Test conversions maintain data integrity
+        test_cases = [
+            # (input_value, field_type, expected_output, expected_type)
+            ("123", "integer", 123, int),
+            ("123.45", "float", 123.45, float),
+            ("true", "boolean", True, bool),
+            ("false", "boolean", False, bool),
+            ("test string", "string", "test string", str),
+            (None, "string", None, type(None)),
+        ]
+        
+        for input_val, field_type, expected_val, expected_type in test_cases:
+            result = processor.convert_value(input_val, field_type)
+            assert result == expected_val
+            assert isinstance(result, expected_type) or result is None
+
+    def test_extracted_object_serialization_contract(self):
+        """Test that ExtractedObject can be serialized/deserialized correctly"""
+        # Create test object
+        original = ExtractedObject(
+            metadata=Metadata(
+                id="serial-001",
+                user="test_user",
+                collection="test_coll",
+                metadata=[]
+            ),
+            schema_name="test_schema",
+            values={"field1": "value1", "field2": "123"},
+            confidence=0.85,
+            source_span="Test span"
+        )
+        
+        # Test serialization using schema
+        schema = AvroSchema(ExtractedObject)
+        
+        # Encode and decode
+        encoded = schema.encode(original)
+        decoded = schema.decode(encoded)
+        
+        # Verify round-trip
+        assert decoded.metadata.id == original.metadata.id
+        assert decoded.metadata.user == original.metadata.user
+        assert decoded.metadata.collection == original.metadata.collection
+        assert decoded.schema_name == original.schema_name
+        assert decoded.values == original.values
+        assert decoded.confidence == original.confidence
+        assert decoded.source_span == original.source_span
+
+    def test_cassandra_table_naming_contract(self):
+        """Test Cassandra naming conventions and constraints"""
+        processor = Processor.__new__(Processor)
+        
+        # Test table naming (always gets o_ prefix)
+        table_test_names = [
+            ("simple_name", "o_simple_name"),
+            ("Name-With-Dashes", "o_name_with_dashes"),
+            ("name.with.dots", "o_name_with_dots"),
+            ("123_numbers", "o_123_numbers"),
+            ("special!@#chars", "o_special___chars"),  # 3 special chars become 3 underscores
+            ("UPPERCASE", "o_uppercase"),
+            ("CamelCase", "o_camelcase"),
+            ("", "o_"),  # Edge case - empty string becomes o_
+        ]
+        
+        for input_name, expected_name in table_test_names:
+            result = processor.sanitize_table(input_name)
+            assert result == expected_name
+            # Verify result is valid Cassandra identifier (starts with letter)
+            assert result.startswith('o_')
+            assert result.replace('o_', '').replace('_', '').isalnum() or result == 'o_'
+        
+        # Test regular name sanitization (only adds o_ prefix if starts with number)
+        name_test_cases = [
+            ("simple_name", "simple_name"),
+            ("Name-With-Dashes", "name_with_dashes"),
+            ("name.with.dots", "name_with_dots"),
+            ("123_numbers", "o_123_numbers"),  # Only this gets o_ prefix
+            ("special!@#chars", "special___chars"),  # 3 special chars become 3 underscores
+            ("UPPERCASE", "uppercase"),
+            ("CamelCase", "camelcase"),
+        ]
+        
+        for input_name, expected_name in name_test_cases:
+            result = processor.sanitize_name(input_name)
+            assert result == expected_name
+
+    def test_primary_key_structure_contract(self):
+        """Test that primary key structure follows Cassandra best practices"""
+        # Verify partition key always includes collection
+        processor = Processor.__new__(Processor)
+        processor.schemas = {}
+        processor.known_keyspaces = set()
+        processor.known_tables = {}
+        processor.session = None
+        
+        # Test schema with primary key
+        schema_with_pk = RowSchema(
+            name="test",
+            fields=[
+                Field(name="id", type="string", primary=True),
+                Field(name="data", type="string")
+            ]
+        )
+        
+        # The primary key should be ((collection, id))
+        # This is verified in the implementation where collection
+        # is always first in the partition key
+
+    def test_metadata_field_usage_contract(self):
+        """Test that metadata fields are used correctly in storage"""
+        # Create test object
+        test_obj = ExtractedObject(
+            metadata=Metadata(
+                id="meta-001",
+                user="user123",  # -> keyspace
+                collection="coll456",  # -> partition key
+                metadata=[{"key": "value"}]
+            ),
+            schema_name="table789",  # -> table name
+            values={"field": "value"},
+            confidence=0.9,
+            source_span="Source"
+        )
+        
+        # Verify mapping contract:
+        # - metadata.user -> Cassandra keyspace
+        # - schema_name -> Cassandra table
+        # - metadata.collection -> Part of primary key
+        assert test_obj.metadata.user  # Required for keyspace
+        assert test_obj.schema_name  # Required for table
+        assert test_obj.metadata.collection  # Required for partition key

tests/contract/test_structured_data_contracts.py

@@ -0,0 +1,308 @@
+"""
+Contract tests for Structured Data Pulsar Message Schemas
+
+These tests verify the contracts for all structured data Pulsar message schemas,
+ensuring schema compatibility, serialization contracts, and service interface stability.
+Following the TEST_STRATEGY.md approach for contract testing.
+"""
+
+import pytest
+import json
+from typing import Dict, Any
+
+from trustgraph.schema import (
+    StructuredDataSubmission, ExtractedObject,
+    NLPToStructuredQueryRequest, NLPToStructuredQueryResponse,
+    StructuredQueryRequest, StructuredQueryResponse,
+    StructuredObjectEmbedding, Field, RowSchema,
+    Metadata, Error, Value
+)
+from .conftest import serialize_deserialize_test
+
+
+@pytest.mark.contract
+class TestStructuredDataSchemaContracts:
+    """Contract tests for structured data schemas"""
+
+    def test_field_schema_contract(self):
+        """Test enhanced Field schema contract"""
+        # Arrange & Act - create Field instance directly
+        field = Field(
+            name="customer_id",
+            type="string",
+            size=0,
+            primary=True,
+            description="Unique customer identifier",
+            required=True,
+            enum_values=[],
+            indexed=True
+        )
+
+        # Assert - test field properties
+        assert field.name == "customer_id"
+        assert field.type == "string"
+        assert field.primary is True
+        assert field.indexed is True
+        assert isinstance(field.enum_values, list)
+        assert len(field.enum_values) == 0
+        
+        # Test with enum values
+        field_with_enum = Field(
+            name="status",
+            type="string",
+            size=0,
+            primary=False,
+            description="Status field",
+            required=False,
+            enum_values=["active", "inactive"],
+            indexed=True
+        )
+        
+        assert len(field_with_enum.enum_values) == 2
+        assert "active" in field_with_enum.enum_values
+
+    def test_row_schema_contract(self):
+        """Test RowSchema contract"""
+        # Arrange & Act
+        field = Field(
+            name="email",
+            type="string",
+            size=255,
+            primary=False,
+            description="Customer email",
+            required=True,
+            enum_values=[],
+            indexed=True
+        )
+        
+        schema = RowSchema(
+            name="customers",
+            description="Customer records schema",
+            fields=[field]
+        )
+
+        # Assert
+        assert schema.name == "customers"
+        assert schema.description == "Customer records schema"
+        assert len(schema.fields) == 1
+        assert schema.fields[0].name == "email"
+        assert schema.fields[0].indexed is True
+
+    def test_structured_data_submission_contract(self):
+        """Test StructuredDataSubmission schema contract"""
+        # Arrange
+        metadata = Metadata(
+            id="structured-data-001",
+            user="test_user",
+            collection="test_collection",
+            metadata=[]
+        )
+        
+        # Act
+        submission = StructuredDataSubmission(
+            metadata=metadata,
+            format="csv",
+            schema_name="customer_records",
+            data=b"id,name,email\n1,John,john@example.com",
+            options={"delimiter": ",", "header": "true"}
+        )
+
+        # Assert
+        assert submission.format == "csv"
+        assert submission.schema_name == "customer_records"
+        assert submission.options["delimiter"] == ","
+        assert submission.metadata.id == "structured-data-001"
+        assert len(submission.data) > 0
+
+    def test_extracted_object_contract(self):
+        """Test ExtractedObject schema contract"""
+        # Arrange
+        metadata = Metadata(
+            id="extracted-obj-001",
+            user="test_user",
+            collection="test_collection",
+            metadata=[]
+        )
+        
+        # Act
+        obj = ExtractedObject(
+            metadata=metadata,
+            schema_name="customer_records",
+            values={"id": "123", "name": "John Doe", "email": "john@example.com"},
+            confidence=0.95,
+            source_span="John Doe (john@example.com) customer ID 123"
+        )
+
+        # Assert
+        assert obj.schema_name == "customer_records"
+        assert obj.values["name"] == "John Doe"
+        assert obj.confidence == 0.95
+        assert len(obj.source_span) > 0
+        assert obj.metadata.id == "extracted-obj-001"
+
+
+@pytest.mark.contract
+class TestStructuredQueryServiceContracts:
+    """Contract tests for structured query services"""
+
+    def test_nlp_to_structured_query_request_contract(self):
+        """Test NLPToStructuredQueryRequest schema contract"""
+        # Act
+        request = NLPToStructuredQueryRequest(
+            natural_language_query="Show me all customers who registered last month",
+            max_results=100,
+            context_hints={"time_range": "last_month", "entity_type": "customer"}
+        )
+
+        # Assert
+        assert "customers" in request.natural_language_query
+        assert request.max_results == 100
+        assert request.context_hints["time_range"] == "last_month"
+
+    def test_nlp_to_structured_query_response_contract(self):
+        """Test NLPToStructuredQueryResponse schema contract"""
+        # Act
+        response = NLPToStructuredQueryResponse(
+            error=None,
+            graphql_query="query { customers(filter: {registered: {gte: \"2024-01-01\"}}) { id name email } }",
+            variables={"start_date": "2024-01-01"},
+            detected_schemas=["customers"],
+            confidence=0.92
+        )
+
+        # Assert
+        assert response.error is None
+        assert "customers" in response.graphql_query
+        assert response.detected_schemas[0] == "customers"
+        assert response.confidence > 0.9
+
+    def test_structured_query_request_contract(self):
+        """Test StructuredQueryRequest schema contract"""
+        # Act
+        request = StructuredQueryRequest(
+            query="query GetCustomers($limit: Int) { customers(limit: $limit) { id name email } }",
+            variables={"limit": "10"},
+            operation_name="GetCustomers"
+        )
+
+        # Assert
+        assert "customers" in request.query
+        assert request.variables["limit"] == "10"
+        assert request.operation_name == "GetCustomers"
+
+    def test_structured_query_response_contract(self):
+        """Test StructuredQueryResponse schema contract"""
+        # Act
+        response = StructuredQueryResponse(
+            error=None,
+            data='{"customers": [{"id": "1", "name": "John", "email": "john@example.com"}]}',
+            errors=[]
+        )
+
+        # Assert
+        assert response.error is None
+        assert "customers" in response.data
+        assert len(response.errors) == 0
+
+    def test_structured_query_response_with_errors_contract(self):
+        """Test StructuredQueryResponse with GraphQL errors contract"""
+        # Act
+        response = StructuredQueryResponse(
+            error=None,
+            data=None,
+            errors=["Field 'invalid_field' not found in schema 'customers'"]
+        )
+
+        # Assert
+        assert response.data is None
+        assert len(response.errors) == 1
+        assert "invalid_field" in response.errors[0]
+
+
+@pytest.mark.contract
+class TestStructuredEmbeddingsContracts:
+    """Contract tests for structured object embeddings"""
+
+    def test_structured_object_embedding_contract(self):
+        """Test StructuredObjectEmbedding schema contract"""
+        # Arrange
+        metadata = Metadata(
+            id="struct-embed-001",
+            user="test_user",
+            collection="test_collection",
+            metadata=[]
+        )
+        
+        # Act
+        embedding = StructuredObjectEmbedding(
+            metadata=metadata,
+            vectors=[[0.1, 0.2, 0.3], [0.4, 0.5, 0.6]],
+            schema_name="customer_records",
+            object_id="customer_123",
+            field_embeddings={
+                "name": [0.1, 0.2, 0.3],
+                "email": [0.4, 0.5, 0.6]
+            }
+        )
+
+        # Assert
+        assert embedding.schema_name == "customer_records"
+        assert embedding.object_id == "customer_123"
+        assert len(embedding.vectors) == 2
+        assert len(embedding.field_embeddings) == 2
+        assert "name" in embedding.field_embeddings
+
+
+@pytest.mark.contract
+class TestStructuredDataSerializationContracts:
+    """Contract tests for structured data serialization/deserialization"""
+
+    def test_structured_data_submission_serialization(self):
+        """Test StructuredDataSubmission serialization contract"""
+        # Arrange
+        metadata = Metadata(id="test", user="user", collection="col", metadata=[])
+        submission_data = {
+            "metadata": metadata,
+            "format": "json",
+            "schema_name": "test_schema",
+            "data": b'{"test": "data"}',
+            "options": {"encoding": "utf-8"}
+        }
+
+        # Act & Assert
+        assert serialize_deserialize_test(StructuredDataSubmission, submission_data)
+
+    def test_extracted_object_serialization(self):
+        """Test ExtractedObject serialization contract"""
+        # Arrange
+        metadata = Metadata(id="test", user="user", collection="col", metadata=[])
+        object_data = {
+            "metadata": metadata,
+            "schema_name": "test_schema",
+            "values": {"field1": "value1"},
+            "confidence": 0.8,
+            "source_span": "test span"
+        }
+
+        # Act & Assert
+        assert serialize_deserialize_test(ExtractedObject, object_data)
+
+    def test_nlp_query_serialization(self):
+        """Test NLP query request/response serialization contract"""
+        # Test request
+        request_data = {
+            "natural_language_query": "test query",
+            "max_results": 10,
+            "context_hints": {}
+        }
+        assert serialize_deserialize_test(NLPToStructuredQueryRequest, request_data)
+
+        # Test response
+        response_data = {
+            "error": None,
+            "graphql_query": "query { test }",
+            "variables": {},
+            "detected_schemas": ["test"],
+            "confidence": 0.9
+        }
+        assert serialize_deserialize_test(NLPToStructuredQueryResponse, response_data)

tests/integration/README.md

@@ -0,0 +1,269 @@
+# Integration Test Pattern for TrustGraph
+
+This directory contains integration tests that verify the coordination between multiple TrustGraph services and components, following the patterns outlined in [TEST_STRATEGY.md](../../TEST_STRATEGY.md).
+
+## Integration Test Approach
+
+Integration tests focus on **service-to-service communication patterns** and **end-to-end message flows** while still using mocks for external infrastructure.
+
+### Key Principles
+
+1. **Test Service Coordination**: Verify that services work together correctly
+2. **Mock External Dependencies**: Use mocks for databases, APIs, and infrastructure
+3. **Real Business Logic**: Exercise actual service logic and data transformations
+4. **Error Propagation**: Test how errors flow through the system
+5. **Configuration Testing**: Verify services respond correctly to different configurations
+
+## Test Structure
+
+### Fixtures (conftest.py)
+
+Common fixtures for integration tests:
+- `mock_pulsar_client`: Mock Pulsar messaging client
+- `mock_flow_context`: Mock flow context for service coordination
+- `integration_config`: Standard configuration for integration tests
+- `sample_documents`: Test document collections
+- `sample_embeddings`: Test embedding vectors
+- `sample_queries`: Test query sets
+
+### Test Patterns
+
+#### 1. End-to-End Flow Testing
+
+```python
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_service_end_to_end_flow(self, service_instance, mock_clients):
+    """Test complete service pipeline from input to output"""
+    # Arrange - Set up realistic test data
+    # Act - Execute the full service workflow
+    # Assert - Verify coordination between all components
+```
+
+#### 2. Error Propagation Testing
+
+```python
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_service_error_handling(self, service_instance, mock_clients):
+    """Test how errors propagate through service coordination"""
+    # Arrange - Set up failure scenarios
+    # Act - Execute service with failing dependency
+    # Assert - Verify proper error handling and cleanup
+```
+
+#### 3. Configuration Testing
+
+```python
+@pytest.mark.integration
+@pytest.mark.asyncio
+async def test_service_configuration_scenarios(self, service_instance):
+    """Test service behavior with different configurations"""
+    # Test multiple configuration scenarios
+    # Verify service adapts correctly to each configuration
+```
+
+## Running Integration Tests
+
+### Run All Integration Tests
+```bash
+pytest tests/integration/ -m integration
+```
+
+### Run Specific Test
+```bash
+pytest tests/integration/test_document_rag_integration.py::TestDocumentRagIntegration::test_document_rag_end_to_end_flow -v
+```
+
+### Run with Coverage (Skip Coverage Requirement)
+```bash
+pytest tests/integration/ -m integration --cov=trustgraph --cov-fail-under=0
+```
+
+### Run Slow Tests
+```bash
+pytest tests/integration/ -m "integration and slow"
+```
+
+### Skip Slow Tests
+```bash
+pytest tests/integration/ -m "integration and not slow"
+```
+
+## Examples: Integration Test Implementations
+
+### 1. Document RAG Integration Test
+
+The `test_document_rag_integration.py` demonstrates the integration test pattern:
+
+### What It Tests
+- **Service Coordination**: Embeddings → Document Retrieval → Prompt Generation
+- **Error Handling**: Failure scenarios for each service dependency
+- **Configuration**: Different document limits, users, and collections
+- **Performance**: Large document set handling
+
+### Key Features
+- **Realistic Data Flow**: Uses actual service logic with mocked dependencies
+- **Multiple Scenarios**: Success, failure, and edge cases
+- **Verbose Logging**: Tests logging functionality
+- **Multi-User Support**: Tests user and collection isolation
+
+### Test Coverage
+- ✅ End-to-end happy path
+- ✅ No documents found scenario
+- ✅ Service failure scenarios (embeddings, documents, prompt)
+- ✅ Configuration variations
+- ✅ Multi-user isolation
+- ✅ Performance testing
+- ✅ Verbose logging
+
+### 2. Text Completion Integration Test
+
+The `test_text_completion_integration.py` demonstrates external API integration testing:
+
+### What It Tests
+- **External API Integration**: OpenAI API connectivity and authentication
+- **Rate Limiting**: Proper handling of API rate limits and retries
+- **Error Handling**: API failures, connection timeouts, and error propagation
+- **Token Tracking**: Accurate input/output token counting and metrics
+- **Configuration**: Different model parameters and settings
+- **Concurrency**: Multiple simultaneous API requests
+
+### Key Features
+- **Realistic Mock Responses**: Uses actual OpenAI API response structures
+- **Authentication Testing**: API key validation and base URL configuration
+- **Error Scenarios**: Rate limits, connection failures, invalid requests
+- **Performance Metrics**: Timing and token usage validation
+- **Model Flexibility**: Tests different GPT models and parameters
+
+### Test Coverage
+- ✅ Successful text completion generation
+- ✅ Multiple model configurations (GPT-3.5, GPT-4, GPT-4-turbo)
+- ✅ Rate limit handling (RateLimitError → TooManyRequests)
+- ✅ API error handling and propagation
+- ✅ Token counting accuracy
+- ✅ Prompt construction and parameter validation
+- ✅ Authentication patterns and API key validation
+- ✅ Concurrent request processing
+- ✅ Response content extraction and validation
+- ✅ Performance timing measurements
+
+### 3. Agent Manager Integration Test
+
+The `test_agent_manager_integration.py` demonstrates complex service coordination testing:
+
+### What It Tests
+- **ReAct Pattern**: Think-Act-Observe cycles with multi-step reasoning
+- **Tool Coordination**: Selection and execution of different tools (knowledge query, text completion, MCP tools)
+- **Conversation State**: Management of conversation history and context
+- **Multi-Service Integration**: Coordination between prompt, graph RAG, and tool services
+- **Error Handling**: Tool failures, unknown tools, and error propagation
+- **Configuration Management**: Dynamic tool loading and configuration
+
+### Key Features
+- **Complex Coordination**: Tests agent reasoning with multiple tool options
+- **Stateful Processing**: Maintains conversation history across interactions
+- **Dynamic Tool Selection**: Tests tool selection based on context and reasoning
+- **Callback Pattern**: Tests think/observe callback mechanisms
+- **JSON Serialization**: Handles complex data structures in prompts
+- **Performance Testing**: Large conversation history handling
+
+### Test Coverage
+- ✅ Basic reasoning cycle with tool selection
+- ✅ Final answer generation (ending ReAct cycle)
+- ✅ Full ReAct cycle with tool execution
+- ✅ Conversation history management
+- ✅ Multiple tool coordination and selection
+- ✅ Tool argument validation and processing
+- ✅ Error handling (unknown tools, execution failures)
+- ✅ Context integration and additional prompting
+- ✅ Empty tool configuration handling
+- ✅ Tool response processing and cleanup
+- ✅ Performance with large conversation history
+- ✅ JSON serialization in complex prompts
+
+### 4. Knowledge Graph Extract → Store Pipeline Integration Test
+
+The `test_kg_extract_store_integration.py` demonstrates multi-stage pipeline testing:
+
+### What It Tests
+- **Text-to-Graph Transformation**: Complete pipeline from text chunks to graph triples
+- **Entity Extraction**: Definition extraction with proper URI generation
+- **Relationship Extraction**: Subject-predicate-object relationship extraction
+- **Graph Database Integration**: Storage coordination with Cassandra knowledge store
+- **Data Validation**: Entity filtering, validation, and consistency checks
+- **Pipeline Coordination**: Multi-stage processing with proper data flow
+
+### Key Features
+- **Multi-Stage Pipeline**: Tests definitions → relationships → storage coordination
+- **Graph Data Structures**: RDF triples, entity contexts, and graph embeddings
+- **URI Generation**: Consistent entity URI creation across pipeline stages
+- **Data Transformation**: Complex text analysis to structured graph data
+- **Batch Processing**: Large document set processing performance
+- **Error Resilience**: Graceful handling of extraction failures
+
+### Test Coverage
+- ✅ Definitions extraction pipeline (text → entities + definitions)
+- ✅ Relationships extraction pipeline (text → subject-predicate-object)
+- ✅ URI generation consistency between processors
+- ✅ Triple generation from definitions and relationships
+- ✅ Knowledge store integration (triples and embeddings storage)
+- ✅ End-to-end pipeline coordination
+- ✅ Error handling in extraction services
+- ✅ Empty and invalid extraction results handling
+- ✅ Entity filtering and validation
+- ✅ Large batch processing performance
+- ✅ Metadata propagation through pipeline stages
+
+## Best Practices
+
+### Test Organization
+- Group related tests in classes
+- Use descriptive test names that explain the scenario
+- Follow the Arrange-Act-Assert pattern
+- Use appropriate pytest markers (`@pytest.mark.integration`, `@pytest.mark.slow`)
+
+### Mock Strategy
+- Mock external services (databases, APIs, message brokers)
+- Use real service logic and data transformations
+- Create realistic mock responses that match actual service behavior
+- Reset mocks between tests to ensure isolation
+
+### Test Data
+- Use realistic test data that reflects actual usage patterns
+- Create reusable fixtures for common test scenarios
+- Test with various data sizes and edge cases
+- Include both success and failure scenarios
+
+### Error Testing
+- Test each dependency failure scenario
+- Verify proper error propagation and cleanup
+- Test timeout and retry mechanisms
+- Validate error response formats
+
+### Performance Testing
+- Mark performance tests with `@pytest.mark.slow`
+- Test with realistic data volumes
+- Set reasonable performance expectations
+- Monitor resource usage during tests
+
+## Adding New Integration Tests
+
+1. **Identify Service Dependencies**: Map out which services your target service coordinates with
+2. **Create Mock Fixtures**: Set up mocks for each dependency in conftest.py
+3. **Design Test Scenarios**: Plan happy path, error cases, and edge conditions
+4. **Implement Tests**: Follow the established patterns in this directory
+5. **Add Documentation**: Update this README with your new test patterns
+
+## Test Markers
+
+- `@pytest.mark.integration`: Marks tests as integration tests
+- `@pytest.mark.slow`: Marks tests that take longer to run
+- `@pytest.mark.asyncio`: Required for async test functions
+
+## Future Enhancements
+
+- Add tests with real test containers for database integration
+- Implement contract testing for service interfaces
+- Add performance benchmarking for critical paths
+- Create integration test templates for common service patterns

tests/integration/cassandra_test_helper.py

@@ -0,0 +1,112 @@
+"""
+Helper for managing Cassandra containers in integration tests
+Alternative to testcontainers for Fedora/Podman compatibility
+"""
+
+import subprocess
+import time
+import socket
+from contextlib import contextmanager
+from cassandra.cluster import Cluster
+from cassandra.policies import RetryPolicy
+
+
+class CassandraTestContainer:
+    """Simple Cassandra container manager using Podman"""
+    
+    def __init__(self, image="docker.io/library/cassandra:4.1", port=9042):
+        self.image = image
+        self.port = port
+        self.container_name = f"test-cassandra-{int(time.time())}"
+        self.container_id = None
+    
+    def start(self):
+        """Start Cassandra container"""
+        # Remove any existing container with same name
+        subprocess.run([
+            "podman", "rm", "-f", self.container_name
+        ], capture_output=True)
+        
+        # Start new container with faster startup options
+        result = subprocess.run([
+            "podman", "run", "-d", 
+            "--name", self.container_name,
+            "-p", f"{self.port}:9042",
+            "-e", "JVM_OPTS=-Dcassandra.skip_wait_for_gossip_to_settle=0",
+            self.image
+        ], capture_output=True, text=True)
+        
+        if result.returncode != 0:
+            raise RuntimeError(f"Failed to start container: {result.stderr}")
+        
+        self.container_id = result.stdout.strip()
+        
+        # Wait for Cassandra to be ready
+        self._wait_for_ready()
+        return self
+    
+    def stop(self):
+        """Stop and remove container"""
+        import time
+        if self.container_name:
+            # Small delay before stopping to ensure connections are closed
+            time.sleep(0.5)
+            subprocess.run([
+                "podman", "rm", "-f", self.container_name
+            ], capture_output=True)
+    
+    def get_connection_host_port(self):
+        """Get host and port for connection"""
+        return "localhost", self.port
+    
+    def _wait_for_ready(self, timeout=120):
+        """Wait for Cassandra to be ready for CQL queries"""
+        start_time = time.time()
+        
+        print(f"Waiting for Cassandra to be ready on port {self.port}...")
+        
+        while time.time() - start_time < timeout:
+            try:
+                # First check if port is open
+                sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+                sock.settimeout(1)
+                result = sock.connect_ex(("localhost", self.port))
+                sock.close()
+                
+                if result == 0:
+                    # Port is open, now try to connect with Cassandra driver
+                    try:
+                        cluster = Cluster(['localhost'], port=self.port)
+                        cluster.connect_timeout = 5
+                        session = cluster.connect()
+                        
+                        # Try a simple query to verify Cassandra is ready
+                        session.execute("SELECT release_version FROM system.local")
+                        session.shutdown()
+                        cluster.shutdown()
+                        
+                        print("Cassandra is ready!")
+                        return
+                        
+                    except Exception as e:
+                        print(f"Cassandra not ready yet: {e}")
+                        pass
+                        
+            except Exception as e:
+                print(f"Connection check failed: {e}")
+                pass
+            
+            time.sleep(3)
+        
+        raise RuntimeError(f"Cassandra not ready after {timeout} seconds")
+
+
+@contextmanager
+def cassandra_container(image="docker.io/library/cassandra:4.1", port=9042):
+    """Context manager for Cassandra container"""
+    container = CassandraTestContainer(image, port)
+    try:
+        container.start()
+        yield container
+    finally:
+        container.stop()

tests/integration/conftest.py

@@ -0,0 +1,404 @@
+"""
+Shared fixtures and configuration for integration tests
+
+This file provides common fixtures and test configuration for integration tests.
+Following the TEST_STRATEGY.md patterns for integration testing.
+"""
+
+import pytest
+from unittest.mock import AsyncMock, MagicMock
+
+
+@pytest.fixture
+def mock_pulsar_client():
+    """Mock Pulsar client for integration tests"""
+    client = MagicMock()
+    client.create_producer.return_value = AsyncMock()
+    client.subscribe.return_value = AsyncMock()
+    return client
+
+
+@pytest.fixture
+def mock_flow_context():
+    """Mock flow context for testing service coordination"""
+    context = MagicMock()
+    
+    # Mock flow producers/consumers
+    context.return_value.send = AsyncMock()
+    context.return_value.receive = AsyncMock()
+    
+    return context
+
+
+@pytest.fixture
+def integration_config():
+    """Common configuration for integration tests"""
+    return {
+        "pulsar_host": "localhost",
+        "pulsar_port": 6650,
+        "test_timeout": 30.0,
+        "max_retries": 3,
+        "doc_limit": 10,
+        "embedding_dim": 5,
+    }
+
+
+@pytest.fixture
+def sample_documents():
+    """Sample document collection for testing"""
+    return [
+        {
+            "id": "doc1",
+            "content": "Machine learning is a subset of artificial intelligence that focuses on algorithms that learn from data.",
+            "collection": "ml_knowledge",
+            "user": "test_user"
+        },
+        {
+            "id": "doc2", 
+            "content": "Deep learning uses neural networks with multiple layers to model complex patterns in data.",
+            "collection": "ml_knowledge",
+            "user": "test_user"
+        },
+        {
+            "id": "doc3",
+            "content": "Supervised learning algorithms learn from labeled training data to make predictions on new data.",
+            "collection": "ml_knowledge", 
+            "user": "test_user"
+        }
+    ]
+
+
+@pytest.fixture
+def sample_embeddings():
+    """Sample embedding vectors for testing"""
+    return [
+        [0.1, 0.2, 0.3, 0.4, 0.5],
+        [0.6, 0.7, 0.8, 0.9, 1.0],
+        [0.2, 0.3, 0.4, 0.5, 0.6],
+        [0.7, 0.8, 0.9, 1.0, 0.1],
+        [0.3, 0.4, 0.5, 0.6, 0.7]
+    ]
+
+
+@pytest.fixture
+def sample_queries():
+    """Sample queries for testing"""
+    return [
+        "What is machine learning?",
+        "How does deep learning work?",
+        "Explain supervised learning",
+        "What are neural networks?",
+        "How do algorithms learn from data?"
+    ]
+
+
+@pytest.fixture
+def sample_text_completion_requests():
+    """Sample text completion requests for testing"""
+    return [
+        {
+            "system": "You are a helpful assistant.",
+            "prompt": "What is artificial intelligence?",
+            "expected_keywords": ["artificial intelligence", "AI", "machine learning"]
+        },
+        {
+            "system": "You are a technical expert.",
+            "prompt": "Explain neural networks",
+            "expected_keywords": ["neural networks", "neurons", "layers"]
+        },
+        {
+            "system": "You are a teacher.",
+            "prompt": "What is supervised learning?",
+            "expected_keywords": ["supervised learning", "training", "labels"]
+        }
+    ]
+
+
+@pytest.fixture
+def mock_openai_response():
+    """Mock OpenAI API response structure"""
+    return {
+        "id": "chatcmpl-test123",
+        "object": "chat.completion",
+        "created": 1234567890,
+        "model": "gpt-3.5-turbo",
+        "choices": [
+            {
+                "index": 0,
+                "message": {
+                    "role": "assistant",
+                    "content": "This is a test response from the AI model."
+                },
+                "finish_reason": "stop"
+            }
+        ],
+        "usage": {
+            "prompt_tokens": 50,
+            "completion_tokens": 100,
+            "total_tokens": 150
+        }
+    }
+
+
+@pytest.fixture
+def text_completion_configs():
+    """Various text completion configurations for testing"""
+    return [
+        {
+            "model": "gpt-3.5-turbo",
+            "temperature": 0.0,
+            "max_output": 1024,
+            "description": "Conservative settings"
+        },
+        {
+            "model": "gpt-4",
+            "temperature": 0.7,
+            "max_output": 2048,
+            "description": "Balanced settings"
+        },
+        {
+            "model": "gpt-4-turbo",
+            "temperature": 1.0,
+            "max_output": 4096,
+            "description": "Creative settings"
+        }
+    ]
+
+
+@pytest.fixture
+def sample_agent_tools():
+    """Sample agent tools configuration for testing"""
+    return {
+        "knowledge_query": {
+            "name": "knowledge_query",
+            "description": "Query the knowledge graph for information",
+            "type": "knowledge-query",
+            "arguments": [
+                {
+                    "name": "question",
+                    "type": "string",
+                    "description": "The question to ask the knowledge graph"
+                }
+            ]
+        },
+        "text_completion": {
+            "name": "text_completion", 
+            "description": "Generate text completion using LLM",
+            "type": "text-completion",
+            "arguments": [
+                {
+                    "name": "question",
+                    "type": "string",
+                    "description": "The question to ask the LLM"
+                }
+            ]
+        },
+        "web_search": {
+            "name": "web_search",
+            "description": "Search the web for information",
+            "type": "mcp-tool",
+            "arguments": [
+                {
+                    "name": "query",
+                    "type": "string",
+                    "description": "The search query"
+                }
+            ]
+        }
+    }
+
+
+@pytest.fixture
+def sample_agent_requests():
+    """Sample agent requests for testing"""
+    return [
+        {
+            "question": "What is machine learning?",
+            "plan": "",
+            "state": "",
+            "history": [],
+            "expected_tool": "knowledge_query"
+        },
+        {
+            "question": "Can you explain neural networks in simple terms?",
+            "plan": "",
+            "state": "",
+            "history": [],
+            "expected_tool": "text_completion"
+        },
+        {
+            "question": "Search for the latest AI research papers",
+            "plan": "",
+            "state": "",
+            "history": [],
+            "expected_tool": "web_search"
+        }
+    ]
+
+
+@pytest.fixture
+def sample_agent_responses():
+    """Sample agent responses for testing"""
+    return [
+        {
+            "thought": "I need to search for information about machine learning",
+            "action": "knowledge_query",
+            "arguments": {"question": "What is machine learning?"}
+        },
+        {
+            "thought": "I can provide a direct answer about neural networks",
+            "final-answer": "Neural networks are computing systems inspired by biological neural networks."
+        },
+        {
+            "thought": "I should search the web for recent research",
+            "action": "web_search",
+            "arguments": {"query": "latest AI research papers 2024"}
+        }
+    ]
+
+
+@pytest.fixture
+def sample_conversation_history():
+    """Sample conversation history for testing"""
+    return [
+        {
+            "thought": "I need to search for basic information first",
+            "action": "knowledge_query",
+            "arguments": {"question": "What is artificial intelligence?"},
+            "observation": "AI is the simulation of human intelligence in machines."
+        },
+        {
+            "thought": "Now I can provide more specific information",
+            "action": "text_completion",
+            "arguments": {"question": "Explain machine learning within AI"},
+            "observation": "Machine learning is a subset of AI that enables computers to learn from data."
+        }
+    ]
+
+
+@pytest.fixture
+def sample_kg_extraction_data():
+    """Sample knowledge graph extraction data for testing"""
+    return {
+        "text_chunks": [
+            "Machine Learning is a subset of Artificial Intelligence that enables computers to learn from data.",
+            "Neural Networks are computing systems inspired by biological neural networks.",
+            "Deep Learning uses neural networks with multiple layers to model complex patterns."
+        ],
+        "expected_entities": [
+            "Machine Learning",
+            "Artificial Intelligence", 
+            "Neural Networks",
+            "Deep Learning"
+        ],
+        "expected_relationships": [
+            {
+                "subject": "Machine Learning",
+                "predicate": "is_subset_of",
+                "object": "Artificial Intelligence"
+            },
+            {
+                "subject": "Deep Learning",
+                "predicate": "uses",
+                "object": "Neural Networks"
+            }
+        ]
+    }
+
+
+@pytest.fixture
+def sample_kg_definitions():
+    """Sample knowledge graph definitions for testing"""
+    return [
+        {
+            "entity": "Machine Learning",
+            "definition": "A subset of artificial intelligence that enables computers to learn from data without explicit programming."
+        },
+        {
+            "entity": "Artificial Intelligence",
+            "definition": "The simulation of human intelligence in machines that are programmed to think and act like humans."
+        },
+        {
+            "entity": "Neural Networks",
+            "definition": "Computing systems inspired by biological neural networks that process information using interconnected nodes."
+        },
+        {
+            "entity": "Deep Learning",
+            "definition": "A subset of machine learning that uses neural networks with multiple layers to model complex patterns in data."
+        }
+    ]
+
+
+@pytest.fixture
+def sample_kg_relationships():
+    """Sample knowledge graph relationships for testing"""
+    return [
+        {
+            "subject": "Machine Learning",
+            "predicate": "is_subset_of",
+            "object": "Artificial Intelligence",
+            "object-entity": True
+        },
+        {
+            "subject": "Deep Learning",
+            "predicate": "is_subset_of",
+            "object": "Machine Learning",
+            "object-entity": True
+        },
+        {
+            "subject": "Neural Networks",
+            "predicate": "is_used_in",
+            "object": "Deep Learning",
+            "object-entity": True
+        },
+        {
+            "subject": "Machine Learning",
+            "predicate": "processes",
+            "object": "data patterns",
+            "object-entity": False
+        }
+    ]
+
+
+@pytest.fixture
+def sample_kg_triples():
+    """Sample knowledge graph triples for testing"""
+    return [
+        {
+            "subject": "http://trustgraph.ai/e/machine-learning",
+            "predicate": "http://www.w3.org/2000/01/rdf-schema#label",
+            "object": "Machine Learning"
+        },
+        {
+            "subject": "http://trustgraph.ai/e/machine-learning",
+            "predicate": "http://trustgraph.ai/definition",
+            "object": "A subset of artificial intelligence that enables computers to learn from data."
+        },
+        {
+            "subject": "http://trustgraph.ai/e/machine-learning",
+            "predicate": "http://trustgraph.ai/e/is_subset_of",
+            "object": "http://trustgraph.ai/e/artificial-intelligence"
+        }
+    ]
+
+
+# Test markers for integration tests
+pytestmark = pytest.mark.integration
+
+
+def pytest_sessionfinish(session, exitstatus):
+    """
+    Called after whole test run finished, right before returning the exit status.
+    
+    This hook is used to ensure Cassandra driver threads have time to shut down
+    properly before pytest exits, preventing "cannot schedule new futures after
+    shutdown" errors.
+    """
+    import time
+    import gc
+    
+    # Force garbage collection to clean up any remaining objects
+    gc.collect()
+    
+    # Give Cassandra driver threads more time to clean up
+    time.sleep(2)

tests/integration/test_agent_kg_extraction_integration.py

@@ -0,0 +1,481 @@
+"""
+Integration tests for Agent-based Knowledge Graph Extraction
+
+These tests verify the end-to-end functionality of the agent-driven knowledge graph
+extraction pipeline, testing the integration between agent communication, prompt
+rendering, JSON response processing, and knowledge graph generation.
+Following the TEST_STRATEGY.md approach for integration testing.
+"""
+
+import pytest
+import json
+from unittest.mock import AsyncMock, MagicMock, patch
+
+from trustgraph.extract.kg.agent.extract import Processor as AgentKgExtractor
+from trustgraph.schema import Chunk, Triple, Triples, Metadata, Value, Error
+from trustgraph.schema import EntityContext, EntityContexts, AgentRequest, AgentResponse
+from trustgraph.rdf import TRUSTGRAPH_ENTITIES, DEFINITION, RDF_LABEL, SUBJECT_OF
+from trustgraph.template.prompt_manager import PromptManager
+
+
+@pytest.mark.integration
+class TestAgentKgExtractionIntegration:
+    """Integration tests for Agent-based Knowledge Graph Extraction"""
+
+    @pytest.fixture
+    def mock_flow_context(self):
+        """Mock flow context for agent communication and output publishing"""
+        context = MagicMock()
+        
+        # Mock agent client
+        agent_client = AsyncMock()
+        
+        # Mock successful agent response
+        def mock_agent_response(recipient, question):
+            # Simulate agent processing and return structured response
+            mock_response = MagicMock()
+            mock_response.error = None
+            mock_response.answer = '''```json
+{
+    "definitions": [
+        {
+            "entity": "Machine Learning",
+            "definition": "A subset of artificial intelligence that enables computers to learn from data without explicit programming."
+        },
+        {
+            "entity": "Neural Networks", 
+            "definition": "Computing systems inspired by biological neural networks that process information."
+        }
+    ],
+    "relationships": [
+        {
+            "subject": "Machine Learning",
+            "predicate": "is_subset_of", 
+            "object": "Artificial Intelligence",
+            "object-entity": true
+        },
+        {
+            "subject": "Neural Networks",
+            "predicate": "used_in",
+            "object": "Machine Learning", 
+            "object-entity": true
+        }
+    ]
+}
+```'''
+            return mock_response.answer
+        
+        agent_client.invoke = mock_agent_response
+        
+        # Mock output publishers
+        triples_publisher = AsyncMock()
+        entity_contexts_publisher = AsyncMock()
+        
+        def context_router(service_name):
+            if service_name == "agent-request":
+                return agent_client
+            elif service_name == "triples":
+                return triples_publisher
+            elif service_name == "entity-contexts":
+                return entity_contexts_publisher
+            else:
+                return AsyncMock()
+        
+        context.side_effect = context_router
+        return context
+
+    @pytest.fixture
+    def sample_chunk(self):
+        """Sample text chunk for knowledge extraction"""
+        text = """
+        Machine Learning is a subset of Artificial Intelligence that enables computers 
+        to learn from data without explicit programming. Neural Networks are computing 
+        systems inspired by biological neural networks that process information. 
+        Neural Networks are commonly used in Machine Learning applications.
+        """
+        
+        return Chunk(
+            chunk=text.encode('utf-8'),
+            metadata=Metadata(
+                id="doc123",
+                metadata=[
+                    Triple(
+                        s=Value(value="doc123", is_uri=True),
+                        p=Value(value="http://example.org/type", is_uri=True),
+                        o=Value(value="document", is_uri=False)
+                    )
+                ]
+            )
+        )
+
+    @pytest.fixture
+    def configured_agent_extractor(self):
+        """Mock agent extractor with loaded configuration for integration testing"""
+        # Create a mock extractor that simulates the real behavior
+        from trustgraph.extract.kg.agent.extract import Processor
+        
+        # Create mock without calling __init__ to avoid FlowProcessor issues
+        extractor = MagicMock()
+        real_extractor = Processor.__new__(Processor)
+        
+        # Copy the methods we want to test
+        extractor.to_uri = real_extractor.to_uri
+        extractor.parse_json = real_extractor.parse_json
+        extractor.process_extraction_data = real_extractor.process_extraction_data
+        extractor.emit_triples = real_extractor.emit_triples
+        extractor.emit_entity_contexts = real_extractor.emit_entity_contexts
+        
+        # Set up the configuration and manager
+        extractor.manager = PromptManager()
+        extractor.template_id = "agent-kg-extract"
+        extractor.config_key = "prompt"
+        
+        # Mock configuration
+        config = {
+            "system": json.dumps("You are a knowledge extraction agent."),
+            "template-index": json.dumps(["agent-kg-extract"]),
+            "template.agent-kg-extract": json.dumps({
+                "prompt": "Extract entities and relationships from: {{ text }}",
+                "response-type": "json"
+            })
+        }
+        
+        # Load configuration
+        extractor.manager.load_config(config)
+        
+        # Mock the on_message method to simulate real behavior
+        async def mock_on_message(msg, consumer, flow):
+            v = msg.value()
+            chunk_text = v.chunk.decode('utf-8')
+            
+            # Render prompt
+            prompt = extractor.manager.render(extractor.template_id, {"text": chunk_text})
+            
+            # Get agent response (the mock returns a string directly)
+            agent_client = flow("agent-request")
+            agent_response = agent_client.invoke(recipient=lambda x: True, question=prompt)
+            
+            # Parse and process
+            extraction_data = extractor.parse_json(agent_response)
+            triples, entity_contexts = extractor.process_extraction_data(extraction_data, v.metadata)
+            
+            # Add metadata triples
+            for t in v.metadata.metadata:
+                triples.append(t)
+            
+            # Emit outputs
+            if triples:
+                await extractor.emit_triples(flow("triples"), v.metadata, triples)
+            if entity_contexts:
+                await extractor.emit_entity_contexts(flow("entity-contexts"), v.metadata, entity_contexts)
+        
+        extractor.on_message = mock_on_message
+        
+        return extractor
+
+    @pytest.mark.asyncio
+    async def test_end_to_end_knowledge_extraction(self, configured_agent_extractor, sample_chunk, mock_flow_context):
+        """Test complete end-to-end knowledge extraction workflow"""
+        # Arrange
+        mock_message = MagicMock()
+        mock_message.value.return_value = sample_chunk
+        mock_consumer = MagicMock()
+
+        # Act
+        await configured_agent_extractor.on_message(mock_message, mock_consumer, mock_flow_context)
+
+        # Assert
+        # Verify agent was called with rendered prompt
+        agent_client = mock_flow_context("agent-request")
+        # Check that the mock function was replaced and called
+        assert hasattr(agent_client, 'invoke')
+
+        # Verify triples were emitted
+        triples_publisher = mock_flow_context("triples")
+        triples_publisher.send.assert_called_once()
+        
+        sent_triples = triples_publisher.send.call_args[0][0]
+        assert isinstance(sent_triples, Triples)
+        assert sent_triples.metadata.id == "doc123"
+        assert len(sent_triples.triples) > 0
+        
+        # Check that we have definition triples
+        definition_triples = [t for t in sent_triples.triples if t.p.value == DEFINITION]
+        assert len(definition_triples) >= 2  # Should have definitions for ML and Neural Networks
+        
+        # Check that we have label triples
+        label_triples = [t for t in sent_triples.triples if t.p.value == RDF_LABEL]
+        assert len(label_triples) >= 2  # Should have labels for entities
+        
+        # Check subject-of relationships
+        subject_of_triples = [t for t in sent_triples.triples if t.p.value == SUBJECT_OF]
+        assert len(subject_of_triples) >= 2  # Entities should be linked to document
+
+        # Verify entity contexts were emitted
+        entity_contexts_publisher = mock_flow_context("entity-contexts")
+        entity_contexts_publisher.send.assert_called_once()
+        
+        sent_contexts = entity_contexts_publisher.send.call_args[0][0]
+        assert isinstance(sent_contexts, EntityContexts)
+        assert len(sent_contexts.entities) >= 2  # Should have contexts for both entities
+        
+        # Verify entity URIs are properly formed
+        entity_uris = [ec.entity.value for ec in sent_contexts.entities]
+        assert f"{TRUSTGRAPH_ENTITIES}Machine%20Learning" in entity_uris
+        assert f"{TRUSTGRAPH_ENTITIES}Neural%20Networks" in entity_uris
+
+    @pytest.mark.asyncio
+    async def test_agent_error_handling(self, configured_agent_extractor, sample_chunk, mock_flow_context):
+        """Test handling of agent errors"""
+        # Arrange - mock agent error response
+        agent_client = mock_flow_context("agent-request")
+        
+        def mock_error_response(recipient, question):
+            # Simulate agent error by raising an exception
+            raise RuntimeError("Agent processing failed")
+        
+        agent_client.invoke = mock_error_response
+        
+        mock_message = MagicMock()
+        mock_message.value.return_value = sample_chunk
+        mock_consumer = MagicMock()
+
+        # Act & Assert
+        with pytest.raises(RuntimeError) as exc_info:
+            await configured_agent_extractor.on_message(mock_message, mock_consumer, mock_flow_context)
+        
+        assert "Agent processing failed" in str(exc_info.value)
+
+    @pytest.mark.asyncio
+    async def test_invalid_json_response_handling(self, configured_agent_extractor, sample_chunk, mock_flow_context):
+        """Test handling of invalid JSON responses from agent"""
+        # Arrange - mock invalid JSON response
+        agent_client = mock_flow_context("agent-request")
+        
+        def mock_invalid_json_response(recipient, question):
+            return "This is not valid JSON at all"
+        
+        agent_client.invoke = mock_invalid_json_response
+        
+        mock_message = MagicMock()
+        mock_message.value.return_value = sample_chunk
+        mock_consumer = MagicMock()
+
+        # Act & Assert
+        with pytest.raises((ValueError, json.JSONDecodeError)):
+            await configured_agent_extractor.on_message(mock_message, mock_consumer, mock_flow_context)
+
+    @pytest.mark.asyncio
+    async def test_empty_extraction_results(self, configured_agent_extractor, sample_chunk, mock_flow_context):
+        """Test handling of empty extraction results"""
+        # Arrange - mock empty extraction response
+        agent_client = mock_flow_context("agent-request")
+        
+        def mock_empty_response(recipient, question):
+            return '{"definitions": [], "relationships": []}'
+        
+        agent_client.invoke = mock_empty_response
+        
+        mock_message = MagicMock()
+        mock_message.value.return_value = sample_chunk
+        mock_consumer = MagicMock()
+
+        # Act
+        await configured_agent_extractor.on_message(mock_message, mock_consumer, mock_flow_context)
+
+        # Assert
+        # Should still emit outputs (even if empty) to maintain flow consistency
+        triples_publisher = mock_flow_context("triples")
+        entity_contexts_publisher = mock_flow_context("entity-contexts")
+        
+        # Triples should include metadata triples at minimum
+        triples_publisher.send.assert_called_once()
+        sent_triples = triples_publisher.send.call_args[0][0]
+        assert isinstance(sent_triples, Triples)
+        
+        # Entity contexts should not be sent if empty
+        entity_contexts_publisher.send.assert_not_called()
+
+    @pytest.mark.asyncio
+    async def test_malformed_extraction_data(self, configured_agent_extractor, sample_chunk, mock_flow_context):
+        """Test handling of malformed extraction data"""
+        # Arrange - mock malformed extraction response
+        agent_client = mock_flow_context("agent-request")
+        
+        def mock_malformed_response(recipient, question):
+            return '''{"definitions": [{"entity": "Missing Definition"}], "relationships": [{"subject": "Missing Object"}]}'''
+        
+        agent_client.invoke = mock_malformed_response
+        
+        mock_message = MagicMock()
+        mock_message.value.return_value = sample_chunk
+        mock_consumer = MagicMock()
+
+        # Act & Assert
+        with pytest.raises(KeyError):
+            await configured_agent_extractor.on_message(mock_message, mock_consumer, mock_flow_context)
+
+    @pytest.mark.asyncio
+    async def test_prompt_rendering_integration(self, configured_agent_extractor, mock_flow_context):
+        """Test integration with prompt template rendering"""
+        # Create a chunk with specific text
+        test_text = "Test text for prompt rendering"
+        chunk = Chunk(
+            chunk=test_text.encode('utf-8'),
+            metadata=Metadata(id="test-doc", metadata=[])
+        )
+        
+        agent_client = mock_flow_context("agent-request")
+        
+        def capture_prompt(recipient, question):
+            # Verify the prompt contains the test text
+            assert test_text in question
+            return '{"definitions": [], "relationships": []}'
+        
+        agent_client.invoke = capture_prompt
+        
+        mock_message = MagicMock()
+        mock_message.value.return_value = chunk
+        mock_consumer = MagicMock()
+
+        # Act
+        await configured_agent_extractor.on_message(mock_message, mock_consumer, mock_flow_context)
+        
+        # Assert - prompt should have been rendered with the text
+        # The agent_client.invoke is a function, not a mock, so we verify it was called by checking the flow worked
+        assert hasattr(agent_client, 'invoke')
+
+    @pytest.mark.asyncio
+    async def test_concurrent_processing_simulation(self, configured_agent_extractor, mock_flow_context):
+        """Test simulation of concurrent chunk processing"""
+        # Create multiple chunks
+        chunks = []
+        for i in range(3):
+            text = f"Test document {i} content"
+            chunks.append(Chunk(
+                chunk=text.encode('utf-8'),
+                metadata=Metadata(id=f"doc{i}", metadata=[])
+            ))
+        
+        agent_client = mock_flow_context("agent-request")
+        responses = []
+        
+        def mock_response(recipient, question):
+            response = f'{{"definitions": [{{"entity": "Entity {len(responses)}", "definition": "Definition {len(responses)}"}}], "relationships": []}}'
+            responses.append(response)
+            return response
+        
+        agent_client.invoke = mock_response
+
+        # Process chunks sequentially (simulating concurrent processing)
+        for chunk in chunks:
+            mock_message = MagicMock()
+            mock_message.value.return_value = chunk
+            mock_consumer = MagicMock()
+            
+            await configured_agent_extractor.on_message(mock_message, mock_consumer, mock_flow_context)
+
+        # Assert
+        assert len(responses) == 3
+        
+        # Verify all chunks were processed
+        triples_publisher = mock_flow_context("triples")
+        assert triples_publisher.send.call_count == 3
+
+    @pytest.mark.asyncio
+    async def test_unicode_text_handling(self, configured_agent_extractor, mock_flow_context):
+        """Test handling of text with unicode characters"""
+        # Create chunk with unicode text
+        unicode_text = "Machine Learning (学习机器) は人工知能の一分野です。"
+        chunk = Chunk(
+            chunk=unicode_text.encode('utf-8'),
+            metadata=Metadata(id="unicode-doc", metadata=[])
+        )
+        
+        agent_client = mock_flow_context("agent-request")
+        
+        def mock_unicode_response(recipient, question):
+            # Verify unicode text was properly decoded and included
+            assert "学习机器" in question
+            assert "人工知能" in question
+            return '''{"definitions": [{"entity": "機械学習", "definition": "人工知能の一分野"}], "relationships": []}'''
+        
+        agent_client.invoke = mock_unicode_response
+        
+        mock_message = MagicMock()
+        mock_message.value.return_value = chunk
+        mock_consumer = MagicMock()
+
+        # Act
+        await configured_agent_extractor.on_message(mock_message, mock_consumer, mock_flow_context)
+
+        # Assert - should handle unicode properly
+        triples_publisher = mock_flow_context("triples")
+        triples_publisher.send.assert_called_once()
+        
+        sent_triples = triples_publisher.send.call_args[0][0]
+        # Check that unicode entity was properly processed
+        entity_labels = [t for t in sent_triples.triples if t.p.value == RDF_LABEL and t.o.value == "機械学習"]
+        assert len(entity_labels) > 0
+
+    @pytest.mark.asyncio
+    async def test_large_text_chunk_processing(self, configured_agent_extractor, mock_flow_context):
+        """Test processing of large text chunks"""
+        # Create a large text chunk
+        large_text = "Machine Learning is important. " * 1000  # Repeat to create large text
+        chunk = Chunk(
+            chunk=large_text.encode('utf-8'),
+            metadata=Metadata(id="large-doc", metadata=[])
+        )
+        
+        agent_client = mock_flow_context("agent-request")
+        
+        def mock_large_text_response(recipient, question):
+            # Verify large text was included
+            assert len(question) > 10000
+            return '''{"definitions": [{"entity": "Machine Learning", "definition": "Important AI technique"}], "relationships": []}'''
+        
+        agent_client.invoke = mock_large_text_response
+        
+        mock_message = MagicMock()
+        mock_message.value.return_value = chunk
+        mock_consumer = MagicMock()
+
+        # Act
+        await configured_agent_extractor.on_message(mock_message, mock_consumer, mock_flow_context)
+
+        # Assert - should handle large text without issues
+        triples_publisher = mock_flow_context("triples")
+        triples_publisher.send.assert_called_once()
+
+    def test_configuration_parameter_validation(self):
+        """Test parameter validation logic"""
+        # Test that default parameter logic would work
+        default_template_id = "agent-kg-extract"
+        default_config_type = "prompt" 
+        default_concurrency = 1
+        
+        # Simulate parameter handling
+        params = {}
+        template_id = params.get("template-id", default_template_id)
+        config_key = params.get("config-type", default_config_type)
+        concurrency = params.get("concurrency", default_concurrency)
+        
+        assert template_id == "agent-kg-extract"
+        assert config_key == "prompt"
+        assert concurrency == 1
+        
+        # Test with custom parameters
+        custom_params = {
+            "template-id": "custom-template",
+            "config-type": "custom-config", 
+            "concurrency": 10
+        }
+        
+        template_id = custom_params.get("template-id", default_template_id)
+        config_key = custom_params.get("config-type", default_config_type)
+        concurrency = custom_params.get("concurrency", default_concurrency)
+        
+        assert template_id == "custom-template"
+        assert config_key == "custom-config"
+        assert concurrency == 10

tests/integration/test_agent_manager_integration.py

@@ -0,0 +1,716 @@
+"""
+Integration tests for Agent Manager (ReAct Pattern) Service
+
+These tests verify the end-to-end functionality of the Agent Manager service,
+testing the ReAct pattern (Think-Act-Observe), tool coordination, multi-step reasoning,
+and conversation state management.
+Following the TEST_STRATEGY.md approach for integration testing.
+"""
+
+import pytest
+import json
+from unittest.mock import AsyncMock, MagicMock, patch
+
+from trustgraph.agent.react.agent_manager import AgentManager
+from trustgraph.agent.react.tools import KnowledgeQueryImpl, TextCompletionImpl, McpToolImpl
+from trustgraph.agent.react.types import Action, Final, Tool, Argument
+from trustgraph.schema import AgentRequest, AgentResponse, AgentStep, Error
+
+
+@pytest.mark.integration
+class TestAgentManagerIntegration:
+    """Integration tests for Agent Manager ReAct pattern coordination"""
+
+    @pytest.fixture
+    def mock_flow_context(self):
+        """Mock flow context for service coordination"""
+        context = MagicMock()
+        
+        # Mock prompt client
+        prompt_client = AsyncMock()
+        prompt_client.agent_react.return_value = """Thought: I need to search for information about machine learning
+Action: knowledge_query
+Args: {
+    "question": "What is machine learning?"
+}"""
+        
+        # Mock graph RAG client
+        graph_rag_client = AsyncMock()
+        graph_rag_client.rag.return_value = "Machine learning is a subset of AI that enables computers to learn from data."
+        
+        # Mock text completion client
+        text_completion_client = AsyncMock()
+        text_completion_client.question.return_value = "Machine learning involves algorithms that improve through experience."
+        
+        # Mock MCP tool client
+        mcp_tool_client = AsyncMock()
+        mcp_tool_client.invoke.return_value = "Tool execution successful"
+        
+        # Configure context to return appropriate clients
+        def context_router(service_name):
+            if service_name == "prompt-request":
+                return prompt_client
+            elif service_name == "graph-rag-request":
+                return graph_rag_client
+            elif service_name == "prompt-request":
+                return text_completion_client
+            elif service_name == "mcp-tool-request":
+                return mcp_tool_client
+            else:
+                return AsyncMock()
+        
+        context.side_effect = context_router
+        return context
+
+    @pytest.fixture
+    def sample_tools(self):
+        """Sample tool configuration for testing"""
+        return {
+            "knowledge_query": Tool(
+                name="knowledge_query",
+                description="Query the knowledge graph for information",
+                arguments=[
+                    Argument(
+                        name="question",
+                        type="string", 
+                        description="The question to ask the knowledge graph"
+                    )
+                ],
+                implementation=KnowledgeQueryImpl,
+                config={}
+            ),
+            "text_completion": Tool(
+                name="text_completion",
+                description="Generate text completion using LLM",
+                arguments=[
+                    Argument(
+                        name="question",
+                        type="string",
+                        description="The question to ask the LLM"
+                    )
+                ],
+                implementation=TextCompletionImpl,
+                config={}
+            ),
+            "web_search": Tool(
+                name="web_search",
+                description="Search the web for information",
+                arguments=[
+                    Argument(
+                        name="query",
+                        type="string",
+                        description="The search query"
+                    )
+                ],
+                implementation=lambda context: AsyncMock(invoke=AsyncMock(return_value="Web search results")),
+                config={}
+            )
+        }
+
+    @pytest.fixture
+    def agent_manager(self, sample_tools):
+        """Create agent manager with sample tools"""
+        return AgentManager(
+            tools=sample_tools,
+            additional_context="You are a helpful AI assistant with access to knowledge and tools."
+        )
+
+    @pytest.mark.asyncio
+    async def test_agent_manager_reasoning_cycle(self, agent_manager, mock_flow_context):
+        """Test basic reasoning cycle with tool selection"""
+        # Arrange
+        question = "What is machine learning?"
+        history = []
+
+        # Act
+        action = await agent_manager.reason(question, history, mock_flow_context)
+
+        # Assert
+        assert isinstance(action, Action)
+        assert action.thought == "I need to search for information about machine learning"
+        assert action.name == "knowledge_query"
+        assert action.arguments == {"question": "What is machine learning?"}
+        assert action.observation == ""
+
+        # Verify prompt client was called correctly
+        prompt_client = mock_flow_context("prompt-request")
+        prompt_client.agent_react.assert_called_once()
+        
+        # Verify the prompt variables passed to agent_react
+        call_args = prompt_client.agent_react.call_args
+        variables = call_args[0][0]
+        assert variables["question"] == question
+        assert len(variables["tools"]) == 3  # knowledge_query, text_completion, web_search
+        assert variables["context"] == "You are a helpful AI assistant with access to knowledge and tools."
+
+    @pytest.mark.asyncio
+    async def test_agent_manager_final_answer(self, agent_manager, mock_flow_context):
+        """Test agent manager returning final answer"""
+        # Arrange
+        mock_flow_context("prompt-request").agent_react.return_value = """Thought: I have enough information to answer the question
+Final Answer: Machine learning is a field of AI that enables computers to learn from data."""
+        
+        question = "What is machine learning?"
+        history = []
+
+        # Act
+        action = await agent_manager.reason(question, history, mock_flow_context)
+
+        # Assert
+        assert isinstance(action, Final)
+        assert action.thought == "I have enough information to answer the question"
+        assert action.final == "Machine learning is a field of AI that enables computers to learn from data."
+
+    @pytest.mark.asyncio
+    async def test_agent_manager_react_with_tool_execution(self, agent_manager, mock_flow_context):
+        """Test full ReAct cycle with tool execution"""
+        # Arrange
+        question = "What is machine learning?"
+        history = []
+        
+        think_callback = AsyncMock()
+        observe_callback = AsyncMock()
+
+        # Act
+        action = await agent_manager.react(question, history, think_callback, observe_callback, mock_flow_context)
+
+        # Assert
+        assert isinstance(action, Action)
+        assert action.thought == "I need to search for information about machine learning"
+        assert action.name == "knowledge_query"
+        assert action.arguments == {"question": "What is machine learning?"}
+        assert action.observation == "Machine learning is a subset of AI that enables computers to learn from data."
+
+        # Verify callbacks were called
+        think_callback.assert_called_once_with("I need to search for information about machine learning")
+        observe_callback.assert_called_once_with("Machine learning is a subset of AI that enables computers to learn from data.")
+
+        # Verify tool was executed
+        graph_rag_client = mock_flow_context("graph-rag-request")
+        graph_rag_client.rag.assert_called_once_with("What is machine learning?")
+
+    @pytest.mark.asyncio
+    async def test_agent_manager_react_with_final_answer(self, agent_manager, mock_flow_context):
+        """Test ReAct cycle ending with final answer"""
+        # Arrange
+        mock_flow_context("prompt-request").agent_react.return_value = """Thought: I can provide a direct answer
+Final Answer: Machine learning is a branch of artificial intelligence."""
+        
+        question = "What is machine learning?"
+        history = []
+        
+        think_callback = AsyncMock()
+        observe_callback = AsyncMock()
+
+        # Act
+        action = await agent_manager.react(question, history, think_callback, observe_callback, mock_flow_context)
+
+        # Assert
+        assert isinstance(action, Final)
+        assert action.thought == "I can provide a direct answer"
+        assert action.final == "Machine learning is a branch of artificial intelligence."
+
+        # Verify only think callback was called (no observation for final answer)
+        think_callback.assert_called_once_with("I can provide a direct answer")
+        observe_callback.assert_not_called()
+
+    @pytest.mark.asyncio
+    async def test_agent_manager_with_conversation_history(self, agent_manager, mock_flow_context):
+        """Test agent manager with conversation history"""
+        # Arrange
+        question = "Can you tell me more about neural networks?"
+        history = [
+            Action(
+                thought="I need to search for information about machine learning",
+                name="knowledge_query",
+                arguments={"question": "What is machine learning?"},
+                observation="Machine learning is a subset of AI that enables computers to learn from data."
+            )
+        ]
+
+        # Act
+        action = await agent_manager.reason(question, history, mock_flow_context)
+
+        # Assert
+        assert isinstance(action, Action)
+        
+        # Verify history was included in prompt variables
+        prompt_client = mock_flow_context("prompt-request")
+        call_args = prompt_client.agent_react.call_args
+        variables = call_args[0][0]
+        assert len(variables["history"]) == 1
+        assert variables["history"][0]["thought"] == "I need to search for information about machine learning"
+        assert variables["history"][0]["action"] == "knowledge_query"
+        assert variables["history"][0]["observation"] == "Machine learning is a subset of AI that enables computers to learn from data."
+
+    @pytest.mark.asyncio
+    async def test_agent_manager_tool_selection(self, agent_manager, mock_flow_context):
+        """Test agent manager selecting different tools"""
+        # Test different tool selections
+        tool_scenarios = [
+            ("knowledge_query", "graph-rag-request"),
+            ("text_completion", "prompt-request"),
+        ]
+
+        for tool_name, expected_service in tool_scenarios:
+            # Arrange
+            mock_flow_context("prompt-request").agent_react.return_value = f"""Thought: I need to use {tool_name}
+Action: {tool_name}
+Args: {{
+    "question": "test question"
+}}"""
+            
+            think_callback = AsyncMock()
+            observe_callback = AsyncMock()
+
+            # Act
+            action = await agent_manager.react("test question", [], think_callback, observe_callback, mock_flow_context)
+
+            # Assert
+            assert isinstance(action, Action)
+            assert action.name == tool_name
+            
+            # Verify correct service was called
+            if tool_name == "knowledge_query":
+                mock_flow_context("graph-rag-request").rag.assert_called()
+            elif tool_name == "text_completion":
+                mock_flow_context("prompt-request").question.assert_called()
+
+            # Reset mocks for next iteration
+            for service in ["prompt-request", "graph-rag-request", "prompt-request"]:
+                mock_flow_context(service).reset_mock()
+
+    @pytest.mark.asyncio
+    async def test_agent_manager_unknown_tool_error(self, agent_manager, mock_flow_context):
+        """Test agent manager error handling for unknown tool"""
+        # Arrange
+        mock_flow_context("prompt-request").agent_react.return_value = """Thought: I need to use an unknown tool
+Action: unknown_tool
+Args: {
+    "param": "value"
+}"""
+        
+        think_callback = AsyncMock()
+        observe_callback = AsyncMock()
+
+        # Act & Assert
+        with pytest.raises(RuntimeError) as exc_info:
+            await agent_manager.react("test question", [], think_callback, observe_callback, mock_flow_context)
+        
+        assert "No action for unknown_tool!" in str(exc_info.value)
+
+    @pytest.mark.asyncio
+    async def test_agent_manager_tool_execution_error(self, agent_manager, mock_flow_context):
+        """Test agent manager handling tool execution errors"""
+        # Arrange
+        mock_flow_context("graph-rag-request").rag.side_effect = Exception("Tool execution failed")
+        
+        think_callback = AsyncMock()
+        observe_callback = AsyncMock()
+
+        # Act & Assert
+        with pytest.raises(Exception) as exc_info:
+            await agent_manager.react("test question", [], think_callback, observe_callback, mock_flow_context)
+        
+        assert "Tool execution failed" in str(exc_info.value)
+
+    @pytest.mark.asyncio
+    async def test_agent_manager_multiple_tools_coordination(self, agent_manager, mock_flow_context):
+        """Test agent manager coordination with multiple available tools"""
+        # Arrange
+        question = "Find information about AI and summarize it"
+        
+        # Mock multi-step reasoning
+        mock_flow_context("prompt-request").agent_react.return_value = """Thought: I need to search for AI information first
+Action: knowledge_query
+Args: {
+    "question": "What is artificial intelligence?"
+}"""
+
+        # Act
+        action = await agent_manager.reason(question, [], mock_flow_context)
+
+        # Assert
+        assert isinstance(action, Action)
+        assert action.name == "knowledge_query"
+        
+        # Verify tool information was passed to prompt
+        prompt_client = mock_flow_context("prompt-request")
+        call_args = prompt_client.agent_react.call_args
+        variables = call_args[0][0]
+        
+        # Should have all 3 tools available
+        tool_names = [tool["name"] for tool in variables["tools"]]
+        assert "knowledge_query" in tool_names
+        assert "text_completion" in tool_names
+        assert "web_search" in tool_names
+
+    @pytest.mark.asyncio
+    async def test_agent_manager_tool_argument_validation(self, agent_manager, mock_flow_context):
+        """Test agent manager with various tool argument patterns"""
+        # Arrange
+        test_cases = [
+            {
+                "action": "knowledge_query",
+                "arguments": {"question": "What is deep learning?"},
+                "expected_service": "graph-rag-request"
+            },
+            {
+                "action": "text_completion", 
+                "arguments": {"question": "Explain neural networks"},
+                "expected_service": "prompt-request"
+            },
+            {
+                "action": "web_search",
+                "arguments": {"query": "latest AI research"},
+                "expected_service": None  # Custom mock
+            }
+        ]
+
+        for test_case in test_cases:
+            # Arrange
+            # Format arguments as JSON
+            import json
+            args_json = json.dumps(test_case['arguments'], indent=4)
+            mock_flow_context("prompt-request").agent_react.return_value = f"""Thought: Using {test_case['action']}
+Action: {test_case['action']}
+Args: {args_json}"""
+            
+            think_callback = AsyncMock()
+            observe_callback = AsyncMock()
+
+            # Act
+            action = await agent_manager.react("test", [], think_callback, observe_callback, mock_flow_context)
+
+            # Assert
+            assert isinstance(action, Action)
+            assert action.name == test_case['action']
+            assert action.arguments == test_case['arguments']
+            
+            # Reset mocks
+            for service in ["prompt-request", "graph-rag-request", "prompt-request"]:
+                mock_flow_context(service).reset_mock()
+
+    @pytest.mark.asyncio
+    async def test_agent_manager_context_integration(self, agent_manager, mock_flow_context):
+        """Test agent manager integration with additional context"""
+        # Arrange
+        agent_with_context = AgentManager(
+            tools={"knowledge_query": agent_manager.tools["knowledge_query"]},
+            additional_context="You are an expert in machine learning research."
+        )
+        
+        question = "What are the latest developments in AI?"
+
+        # Act
+        action = await agent_with_context.reason(question, [], mock_flow_context)
+
+        # Assert
+        prompt_client = mock_flow_context("prompt-request")
+        call_args = prompt_client.agent_react.call_args
+        variables = call_args[0][0]
+        
+        assert variables["context"] == "You are an expert in machine learning research."
+        assert variables["question"] == question
+
+    @pytest.mark.asyncio
+    async def test_agent_manager_empty_tools(self, mock_flow_context):
+        """Test agent manager with no tools available"""
+        # Arrange
+        agent_no_tools = AgentManager(tools={}, additional_context="")
+        
+        question = "What is machine learning?"
+
+        # Act
+        action = await agent_no_tools.reason(question, [], mock_flow_context)
+
+        # Assert
+        prompt_client = mock_flow_context("prompt-request")
+        call_args = prompt_client.agent_react.call_args
+        variables = call_args[0][0]
+        
+        assert len(variables["tools"]) == 0
+        assert variables["tool_names"] == ""
+
+    @pytest.mark.asyncio
+    async def test_agent_manager_tool_response_processing(self, agent_manager, mock_flow_context):
+        """Test agent manager processing different tool response types"""
+        # Arrange
+        response_scenarios = [
+            "Simple text response",
+            "Multi-line response\nwith several lines\nof information",
+            "Response with special characters: @#$%^&*()_+-=[]{}|;':\",./<>?",
+            "   Response with whitespace   ",
+            ""  # Empty response
+        ]
+
+        for expected_response in response_scenarios:
+            # Set up mock response
+            mock_flow_context("graph-rag-request").rag.return_value = expected_response
+            
+            think_callback = AsyncMock()
+            observe_callback = AsyncMock()
+
+            # Act
+            action = await agent_manager.react("test question", [], think_callback, observe_callback, mock_flow_context)
+
+            # Assert
+            assert isinstance(action, Action)
+            assert action.observation == expected_response.strip()
+            observe_callback.assert_called_with(expected_response.strip())
+            
+            # Reset mocks
+            mock_flow_context("graph-rag-request").reset_mock()
+
+    @pytest.mark.asyncio
+    async def test_agent_manager_malformed_response_handling(self, agent_manager, mock_flow_context):
+        """Test agent manager handling of malformed text responses"""
+        # Test cases with expected error messages
+        test_cases = [
+            # Missing action/final answer
+            {
+                "response": "Thought: I need to do something",
+                "error_contains": "Response has thought but no action or final answer"
+            },
+            # Invalid JSON in Args
+            {
+                "response": """Thought: I need to search
+Action: knowledge_query
+Args: {invalid json}""",
+                "error_contains": "Invalid JSON in Args"
+            },
+            # Empty response
+            {
+                "response": "",
+                "error_contains": "Could not parse response"
+            },
+            # Only whitespace
+            {
+                "response": "   \n\t  ",
+                "error_contains": "Could not parse response"
+            },
+            # Missing Args for action (should create empty args dict)
+            {
+                "response": """Thought: I need to search
+Action: knowledge_query""",
+                "error_contains": None  # This should actually succeed with empty args
+            },
+            # Incomplete JSON
+            {
+                "response": """Thought: I need to search
+Action: knowledge_query
+Args: {
+    "question": "test"
+""",
+                "error_contains": "Invalid JSON in Args"
+            },
+        ]
+        
+        for test_case in test_cases:
+            mock_flow_context("prompt-request").agent_react.return_value = test_case["response"]
+            
+            if test_case["error_contains"]:
+                # Should raise an error
+                with pytest.raises(RuntimeError) as exc_info:
+                    await agent_manager.reason("test question", [], mock_flow_context)
+                
+                assert "Failed to parse agent response" in str(exc_info.value)
+                assert test_case["error_contains"] in str(exc_info.value)
+            else:
+                # Should succeed
+                action = await agent_manager.reason("test question", [], mock_flow_context)
+                assert isinstance(action, Action)
+                assert action.name == "knowledge_query"
+                assert action.arguments == {}
+
+    @pytest.mark.asyncio
+    async def test_agent_manager_text_parsing_edge_cases(self, agent_manager, mock_flow_context):
+        """Test edge cases in text parsing"""
+        # Test response with markdown code blocks
+        mock_flow_context("prompt-request").agent_react.return_value = """```
+Thought: I need to search for information
+Action: knowledge_query
+Args: {
+    "question": "What is AI?"
+}
+```"""
+        
+        action = await agent_manager.reason("test", [], mock_flow_context)
+        assert isinstance(action, Action)
+        assert action.thought == "I need to search for information"
+        assert action.name == "knowledge_query"
+        
+        # Test response with extra whitespace
+        mock_flow_context("prompt-request").agent_react.return_value = """
+
+Thought:    I need to think about this    
+Action:   knowledge_query   
+Args:    {
+    "question": "test"
+}
+
+"""
+        
+        action = await agent_manager.reason("test", [], mock_flow_context)
+        assert isinstance(action, Action)
+        assert action.thought == "I need to think about this"
+        assert action.name == "knowledge_query"
+
+    @pytest.mark.asyncio
+    async def test_agent_manager_multiline_content(self, agent_manager, mock_flow_context):
+        """Test handling of multi-line thoughts and final answers"""
+        # Multi-line thought
+        mock_flow_context("prompt-request").agent_react.return_value = """Thought: I need to consider multiple factors:
+1. The user's question is complex
+2. I should search for comprehensive information
+3. This requires using the knowledge query tool
+Action: knowledge_query
+Args: {
+    "question": "complex query"
+}"""
+        
+        action = await agent_manager.reason("test", [], mock_flow_context)
+        assert isinstance(action, Action)
+        assert "multiple factors" in action.thought
+        assert "knowledge query tool" in action.thought
+        
+        # Multi-line final answer
+        mock_flow_context("prompt-request").agent_react.return_value = """Thought: I have gathered enough information
+Final Answer: Here is a comprehensive answer:
+1. First point about the topic
+2. Second point with details
+3. Final conclusion
+
+This covers all aspects of the question."""
+        
+        action = await agent_manager.reason("test", [], mock_flow_context)
+        assert isinstance(action, Final)
+        assert "First point" in action.final
+        assert "Final conclusion" in action.final
+        assert "all aspects" in action.final
+
+    @pytest.mark.asyncio
+    async def test_agent_manager_json_args_special_characters(self, agent_manager, mock_flow_context):
+        """Test JSON arguments with special characters and edge cases"""
+        # Test with special characters in JSON (properly escaped)
+        mock_flow_context("prompt-request").agent_react.return_value = """Thought: Processing special characters
+Action: knowledge_query
+Args: {
+    "question": "What about \\"quotes\\" and 'apostrophes'?",
+    "context": "Line 1\\nLine 2\\tTabbed",
+    "special": "Symbols: @#$%^&*()_+-=[]{}|;':,.<>?"
+}"""
+        
+        action = await agent_manager.reason("test", [], mock_flow_context)
+        assert isinstance(action, Action)
+        assert action.arguments["question"] == 'What about "quotes" and \'apostrophes\'?'
+        assert action.arguments["context"] == "Line 1\nLine 2\tTabbed"
+        assert "@#$%^&*" in action.arguments["special"]
+        
+        # Test with nested JSON
+        mock_flow_context("prompt-request").agent_react.return_value = """Thought: Complex arguments
+Action: web_search
+Args: {
+    "query": "test",
+    "options": {
+        "limit": 10,
+        "filters": ["recent", "relevant"],
+        "metadata": {
+            "source": "user",
+            "timestamp": "2024-01-01"
+        }
+    }
+}"""
+        
+        action = await agent_manager.reason("test", [], mock_flow_context)
+        assert isinstance(action, Action)
+        assert action.arguments["options"]["limit"] == 10
+        assert "recent" in action.arguments["options"]["filters"]
+        assert action.arguments["options"]["metadata"]["source"] == "user"
+
+    @pytest.mark.asyncio
+    async def test_agent_manager_final_answer_json_format(self, agent_manager, mock_flow_context):
+        """Test final answers that contain JSON-like content"""
+        # Final answer with JSON content
+        mock_flow_context("prompt-request").agent_react.return_value = """Thought: I can provide the data in JSON format
+Final Answer: {
+    "result": "success",
+    "data": {
+        "name": "Machine Learning",
+        "type": "AI Technology",
+        "applications": ["NLP", "Computer Vision", "Robotics"]
+    },
+    "confidence": 0.95
+}"""
+        
+        action = await agent_manager.reason("test", [], mock_flow_context)
+        assert isinstance(action, Final)
+        # The final answer should preserve the JSON structure as a string
+        assert '"result": "success"' in action.final
+        assert '"applications":' in action.final
+
+    @pytest.mark.asyncio
+    @pytest.mark.slow
+    async def test_agent_manager_performance_with_large_history(self, agent_manager, mock_flow_context):
+        """Test agent manager performance with large conversation history"""
+        # Arrange
+        large_history = [
+            Action(
+                thought=f"Step {i} thinking",
+                name="knowledge_query",
+                arguments={"question": f"Question {i}"},
+                observation=f"Observation {i}"
+            )
+            for i in range(50)  # Large history
+        ]
+        
+        question = "Final question"
+
+        # Act
+        import time
+        start_time = time.time()
+        
+        action = await agent_manager.reason(question, large_history, mock_flow_context)
+        
+        end_time = time.time()
+        execution_time = end_time - start_time
+
+        # Assert
+        assert isinstance(action, Action)
+        assert execution_time < 5.0  # Should complete within reasonable time
+        
+        # Verify history was processed correctly
+        prompt_client = mock_flow_context("prompt-request")
+        call_args = prompt_client.agent_react.call_args
+        variables = call_args[0][0]
+        assert len(variables["history"]) == 50
+
+    @pytest.mark.asyncio
+    async def test_agent_manager_json_serialization(self, agent_manager, mock_flow_context):
+        """Test agent manager handling of JSON serialization in prompts"""
+        # Arrange
+        complex_history = [
+            Action(
+                thought="Complex thinking with special characters: \"quotes\", 'apostrophes', and symbols",
+                name="knowledge_query",
+                arguments={"question": "What about JSON serialization?", "complex": {"nested": "value"}},
+                observation="Response with JSON: {\"key\": \"value\"}"
+            )
+        ]
+        
+        question = "Handle JSON properly"
+
+        # Act
+        action = await agent_manager.reason(question, complex_history, mock_flow_context)
+
+        # Assert
+        assert isinstance(action, Action)
+        
+        # Verify JSON was properly serialized in prompt
+        prompt_client = mock_flow_context("prompt-request")
+        call_args = prompt_client.agent_react.call_args
+        variables = call_args[0][0]
+        
+        # Should not raise JSON serialization errors
+        json_str = json.dumps(variables, indent=4)
+        assert len(json_str) > 0

tests/integration/test_cassandra_integration.py

@@ -0,0 +1,411 @@
+"""
+Cassandra integration tests using Podman containers
+
+These tests verify end-to-end functionality of Cassandra storage and query processors
+with real database instances. Compatible with Fedora Linux and Podman.
+
+Uses a single container for all tests to minimize startup time.
+"""
+
+import pytest
+import asyncio
+import time
+from unittest.mock import MagicMock
+
+from .cassandra_test_helper import cassandra_container
+from trustgraph.direct.cassandra import TrustGraph
+from trustgraph.storage.triples.cassandra.write import Processor as StorageProcessor
+from trustgraph.query.triples.cassandra.service import Processor as QueryProcessor
+from trustgraph.schema import Triple, Value, Metadata, Triples, TriplesQueryRequest
+
+
+@pytest.mark.integration
+@pytest.mark.slow
+class TestCassandraIntegration:
+    """Integration tests for Cassandra using a single shared container"""
+
+    @pytest.fixture(scope="class")
+    def cassandra_shared_container(self):
+        """Class-level fixture: single Cassandra container for all tests"""
+        with cassandra_container() as container:
+            yield container
+    
+    def setup_method(self):
+        """Track all created clients for cleanup"""
+        self.clients_to_close = []
+    
+    def teardown_method(self):
+        """Clean up all Cassandra connections"""
+        import gc
+        
+        for client in self.clients_to_close:
+            try:
+                client.close()
+            except Exception:
+                pass  # Ignore errors during cleanup
+        
+        # Clear the list and force garbage collection
+        self.clients_to_close.clear()
+        gc.collect()
+        
+        # Small delay to let threads finish
+        time.sleep(0.5)
+
+    @pytest.mark.asyncio
+    async def test_complete_cassandra_integration(self, cassandra_shared_container):
+        """Complete integration test covering all Cassandra functionality"""
+        container = cassandra_shared_container
+        host, port = container.get_connection_host_port()
+        
+        print("=" * 60)
+        print("RUNNING COMPLETE CASSANDRA INTEGRATION TEST")
+        print("=" * 60)
+        
+        # =====================================================
+        # Test 1: Basic TrustGraph Operations
+        # =====================================================
+        print("\n1. Testing basic TrustGraph operations...")
+        
+        client = TrustGraph(
+            hosts=[host],
+            keyspace="test_basic",
+            table="test_table"
+        )
+        self.clients_to_close.append(client)
+        
+        # Insert test data
+        client.insert("http://example.org/alice", "knows", "http://example.org/bob")
+        client.insert("http://example.org/alice", "age", "25")
+        client.insert("http://example.org/bob", "age", "30")
+        
+        # Test get_all
+        all_results = list(client.get_all(limit=10))
+        assert len(all_results) == 3
+        print(f"✓ Stored and retrieved {len(all_results)} triples")
+        
+        # Test get_s (subject query)
+        alice_results = list(client.get_s("http://example.org/alice", limit=10))
+        assert len(alice_results) == 2
+        alice_predicates = [r.p for r in alice_results]
+        assert "knows" in alice_predicates
+        assert "age" in alice_predicates
+        print("✓ Subject queries working")
+        
+        # Test get_p (predicate query)
+        age_results = list(client.get_p("age", limit=10))
+        assert len(age_results) == 2
+        age_subjects = [r.s for r in age_results]
+        assert "http://example.org/alice" in age_subjects
+        assert "http://example.org/bob" in age_subjects
+        print("✓ Predicate queries working")
+        
+        # =====================================================
+        # Test 2: Storage Processor Integration
+        # =====================================================
+        print("\n2. Testing storage processor integration...")
+        
+        storage_processor = StorageProcessor(
+            taskgroup=MagicMock(),
+            hosts=[host],
+            keyspace="test_storage",
+            table="test_triples"
+        )
+        # Track the TrustGraph instance that will be created
+        self.storage_processor = storage_processor
+        
+        # Create test message
+        storage_message = Triples(
+            metadata=Metadata(user="testuser", collection="testcol"),
+            triples=[
+                Triple(
+                    s=Value(value="http://example.org/person1", is_uri=True),
+                    p=Value(value="http://example.org/name", is_uri=True),
+                    o=Value(value="Alice Smith", is_uri=False)
+                ),
+                Triple(
+                    s=Value(value="http://example.org/person1", is_uri=True),
+                    p=Value(value="http://example.org/age", is_uri=True),
+                    o=Value(value="25", is_uri=False)
+                ),
+                Triple(
+                    s=Value(value="http://example.org/person1", is_uri=True),
+                    p=Value(value="http://example.org/department", is_uri=True),
+                    o=Value(value="Engineering", is_uri=False)
+                )
+            ]
+        )
+        
+        # Store triples via processor
+        await storage_processor.store_triples(storage_message)
+        # Track the created TrustGraph instance
+        if hasattr(storage_processor, 'tg'):
+            self.clients_to_close.append(storage_processor.tg)
+        
+        # Verify data was stored
+        storage_results = list(storage_processor.tg.get_s("http://example.org/person1", limit=10))
+        assert len(storage_results) == 3
+        
+        predicates = [row.p for row in storage_results]
+        objects = [row.o for row in storage_results]
+        
+        assert "http://example.org/name" in predicates
+        assert "http://example.org/age" in predicates
+        assert "http://example.org/department" in predicates
+        assert "Alice Smith" in objects
+        assert "25" in objects
+        assert "Engineering" in objects
+        print("✓ Storage processor working")
+        
+        # =====================================================
+        # Test 3: Query Processor Integration
+        # =====================================================
+        print("\n3. Testing query processor integration...")
+        
+        query_processor = QueryProcessor(
+            taskgroup=MagicMock(),
+            hosts=[host],
+            keyspace="test_query",
+            table="test_triples"
+        )
+        
+        # Use same storage processor for the query keyspace
+        query_storage_processor = StorageProcessor(
+            taskgroup=MagicMock(),
+            hosts=[host],
+            keyspace="test_query",
+            table="test_triples"
+        )
+        
+        # Store test data for querying
+        query_test_message = Triples(
+            metadata=Metadata(user="testuser", collection="testcol"),
+            triples=[
+                Triple(
+                    s=Value(value="http://example.org/alice", is_uri=True),
+                    p=Value(value="http://example.org/knows", is_uri=True),
+                    o=Value(value="http://example.org/bob", is_uri=True)
+                ),
+                Triple(
+                    s=Value(value="http://example.org/alice", is_uri=True),
+                    p=Value(value="http://example.org/age", is_uri=True),
+                    o=Value(value="30", is_uri=False)
+                ),
+                Triple(
+                    s=Value(value="http://example.org/bob", is_uri=True),
+                    p=Value(value="http://example.org/knows", is_uri=True),
+                    o=Value(value="http://example.org/charlie", is_uri=True)
+                )
+            ]
+        )
+        await query_storage_processor.store_triples(query_test_message)
+        
+        # Debug: Check what was actually stored
+        print("Debug: Checking what was stored for Alice...")
+        direct_results = list(query_storage_processor.tg.get_s("http://example.org/alice", limit=10))
+        print(f"Direct TrustGraph results: {len(direct_results)}")
+        for result in direct_results:
+            print(f"  S=http://example.org/alice, P={result.p}, O={result.o}")
+        
+        # Test S query (find all relationships for Alice)
+        s_query = TriplesQueryRequest(
+            s=Value(value="http://example.org/alice", is_uri=True),
+            p=None,  # None for wildcard
+            o=None,  # None for wildcard
+            limit=10,
+            user="testuser",
+            collection="testcol"
+        )
+        s_results = await query_processor.query_triples(s_query)
+        print(f"Query processor results: {len(s_results)}")
+        for result in s_results:
+            print(f"  S={result.s.value}, P={result.p.value}, O={result.o.value}")
+        assert len(s_results) == 2
+        
+        s_predicates = [t.p.value for t in s_results]
+        assert "http://example.org/knows" in s_predicates
+        assert "http://example.org/age" in s_predicates
+        print("✓ Subject queries via processor working")
+        
+        # Test P query (find all "knows" relationships)
+        p_query = TriplesQueryRequest(
+            s=None,  # None for wildcard
+            p=Value(value="http://example.org/knows", is_uri=True),
+            o=None,  # None for wildcard
+            limit=10,
+            user="testuser",
+            collection="testcol"
+        )
+        p_results = await query_processor.query_triples(p_query)
+        print(p_results)
+        assert len(p_results) == 2  # Alice knows Bob, Bob knows Charlie
+        
+        p_subjects = [t.s.value for t in p_results]
+        assert "http://example.org/alice" in p_subjects
+        assert "http://example.org/bob" in p_subjects
+        print("✓ Predicate queries via processor working")
+        
+        # =====================================================
+        # Test 4: Concurrent Operations
+        # =====================================================
+        print("\n4. Testing concurrent operations...")
+        
+        concurrent_processor = StorageProcessor(
+            taskgroup=MagicMock(),
+            hosts=[host],
+            keyspace="test_concurrent",
+            table="test_triples"
+        )
+        
+        # Create multiple coroutines for concurrent storage
+        async def store_person_data(person_id, name, age, department):
+            message = Triples(
+                metadata=Metadata(user="concurrent_test", collection="people"),
+                triples=[
+                    Triple(
+                        s=Value(value=f"http://example.org/{person_id}", is_uri=True),
+                        p=Value(value="http://example.org/name", is_uri=True),
+                        o=Value(value=name, is_uri=False)
+                    ),
+                    Triple(
+                        s=Value(value=f"http://example.org/{person_id}", is_uri=True),
+                        p=Value(value="http://example.org/age", is_uri=True),
+                        o=Value(value=str(age), is_uri=False)
+                    ),
+                    Triple(
+                        s=Value(value=f"http://example.org/{person_id}", is_uri=True),
+                        p=Value(value="http://example.org/department", is_uri=True),
+                        o=Value(value=department, is_uri=False)
+                    )
+                ]
+            )
+            await concurrent_processor.store_triples(message)
+        
+        # Store data for multiple people concurrently
+        people_data = [
+            ("person1", "John Doe", 25, "Engineering"),
+            ("person2", "Jane Smith", 30, "Marketing"),
+            ("person3", "Bob Wilson", 35, "Engineering"),
+            ("person4", "Alice Brown", 28, "Sales"),
+        ]
+        
+        # Run storage operations concurrently
+        store_tasks = [store_person_data(pid, name, age, dept) for pid, name, age, dept in people_data]
+        await asyncio.gather(*store_tasks)
+        # Track the created TrustGraph instance
+        if hasattr(concurrent_processor, 'tg'):
+            self.clients_to_close.append(concurrent_processor.tg)
+        
+        # Verify all names were stored
+        name_results = list(concurrent_processor.tg.get_p("http://example.org/name", limit=10))
+        assert len(name_results) == 4
+        
+        stored_names = [r.o for r in name_results]
+        expected_names = ["John Doe", "Jane Smith", "Bob Wilson", "Alice Brown"]
+        
+        for name in expected_names:
+            assert name in stored_names
+        
+        # Verify department data
+        dept_results = list(concurrent_processor.tg.get_p("http://example.org/department", limit=10))
+        assert len(dept_results) == 4
+        
+        stored_depts = [r.o for r in dept_results]
+        assert "Engineering" in stored_depts
+        assert "Marketing" in stored_depts
+        assert "Sales" in stored_depts
+        print("✓ Concurrent operations working")
+        
+        # =====================================================
+        # Test 5: Complex Queries and Data Integrity
+        # =====================================================
+        print("\n5. Testing complex queries and data integrity...")
+        
+        complex_processor = StorageProcessor(
+            taskgroup=MagicMock(),
+            hosts=[host],
+            keyspace="test_complex",
+            table="test_triples"
+        )
+        
+        # Create a knowledge graph about a company
+        company_graph = Triples(
+            metadata=Metadata(user="integration_test", collection="company"),
+            triples=[
+                # People and their types
+                Triple(
+                    s=Value(value="http://company.org/alice", is_uri=True),
+                    p=Value(value="http://www.w3.org/1999/02/22-rdf-syntax-ns#type", is_uri=True),
+                    o=Value(value="http://company.org/Employee", is_uri=True)
+                ),
+                Triple(
+                    s=Value(value="http://company.org/bob", is_uri=True),
+                    p=Value(value="http://www.w3.org/1999/02/22-rdf-syntax-ns#type", is_uri=True),
+                    o=Value(value="http://company.org/Employee", is_uri=True)
+                ),
+                # Relationships
+                Triple(
+                    s=Value(value="http://company.org/alice", is_uri=True),
+                    p=Value(value="http://company.org/reportsTo", is_uri=True),
+                    o=Value(value="http://company.org/bob", is_uri=True)
+                ),
+                Triple(
+                    s=Value(value="http://company.org/alice", is_uri=True),
+                    p=Value(value="http://company.org/worksIn", is_uri=True),
+                    o=Value(value="http://company.org/engineering", is_uri=True)
+                ),
+                # Personal info
+                Triple(
+                    s=Value(value="http://company.org/alice", is_uri=True),
+                    p=Value(value="http://company.org/fullName", is_uri=True),
+                    o=Value(value="Alice Johnson", is_uri=False)
+                ),
+                Triple(
+                    s=Value(value="http://company.org/alice", is_uri=True),
+                    p=Value(value="http://company.org/email", is_uri=True),
+                    o=Value(value="alice@company.org", is_uri=False)
+                ),
+            ]
+        )
+        
+        # Store the company knowledge graph
+        await complex_processor.store_triples(company_graph)
+        # Track the created TrustGraph instance
+        if hasattr(complex_processor, 'tg'):
+            self.clients_to_close.append(complex_processor.tg)
+        
+        # Verify all Alice's data
+        alice_data = list(complex_processor.tg.get_s("http://company.org/alice", limit=20))
+        assert len(alice_data) == 5
+        
+        alice_predicates = [r.p for r in alice_data]
+        expected_predicates = [
+            "http://www.w3.org/1999/02/22-rdf-syntax-ns#type",
+            "http://company.org/reportsTo",
+            "http://company.org/worksIn",
+            "http://company.org/fullName",
+            "http://company.org/email"
+        ]
+        for pred in expected_predicates:
+            assert pred in alice_predicates
+        
+        # Test type-based queries
+        employee_results = list(complex_processor.tg.get_p("http://www.w3.org/1999/02/22-rdf-syntax-ns#type", limit=10))
+        print(employee_results)
+        assert len(employee_results) == 2
+        
+        employees = [r.s for r in employee_results]
+        assert "http://company.org/alice" in employees
+        assert "http://company.org/bob" in employees
+        print("✓ Complex queries and data integrity working")
+        
+        # =====================================================
+        # Summary
+        # =====================================================
+        print("\n" + "=" * 60)
+        print("✅ ALL CASSANDRA INTEGRATION TESTS PASSED!")
+        print("✅ Basic operations: PASSED")
+        print("✅ Storage processor: PASSED") 
+        print("✅ Query processor: PASSED")
+        print("✅ Concurrent operations: PASSED")
+        print("✅ Complex queries: PASSED")
+        print("=" * 60)

tests/integration/test_document_rag_integration.py

@@ -0,0 +1,312 @@
+"""
+Integration tests for DocumentRAG retrieval system
+
+These tests verify the end-to-end functionality of the DocumentRAG system,
+testing the coordination between embeddings, document retrieval, and prompt services.
+Following the TEST_STRATEGY.md approach for integration testing.
+"""
+
+import pytest
+from unittest.mock import AsyncMock, MagicMock
+from trustgraph.retrieval.document_rag.document_rag import DocumentRag
+
+
+@pytest.mark.integration
+class TestDocumentRagIntegration:
+    """Integration tests for DocumentRAG system coordination"""
+
+    @pytest.fixture
+    def mock_embeddings_client(self):
+        """Mock embeddings client that returns realistic vector embeddings"""
+        client = AsyncMock()
+        client.embed.return_value = [
+            [0.1, 0.2, 0.3, 0.4, 0.5],  # Realistic 5-dimensional embedding
+            [0.6, 0.7, 0.8, 0.9, 1.0]   # Second embedding for testing
+        ]
+        return client
+
+    @pytest.fixture
+    def mock_doc_embeddings_client(self):
+        """Mock document embeddings client that returns realistic document chunks"""
+        client = AsyncMock()
+        client.query.return_value = [
+            "Machine learning is a subset of artificial intelligence that focuses on algorithms that learn from data.",
+            "Deep learning uses neural networks with multiple layers to model complex patterns in data.",
+            "Supervised learning algorithms learn from labeled training data to make predictions on new data."
+        ]
+        return client
+
+    @pytest.fixture
+    def mock_prompt_client(self):
+        """Mock prompt client that generates realistic responses"""
+        client = AsyncMock()
+        client.document_prompt.return_value = (
+            "Machine learning is a field of artificial intelligence that enables computers to learn "
+            "and improve from experience without being explicitly programmed. It uses algorithms "
+            "to find patterns in data and make predictions or decisions."
+        )
+        return client
+
+    @pytest.fixture
+    def document_rag(self, mock_embeddings_client, mock_doc_embeddings_client, mock_prompt_client):
+        """Create DocumentRag instance with mocked dependencies"""
+        return DocumentRag(
+            embeddings_client=mock_embeddings_client,
+            doc_embeddings_client=mock_doc_embeddings_client,
+            prompt_client=mock_prompt_client,
+            verbose=True
+        )
+
+    @pytest.mark.asyncio
+    async def test_document_rag_end_to_end_flow(self, document_rag, mock_embeddings_client, 
+                                                mock_doc_embeddings_client, mock_prompt_client):
+        """Test complete DocumentRAG pipeline from query to response"""
+        # Arrange
+        query = "What is machine learning?"
+        user = "test_user"
+        collection = "ml_knowledge"
+        doc_limit = 10
+
+        # Act
+        result = await document_rag.query(
+            query=query,
+            user=user,
+            collection=collection,
+            doc_limit=doc_limit
+        )
+
+        # Assert - Verify service coordination
+        mock_embeddings_client.embed.assert_called_once_with(query)
+        
+        mock_doc_embeddings_client.query.assert_called_once_with(
+            [[0.1, 0.2, 0.3, 0.4, 0.5], [0.6, 0.7, 0.8, 0.9, 1.0]],
+            limit=doc_limit,
+            user=user,
+            collection=collection
+        )
+        
+        mock_prompt_client.document_prompt.assert_called_once_with(
+            query=query,
+            documents=[
+                "Machine learning is a subset of artificial intelligence that focuses on algorithms that learn from data.",
+                "Deep learning uses neural networks with multiple layers to model complex patterns in data.",
+                "Supervised learning algorithms learn from labeled training data to make predictions on new data."
+            ]
+        )
+
+        # Verify final response
+        assert result is not None
+        assert isinstance(result, str)
+        assert "machine learning" in result.lower()
+        assert "artificial intelligence" in result.lower()
+
+    @pytest.mark.asyncio
+    async def test_document_rag_with_no_documents_found(self, mock_embeddings_client, 
+                                                        mock_doc_embeddings_client, mock_prompt_client):
+        """Test DocumentRAG behavior when no documents are retrieved"""
+        # Arrange
+        mock_doc_embeddings_client.query.return_value = []  # No documents found
+        mock_prompt_client.document_prompt.return_value = "I couldn't find any relevant documents for your query."
+        
+        document_rag = DocumentRag(
+            embeddings_client=mock_embeddings_client,
+            doc_embeddings_client=mock_doc_embeddings_client,
+            prompt_client=mock_prompt_client,
+            verbose=False
+        )
+
+        # Act
+        result = await document_rag.query("very obscure query")
+
+        # Assert
+        mock_embeddings_client.embed.assert_called_once()
+        mock_doc_embeddings_client.query.assert_called_once()
+        mock_prompt_client.document_prompt.assert_called_once_with(
+            query="very obscure query",
+            documents=[]
+        )
+        
+        assert result == "I couldn't find any relevant documents for your query."
+
+    @pytest.mark.asyncio
+    async def test_document_rag_embeddings_service_failure(self, mock_embeddings_client, 
+                                                          mock_doc_embeddings_client, mock_prompt_client):
+        """Test DocumentRAG error handling when embeddings service fails"""
+        # Arrange
+        mock_embeddings_client.embed.side_effect = Exception("Embeddings service unavailable")
+        
+        document_rag = DocumentRag(
+            embeddings_client=mock_embeddings_client,
+            doc_embeddings_client=mock_doc_embeddings_client,
+            prompt_client=mock_prompt_client,
+            verbose=False
+        )
+
+        # Act & Assert
+        with pytest.raises(Exception) as exc_info:
+            await document_rag.query("test query")
+        
+        assert "Embeddings service unavailable" in str(exc_info.value)
+        mock_embeddings_client.embed.assert_called_once()
+        mock_doc_embeddings_client.query.assert_not_called()
+        mock_prompt_client.document_prompt.assert_not_called()
+
+    @pytest.mark.asyncio
+    async def test_document_rag_document_service_failure(self, mock_embeddings_client, 
+                                                        mock_doc_embeddings_client, mock_prompt_client):
+        """Test DocumentRAG error handling when document service fails"""
+        # Arrange
+        mock_doc_embeddings_client.query.side_effect = Exception("Document service connection failed")
+        
+        document_rag = DocumentRag(
+            embeddings_client=mock_embeddings_client,
+            doc_embeddings_client=mock_doc_embeddings_client,
+            prompt_client=mock_prompt_client,
+            verbose=False
+        )
+
+        # Act & Assert
+        with pytest.raises(Exception) as exc_info:
+            await document_rag.query("test query")
+        
+        assert "Document service connection failed" in str(exc_info.value)
+        mock_embeddings_client.embed.assert_called_once()
+        mock_doc_embeddings_client.query.assert_called_once()
+        mock_prompt_client.document_prompt.assert_not_called()
+
+    @pytest.mark.asyncio
+    async def test_document_rag_prompt_service_failure(self, mock_embeddings_client, 
+                                                      mock_doc_embeddings_client, mock_prompt_client):
+        """Test DocumentRAG error handling when prompt service fails"""
+        # Arrange
+        mock_prompt_client.document_prompt.side_effect = Exception("LLM service rate limited")
+        
+        document_rag = DocumentRag(
+            embeddings_client=mock_embeddings_client,
+            doc_embeddings_client=mock_doc_embeddings_client,
+            prompt_client=mock_prompt_client,
+            verbose=False
+        )
+
+        # Act & Assert
+        with pytest.raises(Exception) as exc_info:
+            await document_rag.query("test query")
+        
+        assert "LLM service rate limited" in str(exc_info.value)
+        mock_embeddings_client.embed.assert_called_once()
+        mock_doc_embeddings_client.query.assert_called_once()
+        mock_prompt_client.document_prompt.assert_called_once()
+
+    @pytest.mark.asyncio
+    async def test_document_rag_with_different_document_limits(self, document_rag, 
+                                                              mock_doc_embeddings_client):
+        """Test DocumentRAG with various document limit configurations"""
+        # Test different document limits
+        test_cases = [1, 5, 10, 25, 50]
+        
+        for limit in test_cases:
+            # Reset mock call history
+            mock_doc_embeddings_client.reset_mock()
+            
+            # Act
+            await document_rag.query(f"query with limit {limit}", doc_limit=limit)
+            
+            # Assert
+            mock_doc_embeddings_client.query.assert_called_once()
+            call_args = mock_doc_embeddings_client.query.call_args
+            assert call_args.kwargs['limit'] == limit
+
+    @pytest.mark.asyncio
+    async def test_document_rag_multi_user_isolation(self, document_rag, mock_doc_embeddings_client):
+        """Test DocumentRAG properly isolates queries by user and collection"""
+        # Arrange
+        test_scenarios = [
+            ("user1", "collection1"),
+            ("user2", "collection2"),
+            ("user1", "collection2"),  # Same user, different collection
+            ("user2", "collection1"),  # Different user, same collection
+        ]
+
+        for user, collection in test_scenarios:
+            # Reset mock call history
+            mock_doc_embeddings_client.reset_mock()
+            
+            # Act
+            await document_rag.query(
+                f"query from {user} in {collection}",
+                user=user,
+                collection=collection
+            )
+            
+            # Assert
+            mock_doc_embeddings_client.query.assert_called_once()
+            call_args = mock_doc_embeddings_client.query.call_args
+            assert call_args.kwargs['user'] == user
+            assert call_args.kwargs['collection'] == collection
+
+    @pytest.mark.asyncio
+    async def test_document_rag_verbose_logging(self, mock_embeddings_client, 
+                                               mock_doc_embeddings_client, mock_prompt_client, 
+                                               caplog):
+        """Test DocumentRAG verbose logging functionality"""
+        import logging
+        
+        # Arrange - Configure logging to capture debug messages
+        caplog.set_level(logging.DEBUG)
+        
+        document_rag = DocumentRag(
+            embeddings_client=mock_embeddings_client,
+            doc_embeddings_client=mock_doc_embeddings_client,
+            prompt_client=mock_prompt_client,
+            verbose=True
+        )
+
+        # Act
+        await document_rag.query("test query for verbose logging")
+
+        # Assert - Check for new logging messages
+        log_messages = caplog.text
+        assert "DocumentRag initialized" in log_messages
+        assert "Constructing prompt..." in log_messages
+        assert "Computing embeddings..." in log_messages
+        assert "Getting documents..." in log_messages
+        assert "Invoking LLM..." in log_messages
+        assert "Query processing complete" in log_messages
+
+    @pytest.mark.asyncio
+    @pytest.mark.slow
+    async def test_document_rag_performance_with_large_document_set(self, document_rag, 
+                                                                   mock_doc_embeddings_client):
+        """Test DocumentRAG performance with large document retrieval"""
+        # Arrange - Mock large document set (100 documents)
+        large_doc_set = [f"Document {i} content about machine learning and AI" for i in range(100)]
+        mock_doc_embeddings_client.query.return_value = large_doc_set
+
+        # Act
+        import time
+        start_time = time.time()
+        
+        result = await document_rag.query("performance test query", doc_limit=100)
+        
+        end_time = time.time()
+        execution_time = end_time - start_time
+
+        # Assert
+        assert result is not None
+        assert execution_time < 5.0  # Should complete within 5 seconds
+        mock_doc_embeddings_client.query.assert_called_once()
+        call_args = mock_doc_embeddings_client.query.call_args
+        assert call_args.kwargs['limit'] == 100
+
+    @pytest.mark.asyncio
+    async def test_document_rag_default_parameters(self, document_rag, mock_doc_embeddings_client):
+        """Test DocumentRAG uses correct default parameters"""
+        # Act
+        await document_rag.query("test query with defaults")
+
+        # Assert
+        mock_doc_embeddings_client.query.assert_called_once()
+        call_args = mock_doc_embeddings_client.query.call_args
+        assert call_args.kwargs['user'] == "trustgraph"
+        assert call_args.kwargs['collection'] == "default"
+        assert call_args.kwargs['limit'] == 20

tests/integration/test_kg_extract_store_integration.py

@@ -0,0 +1,642 @@
+"""
+Integration tests for Knowledge Graph Extract → Store Pipeline
+
+These tests verify the end-to-end functionality of the knowledge graph extraction
+and storage pipeline, testing text-to-graph transformation, entity extraction,
+relationship extraction, and graph database storage.
+Following the TEST_STRATEGY.md approach for integration testing.
+"""
+
+import pytest
+import json
+import urllib.parse
+from unittest.mock import AsyncMock, MagicMock, patch
+
+from trustgraph.extract.kg.definitions.extract import Processor as DefinitionsProcessor
+from trustgraph.extract.kg.relationships.extract import Processor as RelationshipsProcessor
+from trustgraph.storage.knowledge.store import Processor as KnowledgeStoreProcessor
+from trustgraph.schema import Chunk, Triple, Triples, Metadata, Value, Error
+from trustgraph.schema import EntityContext, EntityContexts, GraphEmbeddings
+from trustgraph.rdf import TRUSTGRAPH_ENTITIES, DEFINITION, RDF_LABEL, SUBJECT_OF
+
+
+@pytest.mark.integration
+class TestKnowledgeGraphPipelineIntegration:
+    """Integration tests for Knowledge Graph Extract → Store Pipeline"""
+
+    @pytest.fixture
+    def mock_flow_context(self):
+        """Mock flow context for service coordination"""
+        context = MagicMock()
+        
+        # Mock prompt client for definitions extraction
+        prompt_client = AsyncMock()
+        prompt_client.extract_definitions.return_value = [
+            {
+                "entity": "Machine Learning",
+                "definition": "A subset of artificial intelligence that enables computers to learn from data without explicit programming."
+            },
+            {
+                "entity": "Neural Networks",
+                "definition": "Computing systems inspired by biological neural networks that process information."
+            }
+        ]
+        
+        # Mock prompt client for relationships extraction
+        prompt_client.extract_relationships.return_value = [
+            {
+                "subject": "Machine Learning",
+                "predicate": "is_subset_of",
+                "object": "Artificial Intelligence",
+                "object-entity": True
+            },
+            {
+                "subject": "Neural Networks",
+                "predicate": "is_used_in",
+                "object": "Machine Learning",
+                "object-entity": True
+            }
+        ]
+        
+        # Mock producers for output streams
+        triples_producer = AsyncMock()
+        entity_contexts_producer = AsyncMock()
+        
+        # Configure context routing
+        def context_router(service_name):
+            if service_name == "prompt-request":
+                return prompt_client
+            elif service_name == "triples":
+                return triples_producer
+            elif service_name == "entity-contexts":
+                return entity_contexts_producer
+            else:
+                return AsyncMock()
+        
+        context.side_effect = context_router
+        return context
+
+    @pytest.fixture
+    def mock_cassandra_store(self):
+        """Mock Cassandra knowledge table store"""
+        store = AsyncMock()
+        store.add_triples.return_value = None
+        store.add_graph_embeddings.return_value = None
+        return store
+
+    @pytest.fixture
+    def sample_chunk(self):
+        """Sample text chunk for processing"""
+        return Chunk(
+            metadata=Metadata(
+                id="doc-123",
+                user="test_user",
+                collection="test_collection",
+                metadata=[]
+            ),
+            chunk=b"Machine Learning is a subset of Artificial Intelligence. Neural Networks are used in Machine Learning to process complex patterns."
+        )
+
+    @pytest.fixture
+    def sample_definitions_response(self):
+        """Sample definitions extraction response"""
+        return [
+            {
+                "entity": "Machine Learning",
+                "definition": "A subset of artificial intelligence that enables computers to learn from data."
+            },
+            {
+                "entity": "Artificial Intelligence",
+                "definition": "The simulation of human intelligence in machines."
+            },
+            {
+                "entity": "Neural Networks",
+                "definition": "Computing systems inspired by biological neural networks."
+            }
+        ]
+
+    @pytest.fixture
+    def sample_relationships_response(self):
+        """Sample relationships extraction response"""
+        return [
+            {
+                "subject": "Machine Learning",
+                "predicate": "is_subset_of",
+                "object": "Artificial Intelligence",
+                "object-entity": True
+            },
+            {
+                "subject": "Neural Networks",
+                "predicate": "is_used_in",
+                "object": "Machine Learning",
+                "object-entity": True
+            },
+            {
+                "subject": "Machine Learning",
+                "predicate": "processes",
+                "object": "data patterns",
+                "object-entity": False
+            }
+        ]
+
+    @pytest.fixture
+    def definitions_processor(self):
+        """Create definitions processor with minimal configuration"""
+        processor = MagicMock()
+        processor.to_uri = DefinitionsProcessor.to_uri.__get__(processor, DefinitionsProcessor)
+        processor.emit_triples = DefinitionsProcessor.emit_triples.__get__(processor, DefinitionsProcessor)
+        processor.emit_ecs = DefinitionsProcessor.emit_ecs.__get__(processor, DefinitionsProcessor)
+        processor.on_message = DefinitionsProcessor.on_message.__get__(processor, DefinitionsProcessor)
+        return processor
+
+    @pytest.fixture
+    def relationships_processor(self):
+        """Create relationships processor with minimal configuration"""
+        processor = MagicMock()
+        processor.to_uri = RelationshipsProcessor.to_uri.__get__(processor, RelationshipsProcessor)
+        processor.emit_triples = RelationshipsProcessor.emit_triples.__get__(processor, RelationshipsProcessor)
+        processor.on_message = RelationshipsProcessor.on_message.__get__(processor, RelationshipsProcessor)
+        return processor
+
+    @pytest.mark.asyncio
+    async def test_definitions_extraction_pipeline(self, definitions_processor, mock_flow_context, sample_chunk):
+        """Test definitions extraction from text chunk to graph triples"""
+        # Arrange
+        mock_msg = MagicMock()
+        mock_msg.value.return_value = sample_chunk
+        mock_consumer = MagicMock()
+
+        # Act
+        await definitions_processor.on_message(mock_msg, mock_consumer, mock_flow_context)
+
+        # Assert
+        # Verify prompt client was called for definitions extraction
+        prompt_client = mock_flow_context("prompt-request")
+        prompt_client.extract_definitions.assert_called_once()
+        call_args = prompt_client.extract_definitions.call_args
+        assert "Machine Learning" in call_args.kwargs['text']
+        assert "Neural Networks" in call_args.kwargs['text']
+
+        # Verify triples producer was called
+        triples_producer = mock_flow_context("triples")
+        triples_producer.send.assert_called_once()
+        
+        # Verify entity contexts producer was called
+        entity_contexts_producer = mock_flow_context("entity-contexts")
+        entity_contexts_producer.send.assert_called_once()
+
+    @pytest.mark.asyncio
+    async def test_relationships_extraction_pipeline(self, relationships_processor, mock_flow_context, sample_chunk):
+        """Test relationships extraction from text chunk to graph triples"""
+        # Arrange
+        mock_msg = MagicMock()
+        mock_msg.value.return_value = sample_chunk
+        mock_consumer = MagicMock()
+
+        # Act
+        await relationships_processor.on_message(mock_msg, mock_consumer, mock_flow_context)
+
+        # Assert
+        # Verify prompt client was called for relationships extraction
+        prompt_client = mock_flow_context("prompt-request")
+        prompt_client.extract_relationships.assert_called_once()
+        call_args = prompt_client.extract_relationships.call_args
+        assert "Machine Learning" in call_args.kwargs['text']
+
+        # Verify triples producer was called
+        triples_producer = mock_flow_context("triples")
+        triples_producer.send.assert_called_once()
+
+    @pytest.mark.asyncio
+    async def test_uri_generation_consistency(self, definitions_processor, relationships_processor):
+        """Test URI generation consistency between processors"""
+        # Arrange
+        test_entities = [
+            "Machine Learning",
+            "Artificial Intelligence",
+            "Neural Networks",
+            "Deep Learning",
+            "Natural Language Processing"
+        ]
+
+        # Act & Assert
+        for entity in test_entities:
+            def_uri = definitions_processor.to_uri(entity)
+            rel_uri = relationships_processor.to_uri(entity)
+            
+            # URIs should be identical between processors
+            assert def_uri == rel_uri
+            
+            # URI should be properly encoded
+            assert def_uri.startswith(TRUSTGRAPH_ENTITIES)
+            assert " " not in def_uri
+            assert def_uri.endswith(urllib.parse.quote(entity.replace(" ", "-").lower().encode("utf-8")))
+
+    @pytest.mark.asyncio
+    async def test_definitions_triple_generation(self, definitions_processor, sample_definitions_response):
+        """Test triple generation from definitions extraction"""
+        # Arrange
+        metadata = Metadata(
+            id="test-doc",
+            user="test_user",
+            collection="test_collection",
+            metadata=[]
+        )
+
+        # Act
+        triples = []
+        entities = []
+        
+        for defn in sample_definitions_response:
+            s = defn["entity"]
+            o = defn["definition"]
+            
+            if s and o:
+                s_uri = definitions_processor.to_uri(s)
+                s_value = Value(value=str(s_uri), is_uri=True)
+                o_value = Value(value=str(o), is_uri=False)
+                
+                # Generate triples as the processor would
+                triples.append(Triple(
+                    s=s_value,
+                    p=Value(value=RDF_LABEL, is_uri=True),
+                    o=Value(value=s, is_uri=False)
+                ))
+                
+                triples.append(Triple(
+                    s=s_value,
+                    p=Value(value=DEFINITION, is_uri=True),
+                    o=o_value
+                ))
+                
+                entities.append(EntityContext(
+                    entity=s_value,
+                    context=defn["definition"]
+                ))
+
+        # Assert
+        assert len(triples) == 6  # 2 triples per entity * 3 entities
+        assert len(entities) == 3  # 1 entity context per entity
+        
+        # Verify triple structure
+        label_triples = [t for t in triples if t.p.value == RDF_LABEL]
+        definition_triples = [t for t in triples if t.p.value == DEFINITION]
+        
+        assert len(label_triples) == 3
+        assert len(definition_triples) == 3
+        
+        # Verify entity contexts
+        for entity in entities:
+            assert entity.entity.is_uri is True
+            assert entity.entity.value.startswith(TRUSTGRAPH_ENTITIES)
+            assert len(entity.context) > 0
+
+    @pytest.mark.asyncio
+    async def test_relationships_triple_generation(self, relationships_processor, sample_relationships_response):
+        """Test triple generation from relationships extraction"""
+        # Arrange
+        metadata = Metadata(
+            id="test-doc",
+            user="test_user",
+            collection="test_collection",
+            metadata=[]
+        )
+
+        # Act
+        triples = []
+        
+        for rel in sample_relationships_response:
+            s = rel["subject"]
+            p = rel["predicate"]
+            o = rel["object"]
+            
+            if s and p and o:
+                s_uri = relationships_processor.to_uri(s)
+                s_value = Value(value=str(s_uri), is_uri=True)
+                
+                p_uri = relationships_processor.to_uri(p)
+                p_value = Value(value=str(p_uri), is_uri=True)
+                
+                if rel["object-entity"]:
+                    o_uri = relationships_processor.to_uri(o)
+                    o_value = Value(value=str(o_uri), is_uri=True)
+                else:
+                    o_value = Value(value=str(o), is_uri=False)
+                
+                # Main relationship triple
+                triples.append(Triple(s=s_value, p=p_value, o=o_value))
+                
+                # Label triples
+                triples.append(Triple(
+                    s=s_value,
+                    p=Value(value=RDF_LABEL, is_uri=True),
+                    o=Value(value=str(s), is_uri=False)
+                ))
+                
+                triples.append(Triple(
+                    s=p_value,
+                    p=Value(value=RDF_LABEL, is_uri=True),
+                    o=Value(value=str(p), is_uri=False)
+                ))
+                
+                if rel["object-entity"]:
+                    triples.append(Triple(
+                        s=o_value,
+                        p=Value(value=RDF_LABEL, is_uri=True),
+                        o=Value(value=str(o), is_uri=False)
+                    ))
+
+        # Assert
+        assert len(triples) > 0
+        
+        # Verify relationship triples exist
+        relationship_triples = [t for t in triples if t.p.value.endswith("is_subset_of") or t.p.value.endswith("is_used_in")]
+        assert len(relationship_triples) >= 2
+        
+        # Verify label triples
+        label_triples = [t for t in triples if t.p.value == RDF_LABEL]
+        assert len(label_triples) > 0
+
+    @pytest.mark.asyncio
+    async def test_knowledge_store_triples_storage(self, mock_cassandra_store):
+        """Test knowledge store triples storage integration"""
+        # Arrange
+        processor = MagicMock()
+        processor.table_store = mock_cassandra_store
+        processor.on_triples = KnowledgeStoreProcessor.on_triples.__get__(processor, KnowledgeStoreProcessor)
+        
+        sample_triples = Triples(
+            metadata=Metadata(
+                id="test-doc",
+                user="test_user",
+                collection="test_collection",
+                metadata=[]
+            ),
+            triples=[
+                Triple(
+                    s=Value(value="http://trustgraph.ai/e/machine-learning", is_uri=True),
+                    p=Value(value=DEFINITION, is_uri=True),
+                    o=Value(value="A subset of AI", is_uri=False)
+                )
+            ]
+        )
+        
+        mock_msg = MagicMock()
+        mock_msg.value.return_value = sample_triples
+
+        # Act
+        await processor.on_triples(mock_msg, None, None)
+
+        # Assert
+        mock_cassandra_store.add_triples.assert_called_once_with(sample_triples)
+
+    @pytest.mark.asyncio
+    async def test_knowledge_store_graph_embeddings_storage(self, mock_cassandra_store):
+        """Test knowledge store graph embeddings storage integration"""
+        # Arrange
+        processor = MagicMock()
+        processor.table_store = mock_cassandra_store
+        processor.on_graph_embeddings = KnowledgeStoreProcessor.on_graph_embeddings.__get__(processor, KnowledgeStoreProcessor)
+        
+        sample_embeddings = GraphEmbeddings(
+            metadata=Metadata(
+                id="test-doc",
+                user="test_user",
+                collection="test_collection",
+                metadata=[]
+            ),
+            entities=[]
+        )
+        
+        mock_msg = MagicMock()
+        mock_msg.value.return_value = sample_embeddings
+
+        # Act
+        await processor.on_graph_embeddings(mock_msg, None, None)
+
+        # Assert
+        mock_cassandra_store.add_graph_embeddings.assert_called_once_with(sample_embeddings)
+
+    @pytest.mark.asyncio
+    async def test_end_to_end_pipeline_coordination(self, definitions_processor, relationships_processor, 
+                                                   mock_flow_context, sample_chunk):
+        """Test end-to-end pipeline coordination from chunk to storage"""
+        # Arrange
+        mock_msg = MagicMock()
+        mock_msg.value.return_value = sample_chunk
+        mock_consumer = MagicMock()
+
+        # Act - Process through definitions extractor
+        await definitions_processor.on_message(mock_msg, mock_consumer, mock_flow_context)
+        
+        # Act - Process through relationships extractor
+        await relationships_processor.on_message(mock_msg, mock_consumer, mock_flow_context)
+
+        # Assert
+        # Verify both extractors called prompt service
+        prompt_client = mock_flow_context("prompt-request")
+        prompt_client.extract_definitions.assert_called_once()
+        prompt_client.extract_relationships.assert_called_once()
+        
+        # Verify triples were produced from both extractors
+        triples_producer = mock_flow_context("triples")
+        assert triples_producer.send.call_count == 2  # One from each extractor
+        
+        # Verify entity contexts were produced from definitions extractor
+        entity_contexts_producer = mock_flow_context("entity-contexts")
+        entity_contexts_producer.send.assert_called_once()
+
+    @pytest.mark.asyncio
+    async def test_error_handling_in_definitions_extraction(self, definitions_processor, mock_flow_context, sample_chunk):
+        """Test error handling in definitions extraction"""
+        # Arrange
+        mock_flow_context("prompt-request").extract_definitions.side_effect = Exception("Prompt service unavailable")
+        
+        mock_msg = MagicMock()
+        mock_msg.value.return_value = sample_chunk
+        mock_consumer = MagicMock()
+
+        # Act & Assert
+        # Should not raise exception, but should handle it gracefully
+        await definitions_processor.on_message(mock_msg, mock_consumer, mock_flow_context)
+        
+        # Verify prompt was attempted
+        prompt_client = mock_flow_context("prompt-request")
+        prompt_client.extract_definitions.assert_called_once()
+
+    @pytest.mark.asyncio
+    async def test_error_handling_in_relationships_extraction(self, relationships_processor, mock_flow_context, sample_chunk):
+        """Test error handling in relationships extraction"""
+        # Arrange
+        mock_flow_context("prompt-request").extract_relationships.side_effect = Exception("Prompt service unavailable")
+        
+        mock_msg = MagicMock()
+        mock_msg.value.return_value = sample_chunk
+        mock_consumer = MagicMock()
+
+        # Act & Assert
+        # Should not raise exception, but should handle it gracefully
+        await relationships_processor.on_message(mock_msg, mock_consumer, mock_flow_context)
+        
+        # Verify prompt was attempted
+        prompt_client = mock_flow_context("prompt-request")
+        prompt_client.extract_relationships.assert_called_once()
+
+    @pytest.mark.asyncio
+    async def test_empty_extraction_results_handling(self, definitions_processor, mock_flow_context, sample_chunk):
+        """Test handling of empty extraction results"""
+        # Arrange
+        mock_flow_context("prompt-request").extract_definitions.return_value = []
+        
+        mock_msg = MagicMock()
+        mock_msg.value.return_value = sample_chunk
+        mock_consumer = MagicMock()
+
+        # Act
+        await definitions_processor.on_message(mock_msg, mock_consumer, mock_flow_context)
+
+        # Assert
+        # Should still call producers but with empty results
+        triples_producer = mock_flow_context("triples")
+        entity_contexts_producer = mock_flow_context("entity-contexts")
+        
+        triples_producer.send.assert_called_once()
+        entity_contexts_producer.send.assert_called_once()
+
+    @pytest.mark.asyncio
+    async def test_invalid_extraction_format_handling(self, definitions_processor, mock_flow_context, sample_chunk):
+        """Test handling of invalid extraction response format"""
+        # Arrange
+        mock_flow_context("prompt-request").extract_definitions.return_value = "invalid format"  # Should be list
+        
+        mock_msg = MagicMock()
+        mock_msg.value.return_value = sample_chunk
+        mock_consumer = MagicMock()
+
+        # Act & Assert
+        # Should handle invalid format gracefully
+        await definitions_processor.on_message(mock_msg, mock_consumer, mock_flow_context)
+        
+        # Verify prompt was attempted
+        prompt_client = mock_flow_context("prompt-request")
+        prompt_client.extract_definitions.assert_called_once()
+
+    @pytest.mark.asyncio
+    async def test_entity_filtering_and_validation(self, definitions_processor, mock_flow_context):
+        """Test entity filtering and validation in extraction"""
+        # Arrange
+        mock_flow_context("prompt-request").extract_definitions.return_value = [
+            {"entity": "Valid Entity", "definition": "Valid definition"},
+            {"entity": "", "definition": "Empty entity"},  # Should be filtered
+            {"entity": "Valid Entity 2", "definition": ""},  # Should be filtered
+            {"entity": None, "definition": "None entity"},  # Should be filtered
+            {"entity": "Valid Entity 3", "definition": None},  # Should be filtered
+        ]
+        
+        sample_chunk = Chunk(
+            metadata=Metadata(id="test", user="user", collection="collection", metadata=[]),
+            chunk=b"Test chunk"
+        )
+        
+        mock_msg = MagicMock()
+        mock_msg.value.return_value = sample_chunk
+        mock_consumer = MagicMock()
+
+        # Act
+        await definitions_processor.on_message(mock_msg, mock_consumer, mock_flow_context)
+
+        # Assert
+        # Should only process valid entities
+        triples_producer = mock_flow_context("triples")
+        entity_contexts_producer = mock_flow_context("entity-contexts")
+        
+        triples_producer.send.assert_called_once()
+        entity_contexts_producer.send.assert_called_once()
+
+    @pytest.mark.asyncio
+    @pytest.mark.slow
+    async def test_large_batch_processing_performance(self, definitions_processor, relationships_processor, 
+                                                     mock_flow_context):
+        """Test performance with large batch of chunks"""
+        # Arrange
+        large_chunk_batch = [
+            Chunk(
+                metadata=Metadata(id=f"doc-{i}", user="user", collection="collection", metadata=[]),
+                chunk=f"Document {i} contains machine learning and AI content.".encode("utf-8")
+            )
+            for i in range(100)  # Large batch
+        ]
+        
+        mock_consumer = MagicMock()
+
+        # Act
+        import time
+        start_time = time.time()
+        
+        for chunk in large_chunk_batch:
+            mock_msg = MagicMock()
+            mock_msg.value.return_value = chunk
+            
+            # Process through both extractors
+            await definitions_processor.on_message(mock_msg, mock_consumer, mock_flow_context)
+            await relationships_processor.on_message(mock_msg, mock_consumer, mock_flow_context)
+        
+        end_time = time.time()
+        execution_time = end_time - start_time
+
+        # Assert
+        assert execution_time < 30.0  # Should complete within reasonable time
+        
+        # Verify all chunks were processed
+        prompt_client = mock_flow_context("prompt-request")
+        assert prompt_client.extract_definitions.call_count == 100
+        assert prompt_client.extract_relationships.call_count == 100
+
+    @pytest.mark.asyncio
+    async def test_metadata_propagation_through_pipeline(self, definitions_processor, mock_flow_context):
+        """Test metadata propagation through the pipeline"""
+        # Arrange
+        original_metadata = Metadata(
+            id="test-doc-123",
+            user="test_user",
+            collection="test_collection",
+            metadata=[
+                Triple(
+                    s=Value(value="doc:test", is_uri=True),
+                    p=Value(value="dc:title", is_uri=True),
+                    o=Value(value="Test Document", is_uri=False)
+                )
+            ]
+        )
+        
+        sample_chunk = Chunk(
+            metadata=original_metadata,
+            chunk=b"Test content for metadata propagation"
+        )
+        
+        mock_msg = MagicMock()
+        mock_msg.value.return_value = sample_chunk
+        mock_consumer = MagicMock()
+
+        # Act
+        await definitions_processor.on_message(mock_msg, mock_consumer, mock_flow_context)
+
+        # Assert
+        # Verify metadata was propagated to output
+        triples_producer = mock_flow_context("triples")
+        entity_contexts_producer = mock_flow_context("entity-contexts")
+        
+        triples_producer.send.assert_called_once()
+        entity_contexts_producer.send.assert_called_once()
+        
+        # Check that metadata was included in the calls
+        triples_call = triples_producer.send.call_args[0][0]
+        entity_contexts_call = entity_contexts_producer.send.call_args[0][0]
+        
+        assert triples_call.metadata.id == "test-doc-123"
+        assert triples_call.metadata.user == "test_user"
+        assert triples_call.metadata.collection == "test_collection"
+        
+        assert entity_contexts_call.metadata.id == "test-doc-123"
+        assert entity_contexts_call.metadata.user == "test_user"
+        assert entity_contexts_call.metadata.collection == "test_collection"

tests/integration/test_object_extraction_integration.py

@@ -0,0 +1,540 @@
+"""
+Integration tests for Object Extraction Service
+
+These tests verify the end-to-end functionality of the object extraction service,
+testing configuration management, text-to-object transformation, and service coordination.
+Following the TEST_STRATEGY.md approach for integration testing.
+"""
+
+import pytest
+import json
+import asyncio
+from unittest.mock import AsyncMock, MagicMock, patch
+
+from trustgraph.extract.kg.objects.processor import Processor
+from trustgraph.schema import (
+    Chunk, ExtractedObject, Metadata, RowSchema, Field,
+    PromptRequest, PromptResponse
+)
+
+
+@pytest.mark.integration
+class TestObjectExtractionServiceIntegration:
+    """Integration tests for Object Extraction Service"""
+
+    @pytest.fixture
+    def integration_config(self):
+        """Integration test configuration with multiple schemas"""
+        customer_schema = {
+            "name": "customer_records",
+            "description": "Customer information schema",
+            "fields": [
+                {
+                    "name": "customer_id",
+                    "type": "string", 
+                    "primary_key": True,
+                    "required": True,
+                    "indexed": True,
+                    "description": "Unique customer identifier"
+                },
+                {
+                    "name": "name",
+                    "type": "string",
+                    "required": True,
+                    "description": "Customer full name"
+                },
+                {
+                    "name": "email",
+                    "type": "string",
+                    "required": True,
+                    "indexed": True,
+                    "description": "Customer email address"
+                },
+                {
+                    "name": "phone",
+                    "type": "string", 
+                    "required": False,
+                    "description": "Customer phone number"
+                }
+            ]
+        }
+        
+        product_schema = {
+            "name": "product_catalog",
+            "description": "Product catalog schema",
+            "fields": [
+                {
+                    "name": "product_id",
+                    "type": "string",
+                    "primary_key": True,
+                    "required": True,
+                    "indexed": True,
+                    "description": "Unique product identifier"
+                },
+                {
+                    "name": "name",
+                    "type": "string",
+                    "required": True,
+                    "description": "Product name"
+                },
+                {
+                    "name": "price",
+                    "type": "double",
+                    "required": True,
+                    "description": "Product price"
+                },
+                {
+                    "name": "category",
+                    "type": "string",
+                    "required": False,
+                    "enum": ["electronics", "clothing", "books", "home"],
+                    "description": "Product category"
+                }
+            ]
+        }
+        
+        return {
+            "schema": {
+                "customer_records": json.dumps(customer_schema),
+                "product_catalog": json.dumps(product_schema)
+            }
+        }
+
+    @pytest.fixture
+    def mock_integrated_flow(self):
+        """Mock integrated flow context with realistic prompt responses"""
+        context = MagicMock()
+        
+        # Mock prompt client with realistic responses
+        prompt_client = AsyncMock()
+        
+        def mock_extract_objects(schema, text):
+            """Mock extract_objects with schema-aware responses"""
+            # Schema is now a dict (converted by row_schema_translator)
+            schema_name = schema.get("name") if isinstance(schema, dict) else schema.name
+            if schema_name == "customer_records":
+                if "john" in text.lower():
+                    return [
+                        {
+                            "customer_id": "CUST001",
+                            "name": "John Smith", 
+                            "email": "john.smith@email.com",
+                            "phone": "555-0123"
+                        }
+                    ]
+                elif "jane" in text.lower():
+                    return [
+                        {
+                            "customer_id": "CUST002",
+                            "name": "Jane Doe",
+                            "email": "jane.doe@email.com",
+                            "phone": ""
+                        }
+                    ]
+                else:
+                    return []
+            
+            elif schema_name == "product_catalog":
+                if "laptop" in text.lower():
+                    return [
+                        {
+                            "product_id": "PROD001",
+                            "name": "Gaming Laptop",
+                            "price": "1299.99",
+                            "category": "electronics"
+                        }
+                    ]
+                elif "book" in text.lower():
+                    return [
+                        {
+                            "product_id": "PROD002", 
+                            "name": "Python Programming Guide",
+                            "price": "49.99",
+                            "category": "books"
+                        }
+                    ]
+                else:
+                    return []
+            
+            return []
+        
+        prompt_client.extract_objects.side_effect = mock_extract_objects
+        
+        # Mock output producer
+        output_producer = AsyncMock()
+        
+        def context_router(service_name):
+            if service_name == "prompt-request":
+                return prompt_client
+            elif service_name == "output":
+                return output_producer
+            else:
+                return AsyncMock()
+        
+        context.side_effect = context_router
+        return context
+
+    @pytest.mark.asyncio
+    async def test_multi_schema_configuration_integration(self, integration_config):
+        """Test integration with multiple schema configurations"""
+        # Arrange - Create mock processor with actual methods
+        processor = MagicMock()
+        processor.schemas = {}
+        processor.config_key = "schema"
+        processor.on_schema_config = Processor.on_schema_config.__get__(processor, Processor)
+        
+        # Act
+        await processor.on_schema_config(integration_config, version=1)
+        
+        # Assert
+        assert len(processor.schemas) == 2
+        assert "customer_records" in processor.schemas
+        assert "product_catalog" in processor.schemas
+        
+        # Verify customer schema
+        customer_schema = processor.schemas["customer_records"]
+        assert customer_schema.name == "customer_records"
+        assert len(customer_schema.fields) == 4
+        
+        # Verify product schema
+        product_schema = processor.schemas["product_catalog"]
+        assert product_schema.name == "product_catalog"
+        assert len(product_schema.fields) == 4
+        
+        # Check enum field in product schema
+        category_field = next((f for f in product_schema.fields if f.name == "category"), None)
+        assert category_field is not None
+        assert len(category_field.enum_values) == 4
+        assert "electronics" in category_field.enum_values
+
+    @pytest.mark.asyncio
+    async def test_full_service_integration_customer_extraction(self, integration_config, mock_integrated_flow):
+        """Test full service integration for customer data extraction"""
+        # Arrange - Create mock processor with actual methods
+        processor = MagicMock()
+        processor.schemas = {}
+        processor.config_key = "schema"
+        processor.flow = mock_integrated_flow
+        processor.on_schema_config = Processor.on_schema_config.__get__(processor, Processor)
+        processor.on_chunk = Processor.on_chunk.__get__(processor, Processor)
+        processor.extract_objects_for_schema = Processor.extract_objects_for_schema.__get__(processor, Processor)
+        
+        # Import and bind the convert_values_to_strings function
+        from trustgraph.extract.kg.objects.processor import convert_values_to_strings
+        processor.convert_values_to_strings = convert_values_to_strings
+        
+        # Load configuration
+        await processor.on_schema_config(integration_config, version=1)
+        
+        # Create realistic customer data chunk
+        metadata = Metadata(
+            id="customer-doc-001",
+            user="integration_test",
+            collection="test_documents",
+            metadata=[]
+        )
+        
+        chunk_text = """
+        Customer Registration Form
+        
+        Name: John Smith
+        Email: john.smith@email.com
+        Phone: 555-0123
+        Customer ID: CUST001
+        
+        Registration completed successfully.
+        """
+        
+        chunk = Chunk(metadata=metadata, chunk=chunk_text.encode('utf-8'))
+        
+        # Mock message
+        mock_msg = MagicMock()
+        mock_msg.value.return_value = chunk
+        
+        # Act
+        await processor.on_chunk(mock_msg, None, mock_integrated_flow)
+        
+        # Assert
+        output_producer = mock_integrated_flow("output")
+        
+        # Should have calls for both schemas (even if one returns empty)
+        assert output_producer.send.call_count >= 1
+        
+        # Find customer extraction
+        customer_calls = []
+        for call in output_producer.send.call_args_list:
+            extracted_obj = call[0][0]
+            if extracted_obj.schema_name == "customer_records":
+                customer_calls.append(extracted_obj)
+        
+        assert len(customer_calls) == 1
+        customer_obj = customer_calls[0]
+        
+        assert customer_obj.values["customer_id"] == "CUST001"
+        assert customer_obj.values["name"] == "John Smith"
+        assert customer_obj.values["email"] == "john.smith@email.com"
+        assert customer_obj.confidence > 0.5
+
+    @pytest.mark.asyncio
+    async def test_full_service_integration_product_extraction(self, integration_config, mock_integrated_flow):
+        """Test full service integration for product data extraction"""
+        # Arrange - Create mock processor with actual methods
+        processor = MagicMock()
+        processor.schemas = {}
+        processor.config_key = "schema"
+        processor.flow = mock_integrated_flow
+        processor.on_schema_config = Processor.on_schema_config.__get__(processor, Processor)
+        processor.on_chunk = Processor.on_chunk.__get__(processor, Processor)
+        processor.extract_objects_for_schema = Processor.extract_objects_for_schema.__get__(processor, Processor)
+        
+        # Import and bind the convert_values_to_strings function
+        from trustgraph.extract.kg.objects.processor import convert_values_to_strings
+        processor.convert_values_to_strings = convert_values_to_strings
+        
+        # Load configuration
+        await processor.on_schema_config(integration_config, version=1)
+        
+        # Create realistic product data chunk
+        metadata = Metadata(
+            id="product-doc-001",
+            user="integration_test",
+            collection="test_documents",
+            metadata=[]
+        )
+        
+        chunk_text = """
+        Product Specification Sheet
+        
+        Product Name: Gaming Laptop
+        Product ID: PROD001
+        Price: $1,299.99
+        Category: Electronics
+        
+        High-performance gaming laptop with latest specifications.
+        """
+        
+        chunk = Chunk(metadata=metadata, chunk=chunk_text.encode('utf-8'))
+        
+        # Mock message
+        mock_msg = MagicMock()
+        mock_msg.value.return_value = chunk
+        
+        # Act
+        await processor.on_chunk(mock_msg, None, mock_integrated_flow)
+        
+        # Assert
+        output_producer = mock_integrated_flow("output")
+        
+        # Find product extraction
+        product_calls = []
+        for call in output_producer.send.call_args_list:
+            extracted_obj = call[0][0]
+            if extracted_obj.schema_name == "product_catalog":
+                product_calls.append(extracted_obj)
+        
+        assert len(product_calls) == 1
+        product_obj = product_calls[0]
+        
+        assert product_obj.values["product_id"] == "PROD001"
+        assert product_obj.values["name"] == "Gaming Laptop"
+        assert product_obj.values["price"] == "1299.99"
+        assert product_obj.values["category"] == "electronics"
+
+    @pytest.mark.asyncio
+    async def test_concurrent_extraction_integration(self, integration_config, mock_integrated_flow):
+        """Test concurrent processing of multiple chunks"""
+        # Arrange - Create mock processor with actual methods
+        processor = MagicMock()
+        processor.schemas = {}
+        processor.config_key = "schema"
+        processor.flow = mock_integrated_flow
+        processor.on_schema_config = Processor.on_schema_config.__get__(processor, Processor)
+        processor.on_chunk = Processor.on_chunk.__get__(processor, Processor)
+        processor.extract_objects_for_schema = Processor.extract_objects_for_schema.__get__(processor, Processor)
+        
+        # Import and bind the convert_values_to_strings function
+        from trustgraph.extract.kg.objects.processor import convert_values_to_strings
+        processor.convert_values_to_strings = convert_values_to_strings
+        
+        # Load configuration
+        await processor.on_schema_config(integration_config, version=1)
+        
+        # Create multiple test chunks
+        chunks_data = [
+            ("customer-chunk-1", "Customer: John Smith, email: john.smith@email.com, ID: CUST001"),
+            ("customer-chunk-2", "Customer: Jane Doe, email: jane.doe@email.com, ID: CUST002"),
+            ("product-chunk-1", "Product: Gaming Laptop, ID: PROD001, Price: $1299.99, Category: electronics"),
+            ("product-chunk-2", "Product: Python Programming Guide, ID: PROD002, Price: $49.99, Category: books")
+        ]
+        
+        chunks = []
+        for chunk_id, text in chunks_data:
+            metadata = Metadata(
+                id=chunk_id,
+                user="concurrent_test",
+                collection="test_collection",
+                metadata=[]
+            )
+            chunk = Chunk(metadata=metadata, chunk=text.encode('utf-8'))
+            chunks.append(chunk)
+        
+        # Act - Process chunks concurrently
+        tasks = []
+        for chunk in chunks:
+            mock_msg = MagicMock()
+            mock_msg.value.return_value = chunk
+            task = processor.on_chunk(mock_msg, None, mock_integrated_flow)
+            tasks.append(task)
+        
+        await asyncio.gather(*tasks)
+        
+        # Assert
+        output_producer = mock_integrated_flow("output")
+        
+        # Should have processed all chunks (some may produce objects, some may not)
+        assert output_producer.send.call_count >= 2  # At least customer and product extractions
+        
+        # Verify we got both types of objects
+        extracted_objects = []
+        for call in output_producer.send.call_args_list:
+            extracted_objects.append(call[0][0])
+        
+        customer_objects = [obj for obj in extracted_objects if obj.schema_name == "customer_records"]
+        product_objects = [obj for obj in extracted_objects if obj.schema_name == "product_catalog"]
+        
+        assert len(customer_objects) >= 1
+        assert len(product_objects) >= 1
+
+    @pytest.mark.asyncio
+    async def test_configuration_reload_integration(self, integration_config, mock_integrated_flow):
+        """Test configuration reload during service operation"""
+        # Arrange - Create mock processor with actual methods
+        processor = MagicMock()
+        processor.schemas = {}
+        processor.config_key = "schema"
+        processor.flow = mock_integrated_flow
+        processor.on_schema_config = Processor.on_schema_config.__get__(processor, Processor)
+        
+        # Load initial configuration (only customer schema)
+        initial_config = {
+            "schema": {
+                "customer_records": integration_config["schema"]["customer_records"]
+            }
+        }
+        await processor.on_schema_config(initial_config, version=1)
+        
+        assert len(processor.schemas) == 1
+        assert "customer_records" in processor.schemas
+        assert "product_catalog" not in processor.schemas
+        
+        # Act - Reload with full configuration
+        await processor.on_schema_config(integration_config, version=2)
+        
+        # Assert
+        assert len(processor.schemas) == 2
+        assert "customer_records" in processor.schemas
+        assert "product_catalog" in processor.schemas
+
+    @pytest.mark.asyncio
+    async def test_error_resilience_integration(self, integration_config):
+        """Test service resilience to various error conditions"""
+        # Arrange - Create mock processor with actual methods
+        processor = MagicMock()
+        processor.schemas = {}
+        processor.config_key = "schema"
+        processor.on_schema_config = Processor.on_schema_config.__get__(processor, Processor)
+        processor.on_chunk = Processor.on_chunk.__get__(processor, Processor)
+        processor.extract_objects_for_schema = Processor.extract_objects_for_schema.__get__(processor, Processor)
+        
+        # Import and bind the convert_values_to_strings function
+        from trustgraph.extract.kg.objects.processor import convert_values_to_strings
+        processor.convert_values_to_strings = convert_values_to_strings
+        
+        # Mock flow with failing prompt service
+        failing_flow = MagicMock()
+        failing_prompt = AsyncMock()
+        failing_prompt.extract_rows.side_effect = Exception("Prompt service unavailable")
+        
+        def failing_context_router(service_name):
+            if service_name == "prompt-request":
+                return failing_prompt
+            elif service_name == "output":
+                return AsyncMock()
+            else:
+                return AsyncMock()
+        
+        failing_flow.side_effect = failing_context_router
+        processor.flow = failing_flow
+        
+        # Load configuration
+        await processor.on_schema_config(integration_config, version=1)
+        
+        # Create test chunk
+        metadata = Metadata(id="error-test", user="test", collection="test", metadata=[])
+        chunk = Chunk(metadata=metadata, chunk=b"Some text that will fail to process")
+        
+        mock_msg = MagicMock()
+        mock_msg.value.return_value = chunk
+        
+        # Act & Assert - Should not raise exception
+        try:
+            await processor.on_chunk(mock_msg, None, failing_flow)
+            # Should complete without throwing exception
+        except Exception as e:
+            pytest.fail(f"Service should handle errors gracefully, but raised: {e}")
+
+    @pytest.mark.asyncio
+    async def test_metadata_propagation_integration(self, integration_config, mock_integrated_flow):
+        """Test proper metadata propagation through extraction pipeline"""
+        # Arrange - Create mock processor with actual methods
+        processor = MagicMock()
+        processor.schemas = {}
+        processor.config_key = "schema"
+        processor.flow = mock_integrated_flow
+        processor.on_schema_config = Processor.on_schema_config.__get__(processor, Processor)
+        processor.on_chunk = Processor.on_chunk.__get__(processor, Processor)
+        processor.extract_objects_for_schema = Processor.extract_objects_for_schema.__get__(processor, Processor)
+        
+        # Import and bind the convert_values_to_strings function
+        from trustgraph.extract.kg.objects.processor import convert_values_to_strings
+        processor.convert_values_to_strings = convert_values_to_strings
+        
+        # Load configuration
+        await processor.on_schema_config(integration_config, version=1)
+        
+        # Create chunk with rich metadata
+        original_metadata = Metadata(
+            id="metadata-test-chunk",
+            user="test_user",
+            collection="test_collection",
+            metadata=[]  # Could include source document metadata
+        )
+        
+        chunk = Chunk(
+            metadata=original_metadata,
+            chunk=b"Customer: John Smith, ID: CUST001, email: john.smith@email.com"
+        )
+        
+        mock_msg = MagicMock()
+        mock_msg.value.return_value = chunk
+        
+        # Act
+        await processor.on_chunk(mock_msg, None, mock_integrated_flow)
+        
+        # Assert
+        output_producer = mock_integrated_flow("output")
+        
+        # Find extracted object
+        extracted_obj = None
+        for call in output_producer.send.call_args_list:
+            obj = call[0][0]
+            if obj.schema_name == "customer_records":
+                extracted_obj = obj
+                break
+        
+        assert extracted_obj is not None
+        
+        # Verify metadata propagation
+        assert extracted_obj.metadata.user == "test_user"
+        assert extracted_obj.metadata.collection == "test_collection"
+        assert "metadata-test-chunk" in extracted_obj.metadata.id  # Should include source reference

tests/integration/test_objects_cassandra_integration.py

@@ -0,0 +1,384 @@
+"""
+Integration tests for Cassandra Object Storage
+
+These tests verify the end-to-end functionality of storing ExtractedObjects
+in Cassandra, including table creation, data insertion, and error handling.
+"""
+
+import pytest
+from unittest.mock import MagicMock, AsyncMock, patch
+import json
+import uuid
+
+from trustgraph.storage.objects.cassandra.write import Processor
+from trustgraph.schema import ExtractedObject, Metadata, RowSchema, Field
+
+
+@pytest.mark.integration
+class TestObjectsCassandraIntegration:
+    """Integration tests for Cassandra object storage"""
+
+    @pytest.fixture
+    def mock_cassandra_session(self):
+        """Mock Cassandra session for integration tests"""
+        session = MagicMock()
+        session.execute = MagicMock()
+        return session
+
+    @pytest.fixture
+    def mock_cassandra_cluster(self, mock_cassandra_session):
+        """Mock Cassandra cluster"""
+        cluster = MagicMock()
+        cluster.connect.return_value = mock_cassandra_session
+        cluster.shutdown = MagicMock()
+        return cluster
+
+    @pytest.fixture
+    def processor_with_mocks(self, mock_cassandra_cluster, mock_cassandra_session):
+        """Create processor with mocked Cassandra dependencies"""
+        processor = MagicMock()
+        processor.graph_host = "localhost"
+        processor.graph_username = None
+        processor.graph_password = None
+        processor.config_key = "schema"
+        processor.schemas = {}
+        processor.known_keyspaces = set()
+        processor.known_tables = {}
+        processor.cluster = None
+        processor.session = None
+        
+        # Bind actual methods
+        processor.connect_cassandra = Processor.connect_cassandra.__get__(processor, Processor)
+        processor.ensure_keyspace = Processor.ensure_keyspace.__get__(processor, Processor)
+        processor.ensure_table = Processor.ensure_table.__get__(processor, Processor)
+        processor.sanitize_name = Processor.sanitize_name.__get__(processor, Processor)
+        processor.sanitize_table = Processor.sanitize_table.__get__(processor, Processor)
+        processor.get_cassandra_type = Processor.get_cassandra_type.__get__(processor, Processor)
+        processor.convert_value = Processor.convert_value.__get__(processor, Processor)
+        processor.on_schema_config = Processor.on_schema_config.__get__(processor, Processor)
+        processor.on_object = Processor.on_object.__get__(processor, Processor)
+        
+        return processor, mock_cassandra_cluster, mock_cassandra_session
+
+    @pytest.mark.asyncio
+    async def test_end_to_end_object_storage(self, processor_with_mocks):
+        """Test complete flow from schema config to object storage"""
+        processor, mock_cluster, mock_session = processor_with_mocks
+        
+        # Mock Cluster creation
+        with patch('trustgraph.storage.objects.cassandra.write.Cluster', return_value=mock_cluster):
+            # Step 1: Configure schema
+            config = {
+                "schema": {
+                    "customer_records": json.dumps({
+                        "name": "customer_records",
+                        "description": "Customer information",
+                        "fields": [
+                            {"name": "customer_id", "type": "string", "primary_key": True},
+                            {"name": "name", "type": "string", "required": True},
+                            {"name": "email", "type": "string", "indexed": True},
+                            {"name": "age", "type": "integer"}
+                        ]
+                    })
+                }
+            }
+            
+            await processor.on_schema_config(config, version=1)
+            assert "customer_records" in processor.schemas
+            
+            # Step 2: Process an ExtractedObject
+            test_obj = ExtractedObject(
+                metadata=Metadata(
+                    id="doc-001",
+                    user="test_user",
+                    collection="import_2024",
+                    metadata=[]
+                ),
+                schema_name="customer_records",
+                values={
+                    "customer_id": "CUST001",
+                    "name": "John Doe",
+                    "email": "john@example.com",
+                    "age": "30"
+                },
+                confidence=0.95,
+                source_span="Customer: John Doe..."
+            )
+            
+            msg = MagicMock()
+            msg.value.return_value = test_obj
+            
+            await processor.on_object(msg, None, None)
+            
+            # Verify Cassandra interactions
+            assert mock_cluster.connect.called
+            
+            # Verify keyspace creation
+            keyspace_calls = [call for call in mock_session.execute.call_args_list 
+                            if "CREATE KEYSPACE" in str(call)]
+            assert len(keyspace_calls) == 1
+            assert "test_user" in str(keyspace_calls[0])
+            
+            # Verify table creation
+            table_calls = [call for call in mock_session.execute.call_args_list 
+                         if "CREATE TABLE" in str(call)]
+            assert len(table_calls) == 1
+            assert "o_customer_records" in str(table_calls[0])  # Table gets o_ prefix
+            assert "collection text" in str(table_calls[0])
+            assert "PRIMARY KEY ((collection, customer_id))" in str(table_calls[0])
+            
+            # Verify index creation
+            index_calls = [call for call in mock_session.execute.call_args_list 
+                         if "CREATE INDEX" in str(call)]
+            assert len(index_calls) == 1
+            assert "email" in str(index_calls[0])
+            
+            # Verify data insertion
+            insert_calls = [call for call in mock_session.execute.call_args_list 
+                          if "INSERT INTO" in str(call)]
+            assert len(insert_calls) == 1
+            insert_call = insert_calls[0]
+            assert "test_user.o_customer_records" in str(insert_call)  # Table gets o_ prefix
+            
+            # Check inserted values
+            values = insert_call[0][1]
+            assert "import_2024" in values  # collection
+            assert "CUST001" in values      # customer_id
+            assert "John Doe" in values     # name
+            assert "john@example.com" in values  # email
+            assert 30 in values             # age (converted to int)
+
+    @pytest.mark.asyncio
+    async def test_multi_schema_handling(self, processor_with_mocks):
+        """Test handling multiple schemas and objects"""
+        processor, mock_cluster, mock_session = processor_with_mocks
+        
+        with patch('trustgraph.storage.objects.cassandra.write.Cluster', return_value=mock_cluster):
+            # Configure multiple schemas
+            config = {
+                "schema": {
+                    "products": json.dumps({
+                        "name": "products",
+                        "fields": [
+                            {"name": "product_id", "type": "string", "primary_key": True},
+                            {"name": "name", "type": "string"},
+                            {"name": "price", "type": "float"}
+                        ]
+                    }),
+                    "orders": json.dumps({
+                        "name": "orders",
+                        "fields": [
+                            {"name": "order_id", "type": "string", "primary_key": True},
+                            {"name": "customer_id", "type": "string"},
+                            {"name": "total", "type": "float"}
+                        ]
+                    })
+                }
+            }
+            
+            await processor.on_schema_config(config, version=1)
+            assert len(processor.schemas) == 2
+            
+            # Process objects for different schemas
+            product_obj = ExtractedObject(
+                metadata=Metadata(id="p1", user="shop", collection="catalog", metadata=[]),
+                schema_name="products",
+                values={"product_id": "P001", "name": "Widget", "price": "19.99"},
+                confidence=0.9,
+                source_span="Product..."
+            )
+            
+            order_obj = ExtractedObject(
+                metadata=Metadata(id="o1", user="shop", collection="sales", metadata=[]),
+                schema_name="orders",
+                values={"order_id": "O001", "customer_id": "C001", "total": "59.97"},
+                confidence=0.85,
+                source_span="Order..."
+            )
+            
+            # Process both objects
+            for obj in [product_obj, order_obj]:
+                msg = MagicMock()
+                msg.value.return_value = obj
+                await processor.on_object(msg, None, None)
+            
+            # Verify separate tables were created
+            table_calls = [call for call in mock_session.execute.call_args_list 
+                         if "CREATE TABLE" in str(call)]
+            assert len(table_calls) == 2
+            assert any("o_products" in str(call) for call in table_calls)  # Tables get o_ prefix
+            assert any("o_orders" in str(call) for call in table_calls)    # Tables get o_ prefix
+
+    @pytest.mark.asyncio
+    async def test_missing_required_fields(self, processor_with_mocks):
+        """Test handling of objects with missing required fields"""
+        processor, mock_cluster, mock_session = processor_with_mocks
+        
+        with patch('trustgraph.storage.objects.cassandra.write.Cluster', return_value=mock_cluster):
+            # Configure schema with required field
+            processor.schemas["test_schema"] = RowSchema(
+                name="test_schema",
+                description="Test",
+                fields=[
+                    Field(name="id", type="string", size=50, primary=True, required=True),
+                    Field(name="required_field", type="string", size=100, required=True)
+                ]
+            )
+            
+            # Create object missing required field
+            test_obj = ExtractedObject(
+                metadata=Metadata(id="t1", user="test", collection="test", metadata=[]),
+                schema_name="test_schema",
+                values={"id": "123"},  # missing required_field
+                confidence=0.8,
+                source_span="Test"
+            )
+            
+            msg = MagicMock()
+            msg.value.return_value = test_obj
+            
+            # Should still process (Cassandra doesn't enforce NOT NULL)
+            await processor.on_object(msg, None, None)
+            
+            # Verify insert was attempted
+            insert_calls = [call for call in mock_session.execute.call_args_list 
+                          if "INSERT INTO" in str(call)]
+            assert len(insert_calls) == 1
+
+    @pytest.mark.asyncio
+    async def test_schema_without_primary_key(self, processor_with_mocks):
+        """Test handling schemas without defined primary keys"""
+        processor, mock_cluster, mock_session = processor_with_mocks
+        
+        with patch('trustgraph.storage.objects.cassandra.write.Cluster', return_value=mock_cluster):
+            # Configure schema without primary key
+            processor.schemas["events"] = RowSchema(
+                name="events",
+                description="Event log",
+                fields=[
+                    Field(name="event_type", type="string", size=50),
+                    Field(name="timestamp", type="timestamp", size=0)
+                ]
+            )
+            
+            # Process object
+            test_obj = ExtractedObject(
+                metadata=Metadata(id="e1", user="logger", collection="app_events", metadata=[]),
+                schema_name="events",
+                values={"event_type": "login", "timestamp": "2024-01-01T10:00:00Z"},
+                confidence=1.0,
+                source_span="Event"
+            )
+            
+            msg = MagicMock()
+            msg.value.return_value = test_obj
+            
+            await processor.on_object(msg, None, None)
+            
+            # Verify synthetic_id was added
+            table_calls = [call for call in mock_session.execute.call_args_list 
+                         if "CREATE TABLE" in str(call)]
+            assert len(table_calls) == 1
+            assert "synthetic_id uuid" in str(table_calls[0])
+            
+            # Verify insert includes UUID
+            insert_calls = [call for call in mock_session.execute.call_args_list 
+                          if "INSERT INTO" in str(call)]
+            assert len(insert_calls) == 1
+            values = insert_calls[0][0][1]
+            # Check that a UUID was generated (will be in values list)
+            uuid_found = any(isinstance(v, uuid.UUID) for v in values)
+            assert uuid_found
+
+    @pytest.mark.asyncio
+    async def test_authentication_handling(self, processor_with_mocks):
+        """Test Cassandra authentication"""
+        processor, mock_cluster, mock_session = processor_with_mocks
+        processor.graph_username = "cassandra_user"
+        processor.graph_password = "cassandra_pass"
+        
+        with patch('trustgraph.storage.objects.cassandra.write.Cluster') as mock_cluster_class:
+            with patch('trustgraph.storage.objects.cassandra.write.PlainTextAuthProvider') as mock_auth:
+                mock_cluster_class.return_value = mock_cluster
+                
+                # Trigger connection
+                processor.connect_cassandra()
+                
+                # Verify authentication was configured
+                mock_auth.assert_called_once_with(
+                    username="cassandra_user",
+                    password="cassandra_pass"
+                )
+                mock_cluster_class.assert_called_once()
+                call_kwargs = mock_cluster_class.call_args[1]
+                assert 'auth_provider' in call_kwargs
+
+    @pytest.mark.asyncio 
+    async def test_error_handling_during_insert(self, processor_with_mocks):
+        """Test error handling when insertion fails"""
+        processor, mock_cluster, mock_session = processor_with_mocks
+        
+        with patch('trustgraph.storage.objects.cassandra.write.Cluster', return_value=mock_cluster):
+            processor.schemas["test"] = RowSchema(
+                name="test",
+                fields=[Field(name="id", type="string", size=50, primary=True)]
+            )
+            
+            # Make insert fail
+            mock_session.execute.side_effect = [
+                None,  # keyspace creation succeeds
+                None,  # table creation succeeds
+                Exception("Connection timeout")  # insert fails
+            ]
+            
+            test_obj = ExtractedObject(
+                metadata=Metadata(id="t1", user="test", collection="test", metadata=[]),
+                schema_name="test",
+                values={"id": "123"},
+                confidence=0.9,
+                source_span="Test"
+            )
+            
+            msg = MagicMock()
+            msg.value.return_value = test_obj
+            
+            # Should raise the exception
+            with pytest.raises(Exception, match="Connection timeout"):
+                await processor.on_object(msg, None, None)
+
+    @pytest.mark.asyncio
+    async def test_collection_partitioning(self, processor_with_mocks):
+        """Test that objects are properly partitioned by collection"""
+        processor, mock_cluster, mock_session = processor_with_mocks
+        
+        with patch('trustgraph.storage.objects.cassandra.write.Cluster', return_value=mock_cluster):
+            processor.schemas["data"] = RowSchema(
+                name="data",
+                fields=[Field(name="id", type="string", size=50, primary=True)]
+            )
+            
+            # Process objects from different collections
+            collections = ["import_jan", "import_feb", "import_mar"]
+            
+            for coll in collections:
+                obj = ExtractedObject(
+                    metadata=Metadata(id=f"{coll}-1", user="analytics", collection=coll, metadata=[]),
+                    schema_name="data",
+                    values={"id": f"ID-{coll}"},
+                    confidence=0.9,
+                    source_span="Data"
+                )
+                
+                msg = MagicMock()
+                msg.value.return_value = obj
+                await processor.on_object(msg, None, None)
+            
+            # Verify all inserts include collection in values
+            insert_calls = [call for call in mock_session.execute.call_args_list 
+                          if "INSERT INTO" in str(call)]
+            assert len(insert_calls) == 3
+            
+            # Check each insert has the correct collection
+            for i, call in enumerate(insert_calls):
+                values = call[0][1]
+                assert collections[i] in values

tests/integration/test_template_service_integration.py

@@ -0,0 +1,205 @@
+"""
+Simplified integration tests for Template Service
+
+These tests verify the basic functionality of the template service
+without the full message queue infrastructure.
+"""
+
+import pytest
+import json
+from unittest.mock import AsyncMock, MagicMock
+
+from trustgraph.schema import PromptRequest, PromptResponse
+from trustgraph.template.prompt_manager import PromptManager
+
+
+@pytest.mark.integration 
+class TestTemplateServiceSimple:
+    """Simplified integration tests for Template Service components"""
+
+    @pytest.fixture
+    def sample_config(self):
+        """Sample configuration for testing"""
+        return {
+            "system": json.dumps("You are a helpful assistant."),
+            "template-index": json.dumps(["greeting", "json_test"]),
+            "template.greeting": json.dumps({
+                "prompt": "Hello {{ name }}, welcome to {{ system_name }}!",
+                "response-type": "text"
+            }),
+            "template.json_test": json.dumps({
+                "prompt": "Generate profile for {{ username }}",
+                "response-type": "json",
+                "schema": {
+                    "type": "object",
+                    "properties": {
+                        "name": {"type": "string"},
+                        "role": {"type": "string"}
+                    },
+                    "required": ["name", "role"]
+                }
+            })
+        }
+
+    @pytest.fixture
+    def prompt_manager(self, sample_config):
+        """Create a configured PromptManager"""
+        pm = PromptManager()
+        pm.load_config(sample_config)
+        pm.terms["system_name"] = "TrustGraph"
+        return pm
+
+    @pytest.mark.asyncio
+    async def test_prompt_manager_text_invocation(self, prompt_manager):
+        """Test PromptManager text response invocation"""
+        # Mock LLM function
+        async def mock_llm(system, prompt):
+            assert system == "You are a helpful assistant."
+            assert "Hello Alice, welcome to TrustGraph!" in prompt
+            return "Welcome message processed!"
+
+        result = await prompt_manager.invoke("greeting", {"name": "Alice"}, mock_llm)
+        
+        assert result == "Welcome message processed!"
+
+    @pytest.mark.asyncio
+    async def test_prompt_manager_json_invocation(self, prompt_manager):
+        """Test PromptManager JSON response invocation"""
+        # Mock LLM function
+        async def mock_llm(system, prompt):
+            assert "Generate profile for johndoe" in prompt
+            return '{"name": "John Doe", "role": "user"}'
+
+        result = await prompt_manager.invoke("json_test", {"username": "johndoe"}, mock_llm)
+        
+        assert isinstance(result, dict)
+        assert result["name"] == "John Doe"
+        assert result["role"] == "user"
+
+    @pytest.mark.asyncio
+    async def test_prompt_manager_json_validation_error(self, prompt_manager):
+        """Test JSON schema validation failure"""
+        # Mock LLM function that returns invalid JSON
+        async def mock_llm(system, prompt):
+            return '{"name": "John Doe"}'  # Missing required "role"
+
+        with pytest.raises(RuntimeError) as exc_info:
+            await prompt_manager.invoke("json_test", {"username": "johndoe"}, mock_llm)
+        
+        assert "Schema validation fail" in str(exc_info.value)
+
+    @pytest.mark.asyncio
+    async def test_prompt_manager_json_parse_error(self, prompt_manager):
+        """Test JSON parsing failure"""
+        # Mock LLM function that returns non-JSON
+        async def mock_llm(system, prompt):
+            return "This is not JSON at all"
+
+        with pytest.raises(RuntimeError) as exc_info:
+            await prompt_manager.invoke("json_test", {"username": "johndoe"}, mock_llm)
+        
+        assert "JSON parse fail" in str(exc_info.value)
+
+    @pytest.mark.asyncio
+    async def test_prompt_manager_unknown_prompt(self, prompt_manager):
+        """Test unknown prompt ID handling"""
+        async def mock_llm(system, prompt):
+            return "Response"
+
+        with pytest.raises(KeyError):
+            await prompt_manager.invoke("unknown_prompt", {}, mock_llm)
+
+    @pytest.mark.asyncio
+    async def test_prompt_manager_term_merging(self, prompt_manager):
+        """Test proper term merging (global + prompt + input)"""
+        # Add prompt-specific terms
+        prompt_manager.prompts["greeting"].terms = {"greeting_prefix": "Hi"}
+        
+        async def mock_llm(system, prompt):
+            # Should have global term (system_name), input term (name), and any prompt terms
+            assert "TrustGraph" in prompt  # Global term
+            assert "Bob" in prompt  # Input term
+            return "Merged correctly"
+
+        result = await prompt_manager.invoke("greeting", {"name": "Bob"}, mock_llm)
+        assert result == "Merged correctly"
+
+    def test_prompt_manager_template_rendering(self, prompt_manager):
+        """Test direct template rendering"""
+        result = prompt_manager.render("greeting", {"name": "Charlie"})
+        
+        assert "Hello Charlie, welcome to TrustGraph!" == result.strip()
+
+    def test_prompt_manager_configuration_loading(self):
+        """Test configuration loading with various formats"""
+        pm = PromptManager()
+        
+        # Test empty configuration
+        pm.load_config({})
+        assert pm.config.system_template == "Be helpful."
+        assert len(pm.prompts) == 0
+        
+        # Test configuration with single prompt
+        config = {
+            "system": json.dumps("Test system"),
+            "template-index": json.dumps(["test"]),
+            "template.test": json.dumps({
+                "prompt": "Test {{ value }}",
+                "response-type": "text"
+            })
+        }
+        pm.load_config(config)
+        
+        assert pm.config.system_template == "Test system"
+        assert "test" in pm.prompts
+        assert pm.prompts["test"].response_type == "text"
+
+    @pytest.mark.asyncio
+    async def test_prompt_manager_json_with_markdown(self, prompt_manager):
+        """Test JSON extraction from markdown code blocks"""
+        async def mock_llm(system, prompt):
+            return '''
+            Here's the profile:
+            ```json
+            {"name": "Jane Smith", "role": "admin"}
+            ```
+            '''
+
+        result = await prompt_manager.invoke("json_test", {"username": "jane"}, mock_llm)
+        
+        assert isinstance(result, dict)
+        assert result["name"] == "Jane Smith"
+        assert result["role"] == "admin"
+
+    def test_prompt_manager_error_handling_in_templates(self, prompt_manager):
+        """Test error handling in template rendering"""
+        # Test with missing variable - ibis might handle this differently than Jinja2
+        try:
+            result = prompt_manager.render("greeting", {})  # Missing 'name'
+            # If no exception, check that result is still a string
+            assert isinstance(result, str)
+        except Exception as e:
+            # If exception is raised, that's also acceptable
+            assert "name" in str(e) or "undefined" in str(e).lower() or "variable" in str(e).lower()
+
+    @pytest.mark.asyncio
+    async def test_concurrent_prompt_invocations(self, prompt_manager):
+        """Test concurrent invocations"""
+        async def mock_llm(system, prompt):
+            # Extract name from prompt for response
+            if "Alice" in prompt:
+                return "Alice response"
+            elif "Bob" in prompt:
+                return "Bob response"
+            else:
+                return "Default response"
+
+        # Run concurrent invocations
+        import asyncio
+        results = await asyncio.gather(
+            prompt_manager.invoke("greeting", {"name": "Alice"}, mock_llm),
+            prompt_manager.invoke("greeting", {"name": "Bob"}, mock_llm),
+        )
+
+        assert "Alice response" in results
+        assert "Bob response" in results

tests/integration/test_text_completion_integration.py

@@ -0,0 +1,429 @@
+"""
+Integration tests for Text Completion Service (OpenAI)
+
+These tests verify the end-to-end functionality of the OpenAI text completion service,
+testing API connectivity, authentication, rate limiting, error handling, and token tracking.
+Following the TEST_STRATEGY.md approach for integration testing.
+"""
+
+import pytest
+import os
+from unittest.mock import AsyncMock, MagicMock, patch
+from openai import OpenAI, RateLimitError
+from openai.types.chat import ChatCompletion, ChatCompletionMessage
+from openai.types.chat.chat_completion import Choice
+from openai.types.completion_usage import CompletionUsage
+
+from trustgraph.model.text_completion.openai.llm import Processor
+from trustgraph.exceptions import TooManyRequests
+from trustgraph.base import LlmResult
+from trustgraph.schema import TextCompletionRequest, TextCompletionResponse, Error
+
+
+@pytest.mark.integration
+class TestTextCompletionIntegration:
+    """Integration tests for OpenAI text completion service coordination"""
+
+    @pytest.fixture
+    def mock_openai_client(self):
+        """Mock OpenAI client that returns realistic responses"""
+        client = MagicMock(spec=OpenAI)
+        
+        # Mock chat completion response
+        usage = CompletionUsage(prompt_tokens=50, completion_tokens=100, total_tokens=150)
+        message = ChatCompletionMessage(role="assistant", content="This is a test response from the AI model.")
+        choice = Choice(index=0, message=message, finish_reason="stop")
+        
+        completion = ChatCompletion(
+            id="chatcmpl-test123",
+            choices=[choice],
+            created=1234567890,
+            model="gpt-3.5-turbo",
+            object="chat.completion",
+            usage=usage
+        )
+        
+        client.chat.completions.create.return_value = completion
+        return client
+
+    @pytest.fixture
+    def processor_config(self):
+        """Configuration for processor testing"""
+        return {
+            "model": "gpt-3.5-turbo",
+            "temperature": 0.7,
+            "max_output": 1024,
+        }
+
+    @pytest.fixture
+    def text_completion_processor(self, processor_config):
+        """Create text completion processor with test configuration"""
+        # Create a minimal processor instance for testing generate_content
+        processor = MagicMock()
+        processor.model = processor_config["model"]
+        processor.temperature = processor_config["temperature"]
+        processor.max_output = processor_config["max_output"]
+        
+        # Add the actual generate_content method from Processor class
+        processor.generate_content = Processor.generate_content.__get__(processor, Processor)
+        
+        return processor
+
+    @pytest.mark.asyncio
+    async def test_text_completion_successful_generation(self, text_completion_processor, mock_openai_client):
+        """Test successful text completion generation"""
+        # Arrange
+        text_completion_processor.openai = mock_openai_client
+        system_prompt = "You are a helpful assistant."
+        user_prompt = "What is machine learning?"
+
+        # Act
+        result = await text_completion_processor.generate_content(system_prompt, user_prompt)
+
+        # Assert
+        assert isinstance(result, LlmResult)
+        assert result.text == "This is a test response from the AI model."
+        assert result.in_token == 50
+        assert result.out_token == 100
+        assert result.model == "gpt-3.5-turbo"
+
+        # Verify OpenAI API was called correctly
+        mock_openai_client.chat.completions.create.assert_called_once()
+        call_args = mock_openai_client.chat.completions.create.call_args
+        
+        assert call_args.kwargs['model'] == "gpt-3.5-turbo"
+        assert call_args.kwargs['temperature'] == 0.7
+        assert call_args.kwargs['max_tokens'] == 1024
+        assert len(call_args.kwargs['messages']) == 1
+        assert call_args.kwargs['messages'][0]['role'] == "user"
+        assert "You are a helpful assistant." in call_args.kwargs['messages'][0]['content'][0]['text']
+        assert "What is machine learning?" in call_args.kwargs['messages'][0]['content'][0]['text']
+
+    @pytest.mark.asyncio
+    async def test_text_completion_with_different_configurations(self, mock_openai_client):
+        """Test text completion with various configuration parameters"""
+        # Test different configurations
+        test_configs = [
+            {"model": "gpt-4", "temperature": 0.0, "max_output": 512},
+            {"model": "gpt-3.5-turbo", "temperature": 1.0, "max_output": 2048},
+            {"model": "gpt-4-turbo", "temperature": 0.5, "max_output": 4096}
+        ]
+
+        for config in test_configs:
+            # Arrange - Create minimal processor mock
+            processor = MagicMock()
+            processor.model = config['model']
+            processor.temperature = config['temperature']
+            processor.max_output = config['max_output']
+            processor.openai = mock_openai_client
+            
+            # Add the actual generate_content method
+            processor.generate_content = Processor.generate_content.__get__(processor, Processor)
+
+            # Act
+            result = await processor.generate_content("System prompt", "User prompt")
+
+            # Assert
+            assert isinstance(result, LlmResult)
+            assert result.text == "This is a test response from the AI model."
+            assert result.in_token == 50
+            assert result.out_token == 100
+            # Note: result.model comes from mock response, not processor config
+            
+            # Verify configuration was applied
+            call_args = mock_openai_client.chat.completions.create.call_args
+            assert call_args.kwargs['model'] == config['model']
+            assert call_args.kwargs['temperature'] == config['temperature']
+            assert call_args.kwargs['max_tokens'] == config['max_output']
+            
+            # Reset mock for next iteration
+            mock_openai_client.reset_mock()
+
+    @pytest.mark.asyncio
+    async def test_text_completion_rate_limit_handling(self, text_completion_processor, mock_openai_client):
+        """Test proper rate limit error handling"""
+        # Arrange
+        mock_openai_client.chat.completions.create.side_effect = RateLimitError(
+            "Rate limit exceeded", 
+            response=MagicMock(status_code=429),
+            body={}
+        )
+        text_completion_processor.openai = mock_openai_client
+
+        # Act & Assert
+        with pytest.raises(TooManyRequests):
+            await text_completion_processor.generate_content("System prompt", "User prompt")
+
+        # Verify OpenAI API was called
+        mock_openai_client.chat.completions.create.assert_called_once()
+
+    @pytest.mark.asyncio
+    async def test_text_completion_api_error_handling(self, text_completion_processor, mock_openai_client):
+        """Test handling of general API errors"""
+        # Arrange
+        mock_openai_client.chat.completions.create.side_effect = Exception("API connection failed")
+        text_completion_processor.openai = mock_openai_client
+
+        # Act & Assert
+        with pytest.raises(Exception) as exc_info:
+            await text_completion_processor.generate_content("System prompt", "User prompt")
+
+        assert "API connection failed" in str(exc_info.value)
+        mock_openai_client.chat.completions.create.assert_called_once()
+
+    @pytest.mark.asyncio
+    async def test_text_completion_token_tracking(self, text_completion_processor, mock_openai_client):
+        """Test accurate token counting and tracking"""
+        # Arrange - Different token counts for multiple requests
+        test_cases = [
+            (25, 75),   # Small request
+            (100, 200), # Medium request
+            (500, 1000) # Large request
+        ]
+
+        for input_tokens, output_tokens in test_cases:
+            # Update mock response with different token counts
+            usage = CompletionUsage(
+                prompt_tokens=input_tokens, 
+                completion_tokens=output_tokens, 
+                total_tokens=input_tokens + output_tokens
+            )
+            message = ChatCompletionMessage(role="assistant", content="Test response")
+            choice = Choice(index=0, message=message, finish_reason="stop")
+            
+            completion = ChatCompletion(
+                id="chatcmpl-test123",
+                choices=[choice],
+                created=1234567890,
+                model="gpt-3.5-turbo",
+                object="chat.completion",
+                usage=usage
+            )
+            
+            mock_openai_client.chat.completions.create.return_value = completion
+            text_completion_processor.openai = mock_openai_client
+
+            # Act
+            result = await text_completion_processor.generate_content("System", "Prompt")
+
+            # Assert
+            assert result.in_token == input_tokens
+            assert result.out_token == output_tokens
+            assert result.model == "gpt-3.5-turbo"
+
+            # Reset mock for next iteration
+            mock_openai_client.reset_mock()
+
+    @pytest.mark.asyncio
+    async def test_text_completion_prompt_construction(self, text_completion_processor, mock_openai_client):
+        """Test proper prompt construction with system and user prompts"""
+        # Arrange
+        text_completion_processor.openai = mock_openai_client
+        system_prompt = "You are an expert in artificial intelligence."
+        user_prompt = "Explain neural networks in simple terms."
+
+        # Act
+        result = await text_completion_processor.generate_content(system_prompt, user_prompt)
+
+        # Assert
+        call_args = mock_openai_client.chat.completions.create.call_args
+        sent_message = call_args.kwargs['messages'][0]['content'][0]['text']
+        
+        # Verify system and user prompts are combined correctly
+        assert system_prompt in sent_message
+        assert user_prompt in sent_message
+        assert sent_message.startswith(system_prompt)
+        assert user_prompt in sent_message
+
+    @pytest.mark.asyncio
+    async def test_text_completion_concurrent_requests(self, processor_config, mock_openai_client):
+        """Test handling of concurrent requests"""
+        # Arrange
+        processors = []
+        for i in range(5):
+            processor = MagicMock()
+            processor.model = processor_config["model"]
+            processor.temperature = processor_config["temperature"]
+            processor.max_output = processor_config["max_output"]
+            processor.openai = mock_openai_client
+            processor.generate_content = Processor.generate_content.__get__(processor, Processor)
+            processors.append(processor)
+
+        # Simulate multiple concurrent requests
+        tasks = []
+        for i, processor in enumerate(processors):
+            task = processor.generate_content(f"System {i}", f"Prompt {i}")
+            tasks.append(task)
+
+        # Act
+        import asyncio
+        results = await asyncio.gather(*tasks)
+
+        # Assert
+        assert len(results) == 5
+        for result in results:
+            assert isinstance(result, LlmResult)
+            assert result.text == "This is a test response from the AI model."
+            assert result.in_token == 50
+            assert result.out_token == 100
+
+        # Verify all requests were processed
+        assert mock_openai_client.chat.completions.create.call_count == 5
+
+    @pytest.mark.asyncio
+    async def test_text_completion_response_format_validation(self, text_completion_processor, mock_openai_client):
+        """Test response format and structure validation"""
+        # Arrange
+        text_completion_processor.openai = mock_openai_client
+
+        # Act
+        result = await text_completion_processor.generate_content("System", "Prompt")
+
+        # Assert
+        # Verify OpenAI API call parameters
+        call_args = mock_openai_client.chat.completions.create.call_args
+        assert call_args.kwargs['response_format'] == {"type": "text"}
+        assert call_args.kwargs['top_p'] == 1
+        assert call_args.kwargs['frequency_penalty'] == 0
+        assert call_args.kwargs['presence_penalty'] == 0
+
+        # Verify result structure
+        assert hasattr(result, 'text')
+        assert hasattr(result, 'in_token')
+        assert hasattr(result, 'out_token')
+        assert hasattr(result, 'model')
+
+    @pytest.mark.asyncio
+    async def test_text_completion_authentication_patterns(self):
+        """Test different authentication configurations"""
+        # Test missing API key first (this should fail early)
+        with pytest.raises(RuntimeError) as exc_info:
+            Processor(id="test-no-key", api_key=None)
+        assert "OpenAI API key not specified" in str(exc_info.value)
+
+        # Test authentication pattern by examining the initialization logic
+        # Since we can't fully instantiate due to taskgroup requirements,
+        # we'll test the authentication logic directly
+        from trustgraph.model.text_completion.openai.llm import default_api_key, default_base_url
+        
+        # Test default values
+        assert default_base_url == "https://api.openai.com/v1"
+        
+        # Test configuration parameters
+        test_configs = [
+            {"api_key": "test-key-1", "url": "https://api.openai.com/v1"},
+            {"api_key": "test-key-2", "url": "https://custom.openai.com/v1"},
+        ]
+        
+        for config in test_configs:
+            # We can't fully test instantiation due to taskgroup,
+            # but we can verify the authentication logic would work
+            assert config["api_key"] is not None
+            assert config["url"] is not None
+
+    @pytest.mark.asyncio
+    async def test_text_completion_error_propagation(self, text_completion_processor, mock_openai_client):
+        """Test error propagation through the service"""
+        # Test different error types
+        error_cases = [
+            (RateLimitError("Rate limit", response=MagicMock(status_code=429), body={}), TooManyRequests),
+            (Exception("Connection timeout"), Exception),
+            (ValueError("Invalid request"), ValueError),
+        ]
+
+        for error_input, expected_error in error_cases:
+            # Arrange
+            mock_openai_client.chat.completions.create.side_effect = error_input
+            text_completion_processor.openai = mock_openai_client
+
+            # Act & Assert
+            with pytest.raises(expected_error):
+                await text_completion_processor.generate_content("System", "Prompt")
+
+            # Reset mock for next iteration
+            mock_openai_client.reset_mock()
+
+    @pytest.mark.asyncio
+    async def test_text_completion_model_parameter_validation(self, mock_openai_client):
+        """Test that model parameters are correctly passed to OpenAI API"""
+        # Arrange
+        processor = MagicMock()
+        processor.model = "gpt-4"
+        processor.temperature = 0.8
+        processor.max_output = 2048
+        processor.openai = mock_openai_client
+        processor.generate_content = Processor.generate_content.__get__(processor, Processor)
+
+        # Act
+        await processor.generate_content("System prompt", "User prompt")
+
+        # Assert
+        call_args = mock_openai_client.chat.completions.create.call_args
+        assert call_args.kwargs['model'] == "gpt-4"
+        assert call_args.kwargs['temperature'] == 0.8
+        assert call_args.kwargs['max_tokens'] == 2048
+        assert call_args.kwargs['top_p'] == 1
+        assert call_args.kwargs['frequency_penalty'] == 0
+        assert call_args.kwargs['presence_penalty'] == 0
+
+    @pytest.mark.asyncio
+    @pytest.mark.slow
+    async def test_text_completion_performance_timing(self, text_completion_processor, mock_openai_client):
+        """Test performance timing for text completion"""
+        # Arrange
+        text_completion_processor.openai = mock_openai_client
+        
+        # Act
+        import time
+        start_time = time.time()
+        
+        result = await text_completion_processor.generate_content("System", "Prompt")
+        
+        end_time = time.time()
+        execution_time = end_time - start_time
+
+        # Assert
+        assert isinstance(result, LlmResult)
+        assert execution_time < 1.0  # Should complete quickly with mocked API
+        mock_openai_client.chat.completions.create.assert_called_once()
+
+    @pytest.mark.asyncio
+    async def test_text_completion_response_content_extraction(self, text_completion_processor, mock_openai_client):
+        """Test proper extraction of response content from OpenAI API"""
+        # Arrange
+        test_responses = [
+            "This is a simple response.",
+            "This is a multi-line response.\nWith multiple lines.\nAnd more content.",
+            "Response with special characters: @#$%^&*()_+-=[]{}|;':\",./<>?",
+            ""  # Empty response
+        ]
+
+        for test_content in test_responses:
+            # Update mock response
+            usage = CompletionUsage(prompt_tokens=10, completion_tokens=20, total_tokens=30)
+            message = ChatCompletionMessage(role="assistant", content=test_content)
+            choice = Choice(index=0, message=message, finish_reason="stop")
+            
+            completion = ChatCompletion(
+                id="chatcmpl-test123",
+                choices=[choice],
+                created=1234567890,
+                model="gpt-3.5-turbo",
+                object="chat.completion",
+                usage=usage
+            )
+            
+            mock_openai_client.chat.completions.create.return_value = completion
+            text_completion_processor.openai = mock_openai_client
+
+            # Act
+            result = await text_completion_processor.generate_content("System", "Prompt")
+
+            # Assert
+            assert result.text == test_content
+            assert result.in_token == 10
+            assert result.out_token == 20
+            assert result.model == "gpt-3.5-turbo"
+
+            # Reset mock for next iteration
+            mock_openai_client.reset_mock()

tests/pytest.ini

@@ -0,0 +1,22 @@
+[pytest]
+testpaths = tests
+python_paths = .
+python_files = test_*.py
+python_classes = Test*
+python_functions = test_*
+addopts = 
+    -v
+    --tb=short
+    --strict-markers
+    --disable-warnings
+    --cov=trustgraph
+    --cov-report=html
+    --cov-report=term-missing
+#    --cov-fail-under=80
+asyncio_mode = auto
+markers =
+    slow: marks tests as slow (deselect with '-m "not slow"')
+    integration: marks tests as integration tests
+    unit: marks tests as unit tests
+    contract: marks tests as contract tests (service interface validation)
+    vertexai: marks tests as vertex ai specific tests

tests/query

@@ -1,21 +0,0 @@
-#!/usr/bin/env python3
-
-from trustgraph.graph_rag import GraphRag
-import sys
-
-query = " ".join(sys.argv[1:])
-
-gr = GraphRag(
-    verbose=True,
-    pulsar_host="pulsar://localhost:6650",
-    pr_request_queue="non-persistent://tg/request/prompt",
-    pr_response_queue="non-persistent://tg/response/prompt-response",
-)
-
-if query == "":
-    query="""This knowledge graph describes the Space Shuttle disaster.
-Present 20 facts which are present in the knowledge graph."""
-
-resp = gr.query(query)
-print(resp)
-

tests/report-chunk-sizes

@@ -1,100 +0,0 @@
-#!/usr/bin/env python3
-
-"""
-Accepts entity/vector pairs and writes them to a Milvus store.
-"""
-
-from trustgraph.schema import Chunk
-from trustgraph.schema import chunk_ingest_queue
-from trustgraph.log_level import LogLevel
-from trustgraph.base import Consumer
-from threading import Thread, Lock
-import time
-
-module = "test-chunk-size"
-
-default_input_queue = chunk_ingest_queue
-default_subscriber = module
-default_store_uri = 'http://localhost:19530'
-
-class Processor(Consumer):
-
-    def __init__(self, **params):
-
-        input_queue = params.get("input_queue", default_input_queue)
-        subscriber = params.get("subscriber", default_subscriber)
-        width = params.get("width", 200)
-
-        super(Processor, self).__init__(
-            **params | {
-                "input_queue": input_queue,
-                "subscriber": subscriber,
-                "input_schema": Chunk,
-            }
-        )
-
-        self.sizes = {}
-        self.width = width
-        self.lock = Lock()
-
-        Thread(target=self.report).start()
-
-    def report(self):
-
-        while True:
-            time.sleep(1)
-
-            print()
-
-            with self.lock:
-                tot = 0
-                for i in range(0, 20000, self.width):
-                    k = (i, i + self.width)
-                    if k in self.sizes:
-                        print(f"{i:5d} ..{i+self.width:5d}: {self.sizes[k]}")
-                        tot += self.sizes[k]
-                print(f"{'Total':13s}: {tot}")
-
-                    
-                
-
-    def handle(self, msg):
-
-        v = msg.value()
-
-        chunk = v.chunk.decode("utf-8")
-
-        l = len(chunk)
-
-
-        low = int(l / self.width) * self.width
-        high = low + self.width
-        key = (low, high)
-
-        with self.lock:
-
-            if key not in self.sizes:
-                self.sizes[key] = 0
-
-            self.sizes[key] += 1
-
-    @staticmethod
-    def add_args(parser):
-
-        Consumer.add_args(
-            parser, default_input_queue, default_subscriber,
-        )
-
-        parser.add_argument(
-            '--width',
-            type=int,
-            default=200,
-            help=f'Histogram width (default: 200)',
-        )
-
-def run():
-
-    Processor.start(module, __doc__)
-
-run()
-

tests/requirements.txt

@@ -0,0 +1,9 @@
+pytest>=7.0.0
+pytest-asyncio>=0.21.0
+pytest-mock>=3.10.0
+pytest-cov>=4.0.0
+google-cloud-aiplatform>=1.25.0
+google-auth>=2.17.0
+google-api-core>=2.11.0
+pulsar-client>=3.0.0
+prometheus-client>=0.16.0

tests/test-agent

@@ -1,48 +0,0 @@
-#!/usr/bin/env python3
-
-import json
-import textwrap
-from trustgraph.clients.agent_client import AgentClient
-
-def wrap(text, width=75):
-
-    if text is None: text = "n/a"
-
-    out = textwrap.wrap(
-        text, width=width
-    )
-    return "\n".join(out)
-
-def output(text, prefix="> ", width=78):
-
-    out = textwrap.indent(
-        text, prefix=prefix
-    )
-    print(out)
-
-p = AgentClient(
-    pulsar_host="pulsar://pulsar:6650",
-    input_queue = "non-persistent://tg/request/agent:0000",
-    output_queue = "non-persistent://tg/response/agent:0000",
-)
-
-q = "How many cats does Mark have? Calculate that number raised to 0.4 power.  Is that number lower than the numeric part of the mission identifier of the Space Shuttle Challenger on its last mission?  If so, give me an apple pie recipe, otherwise return a poem about cheese."
-
-output(wrap(q), "\U00002753 ")
-print()
-
-def think(x):
-    output(wrap(x), "\U0001f914 ")
-    print()
-
-def observe(x):
-    output(wrap(x), "\U0001f4a1 ")
-    print()
-
-resp = p.request(
-    question=q, think=think, observe=observe,
-)
-
-output(resp, "\U0001f4ac ")
-print()
-

tests/test-config

@@ -1,2 +0,0 @@
-#!/usr/bin/env python3
-

tests/test-doc-embeddings

@@ -1,22 +0,0 @@
-#!/usr/bin/env python3
-
-import pulsar
-from trustgraph.clients.document_embeddings_client import DocumentEmbeddingsClient
-from trustgraph.clients.embeddings_client import EmbeddingsClient
-
-ec = EmbeddingsClient(pulsar_host="pulsar://localhost:6650")
-
-vectors = ec.request("What caused the space shuttle to explode?")
-
-print(vectors)
-
-llm = DocumentEmbeddingsClient(pulsar_host="pulsar://localhost:6650")
-
-limit=10
-
-resp = llm.request(vectors, limit)
-
-print("Response...")
-for val in resp:
-    print(val)
-

tests/test-doc-prompt

@@ -1,25 +0,0 @@
-#!/usr/bin/env python3
-
-import pulsar
-from trustgraph.clients.prompt_client import PromptClient
-
-p = PromptClient(pulsar_host="pulsar://localhost:6650")
-
-docs = [
-    "In our house there is a big cat and a small cat.",
-    "The small cat is black.",
-    "The big cat is called Fred.",
-    "The orange stripey cat is big.",
-    "The black cat pounces on the big cat.",
-    "The black cat is called Hope."
-]
-
-query="What is the name of the cat who pounces on Fred?  Provide a full explanation."
-
-resp = p.request_document_prompt(
-    query=query,
-    documents=docs,
-)
-
-print(resp)
-

tests/test-doc-rag

@@ -1,19 +0,0 @@
-#!/usr/bin/env python3
-
-import pulsar
-from trustgraph.clients.document_rag_client import DocumentRagClient
-
-rag = DocumentRagClient(
-    pulsar_host="pulsar://localhost:6650",
-    subscriber="test1",
-    input_queue = "non-persistent://tg/request/document-rag:default",
-    output_queue = "non-persistent://tg/response/document-rag:default",
-)
-
-query="""
-What was the cause of the space shuttle disaster?"""
-
-resp = rag.request(query)
-
-print(resp)
-

tests/test-embeddings

@@ -1,18 +0,0 @@
-#!/usr/bin/env python3
-
-import pulsar
-from trustgraph.clients.embeddings_client import EmbeddingsClient
-
-embed = EmbeddingsClient(
-    pulsar_host="pulsar://pulsar:6650",
-    input_queue="non-persistent://tg/request/embeddings:default",
-    output_queue="non-persistent://tg/response/embeddings:default",
-    subscriber="test1",
-)
-
-prompt="Write a funny limerick about a llama"
-
-resp = embed.request(prompt)
-
-print(resp)
-

tests/test-flow

@@ -1,92 +0,0 @@
-#!/usr/bin/env python3
-
-import requests
-
-url = "http://localhost:8088/"
-
-resp = requests.post(
-    f"{url}/api/v1/flow",
-    json={
-        "operation": "list-classes",
-    }
-)
-
-print(resp)
-print(resp.text)
-
-resp = requests.post(
-    f"{url}/api/v1/flow",
-    json={
-        "operation": "get-class",
-        "class-name": "default",
-    }
-)
-
-print(resp)
-print(resp.text)
-
-resp = requests.post(
-    f"{url}/api/v1/flow",
-    json={
-        "operation": "put-class",
-        "class-name": "bunch",
-        "class-definition": "{}",
-    }
-)
-
-print(resp)
-print(resp.text)
-
-resp = requests.post(
-    f"{url}/api/v1/flow",
-    json={
-        "operation": "get-class",
-        "class-name": "bunch",
-    }
-)
-
-print(resp)
-print(resp.text)
-
-resp = requests.post(
-    f"{url}/api/v1/flow",
-    json={
-        "operation": "list-classes",
-    }
-)
-
-print(resp)
-print(resp.text)
-
-
-resp = requests.post(
-    f"{url}/api/v1/flow",
-    json={
-        "operation": "delete-class",
-        "class-name": "bunch",
-    }
-)
-
-print(resp)
-print(resp.text)
-
-
-resp = requests.post(
-    f"{url}/api/v1/flow",
-    json={
-        "operation": "list-classes",
-    }
-)
-
-print(resp)
-print(resp.text)
-
-resp = requests.post(
-    f"{url}/api/v1/flow",
-    json={
-        "operation": "list-flows",
-    }
-)
-
-print(resp)
-print(resp.text)

tests/test-flow-get-class

@@ -1,19 +0,0 @@
-#!/usr/bin/env python3
-
-import requests
-
-url = "http://localhost:8088/"
-
-resp = requests.post(
-    f"{url}/api/v1/flow",
-    json={
-        "operation": "get-class",
-        "class-name": "default",
-    }
-)
-
-resp = resp.json()
-
-print(resp["class-definition"])
-
-

tests/test-flow-start-flow

@@ -1,23 +0,0 @@
-#!/usr/bin/env python3
-
-import requests
-import json
-
-url = "http://localhost:8088/"
-
-resp = requests.post(
-    f"{url}/api/v1/flow",
-    json={
-        "operation": "start-flow",
-        "flow-id": "0003",
-        "class-name": "default",
-    }
-)
-
-print(resp)
-print(resp.text)
-resp = resp.json()
-
-
-print(resp)
-

tests/test-flow-stop-flow

@@ -1,22 +0,0 @@
-#!/usr/bin/env python3
-
-import requests
-import json
-
-url = "http://localhost:8088/"
-
-resp = requests.post(
-    f"{url}/api/v1/flow",
-    json={
-        "operation": "stop-flow",
-        "flow-id": "0003",
-    }
-)
-
-print(resp)
-print(resp.text)
-resp = resp.json()
-
-
-print(resp)
-

tests/test-get-config

@@ -1,11 +0,0 @@
-#!/usr/bin/env python3
-
-import pulsar
-from trustgraph.clients.config_client import ConfigClient
-
-cli = ConfigClient(pulsar_host="pulsar://localhost:6650")
-
-resp = cli.request_config()
-
-print(resp)
-

tests/test-graph-embeddings

@@ -1,22 +0,0 @@
-#!/usr/bin/env python3
-
-import pulsar
-from trustgraph.clients.graph_embeddings_client import GraphEmbeddingsClient
-from trustgraph.clients.embeddings_client import EmbeddingsClient
-
-ec = EmbeddingsClient(pulsar_host="pulsar://localhost:6650")
-
-vectors = ec.request("What caused the space shuttle to explode?")
-
-print(vectors)
-
-llm = GraphEmbeddingsClient(pulsar_host="pulsar://localhost:6650")
-
-limit=10
-
-resp = llm.request(vectors, limit)
-
-print("Response...")
-for val in resp:
-    print(val.value)
-

tests/test-graph-rag

@@ -1,22 +0,0 @@
-#!/usr/bin/env python3
-
-import pulsar
-from trustgraph.clients.graph_rag_client import GraphRagClient
-
-rag = GraphRagClient(
-    pulsar_host="pulsar://localhost:6650",
-    subscriber="test1",
-    input_queue = "non-persistent://tg/request/graph-rag:default",
-    output_queue = "non-persistent://tg/response/graph-rag:default",
-)
-
-#query="""
-#This knowledge graph describes the Space Shuttle disaster.
-#Present 20 facts which are present in the knowledge graph."""
-
-query = "How many cats does Mark have?"
-
-resp = rag.request(query)
-
-print(resp)
-

tests/test-graph-rag2

@@ -1,14 +0,0 @@
-#!/usr/bin/env python3
-
-import pulsar
-from trustgraph.clients.graph_rag_client import GraphRagClient
-
-rag = GraphRagClient(pulsar_host="pulsar://localhost:6650")
-
-query="""List 20 key points to describe the research that led to the discovery of Leo VI.
-"""
-
-resp = rag.request(query)
-
-print(resp)
-

tests/test-lang-definition

@@ -1,24 +0,0 @@
-#!/usr/bin/env python3
-
-import pulsar
-from trustgraph.clients.prompt_client import PromptClient
-
-p = PromptClient(pulsar_host="pulsar://localhost:6650")
-
-chunk = """I noticed a cat in my garden.  It is a four-legged animal
-which is a mammal and can be tame or wild.  I wonder if it will be friends
-with me.  I think the cat's name is Fred and it has 4 legs.
-
-A cat is a small mammal.
-
-A grapefruit is a citrus fruit.
-
-"""
-
-resp = p.request_definitions(
-    chunk=chunk,
-)
-
-for d in resp:
-    print(d.name, ":", d.definition)
-

tests/test-lang-kg-prompt

@@ -1,72 +0,0 @@
-#!/usr/bin/env python3
-
-import pulsar
-from trustgraph.clients.prompt_client import PromptClient
-
-p = PromptClient(pulsar_host="pulsar://localhost:6650")
-
-facts = [
-      ("accident", "evoked", "a wide range of deeply felt public responses"),
-      ("Space Shuttle concept", "had", "genesis"),
-      ("Commission", "had", "a mandate to develop recommendations for corrective or other action based upon the Commission's findings and determinations"),
-      ("Commission", "established", "teams of persons"),
-      ("Space Shuttle Challenger", "http://www.w3.org/2004/02/skos/core#definition", "A space shuttle that was destroyed in an accident during mission 51-L."),
-      ("The mid fuselage", "contains", "the payload bay"),
-      ("Volume I", "contains", "Chapter IX"),
-      ("accident", "resulted in", "firm national resolve that those men and women be forever enshrined in the annals of American heroes"),
-      ("Volume I", "contains", "Chapter IV"),
-      ("Volume I", "contains", "Appendix A"),
-      ("Volume I", "contains", "Appendix B"),
-      ("Volume I", "contains", "The Staff"),
-      ("Commission", "required", "detailed investigation"),
-      ("Commission", "focused", "safety aspects of future flights"),
-      ("Commission", "http://www.w3.org/2004/02/skos/core#definition", "An independent group appointed to investigate the Space Shuttle Challenger accident."),
-      ("Commission", "moved forward with", "its investigation"),
-      ("President", "appointed", "an independent Commission"),
-      ("accident", "interrupted", "one of the most productive engineering, scientific and exploratory programs in history"),
-      ("Volume I", "contains", "Preface"),
-      ("Commission", "believes", "investigation"),
-      ("Volume I", "contains", "Chapter I"),
-      ("President", "was moved and troubled", "by this accident in a very personal way"),
-      ("PRESIDENTIAL COMMISSION", "Report to", "President"),
-      ("Volume I", "contains", "Chapter VI"),
-      ("Commission", "held", "public hearings dealing with the facts leading up to the accident"),
-      ("Volume I", "http://www.w3.org/2004/02/skos/core#definition", "The first volume of a multi-volume publication."),
-      ("Space Shuttle Challenger", "was involved in", "an accident"),
-      ("Volume I", "contains", "Chapter VII"),
-      ("Volume I", "contains", "Chapter II"),
-      ("Volume I", "contains", "Chapter V"),
-      ("Commission", "believes", "its investigation and report have been responsive to the request of the President and hopes that they will serve the best interests of the nation in restoring the United States space program to its preeminent position in the world"),
-      ("Commission", "supported", "panels"),
-      ("Volume I", "contains", "Chapter VIII"),
-      ("NASA", "cooperated", "Commission"),
-      ("liquid oxygen tank", "contains", "oxidizer"),
-      ("President", "http://www.w3.org/2004/02/skos/core#definition", "The head of state of the United States."),
-      ("Volume I", "contains", "Chapter III"),
-      ("Apollo lunar landing spacecraft", "had", "not yet flown"),
-      ("Commission", "construe", "mandate"),
-      ("accident", "became", "a milestone on the way to achieving the full potential that space offers to mankind"),
-      ("Volume I", "contains", "The Commission"),
-      ("Commission", "focused", "attention"),
-      ("Commission", "learned", "lessons"),
-      ("Commission", "required", "interfere with or supersede Congress"),
-      ("Commission", "was made up of", "persons not connected with the mission"),
-      ("Commission", "required", "review budgetary matters"),
-      ("Space Shuttle", "became", "focus of NASA's near-term future"),
-      ("Volume I", "contains", "Appendix C"),
-      ("accident", "caused", "grief and sadness for the loss of seven brave members of the crew"),
-      ("Commission", "http://www.w3.org/2004/02/skos/core#definition", "A group established to investigate the space shuttle accident"),
-      ("Volume I", "contains", "Appendix D"),
-      ("Commission", "had", "a mandate to review the circumstances surrounding the accident to establish the probable cause or causes of the accident"),
-      ("Volume I", "contains", "Recommendations")
-]
-
-query="Present 20 facts which are present in the knowledge graph."
-
-resp = p.request_kg_prompt(
-    query=query,
-    kg=facts,
-)
-
-print(resp)
-

tests/test-lang-relationships

@@ -1,21 +0,0 @@
-#!/usr/bin/env python3
-
-import pulsar
-from trustgraph.clients.prompt_client import PromptClient
-
-p = PromptClient(pulsar_host="pulsar://localhost:6650")
-
-chunk = """I noticed a cat in my garden.  It is a four-legged animal
-which is a mammal and can be tame or wild.  I wonder if it will be friends
-with me.  I think the cat's name is Fred and it has 4 legs"""
-
-resp = p.request_relationships(
-    chunk=chunk,
-)
-
-for d in resp:
-    print(d.s)
-    print("  ", d.p)
-    print("  ", d.o)
-    print("  ", d.o_entity)
-

tests/test-lang-topics

@@ -1,19 +0,0 @@
-#!/usr/bin/env python3
-
-import pulsar
-from trustgraph.clients.prompt_client import PromptClient
-
-p = PromptClient(pulsar_host="pulsar://localhost:6650")
-
-chunk = """I noticed a cat in my garden.  It is a four-legged animal
-which is a mammal and can be tame or wild.  I wonder if it will be friends
-with me.  I think the cat's name is Fred and it has 4 legs"""
-
-resp = p.request_topics(
-    chunk=chunk,
-)
-
-for d in resp:
-    print(d.topic)
-    print("  ", d.definition)
-

tests/test-llm

@@ -1,19 +0,0 @@
-#!/usr/bin/env python3
-
-import pulsar
-from trustgraph.clients.llm_client import LlmClient
-
-llm = LlmClient(
-    pulsar_host="pulsar://pulsar:6650",
-    input_queue="non-persistent://tg/request/text-completion:default",
-    output_queue="non-persistent://tg/response/text-completion:default",
-    subscriber="test1",
-)
-
-system = "You are a lovely assistant."
-prompt="what is 2 + 2 == 5"
-
-resp = llm.request(system, prompt)
-
-print(resp)
-

tests/test-llm2

@@ -1,15 +0,0 @@
-#!/usr/bin/env python3
-
-import pulsar
-from trustgraph.clients.llm_client import LlmClient
-
-llm = LlmClient(pulsar_host="pulsar://localhost:6650")
-
-prompt="What is 2 + 12?"
-
-try:
-    resp = llm.request(prompt)
-    print(resp)
-except Exception as e:
-    print(f"{e.__class__.__name__}: {e}")
-

tests/test-llm3

@@ -1,15 +0,0 @@
-#!/usr/bin/env python3
-
-import pulsar
-from trustgraph.clients.llm_client import LlmClient
-
-llm = LlmClient(pulsar_host="pulsar://localhost:6650")
-
-prompt="What is 2 + 12?"
-
-try:
-    resp = llm.request(prompt)
-    print(resp)
-except Exception as e:
-    print(f"{e.__class__.__name__}: {e}")
-

tests/test-load-pdf

@@ -1,36 +0,0 @@
-#!/usr/bin/env python3
-
-import pulsar
-from pulsar.schema import JsonSchema
-import base64
-
-from trustgraph.schema import Document, Metadata
-
-client = pulsar.Client("pulsar://localhost:6650", listener_name="localhost")
-
-prod = client.create_producer(
-    topic="persistent://tg/flow/document-load:0000",
-    schema=JsonSchema(Document),
-    chunking_enabled=True,
-)
-
-path = "../sources/Challenger-Report-Vol1.pdf"
-
-with open(path, "rb") as f:
-    blob = base64.b64encode(f.read()).decode("utf-8")
-
-message = Document(
-    metadata = Metadata(
-        id = "00001",
-        metadata = [],
-        user="trustgraph",
-        collection="default",
-    ),
-    data=blob
-)    
-
-prod.send(message)
-
-prod.close()
-client.close()
-

tests/test-load-text

@@ -1,37 +0,0 @@
-#!/usr/bin/env python3
-
-import pulsar
-from pulsar.schema import JsonSchema
-import base64
-
-from trustgraph.schema import TextDocument, Metadata
-
-client = pulsar.Client("pulsar://localhost:6650", listener_name="localhost")
-
-prod = client.create_producer(
-    topic="persistent://tg/flow/text-document-load:0000",
-    schema=JsonSchema(TextDocument),
-    chunking_enabled=True,
-)
-
-path = "../trustgraph/docs/README.cats"
-
-with open(path, "r") as f:
-#    blob = base64.b64encode(f.read()).decode("utf-8")
-    blob = f.read()
-
-message = TextDocument(
-    metadata = Metadata(
-        id = "00001",
-        metadata = [],
-        user="trustgraph",
-        collection="default",
-    ),
-    text=blob
-)    
-
-prod.send(message)
-
-prod.close()
-client.close()
-

tests/test-milvus

@@ -1,35 +0,0 @@
-#!/usr/bin/env python3
-
-from langchain_huggingface import HuggingFaceEmbeddings
-
-from trustgraph.direct.milvus import TripleVectors
-
-client = TripleVectors()
-
-embeddings = HuggingFaceEmbeddings(model_name="all-MiniLM-L6-v2")
-
-text="""A cat is a small animal.  A dog is a large animal.
-Cats say miaow.  Dogs go woof.
-"""
-
-embeds = embeddings.embed_documents([text])[0]
-
-text2="""If you couldn't download the model due to network issues, as a walkaround, you can use random vectors to represent the text and still finish the example. Just note that the search result won't reflect semantic similarity as the vectors are fake ones.
-"""
-
-embeds2 = embeddings.embed_documents([text2])[0]
-
-client.insert(embeds, "animals")
-client.insert(embeds, "vectors")
-
-query="""What noise does a cat make?"""
-
-qembeds = embeddings.embed_documents([query])[0]
-
-res = client.search(
-    qembeds,
-    limit=2
-)
-
-print(res)
-

tests/test-prompt-analyze

@@ -1,18 +0,0 @@
-#!/usr/bin/env python3
-
-import json
-from trustgraph.clients.prompt_client import PromptClient
-
-p = PromptClient(pulsar_host="pulsar://localhost:6650")
-
-description = """Fred is a 4-legged cat who is 12 years old"""
-
-resp = p.request(
-    id="analyze",
-    terms = {
-        "description": description,
-    }
-)
-
-print(json.dumps(resp, indent=4))
-

tests/test-prompt-extraction

@@ -1,51 +0,0 @@
-#!/usr/bin/env python3
-
-import json
-from trustgraph.clients.prompt_client import PromptClient
-
-p = PromptClient(
-    pulsar_host="pulsar://localhost:6650",
-    input_queue="non-persistent://tg/request/prompt:default",
-    output_queue="non-persistent://tg/response/prompt:default",
-    subscriber="test1",
-)
-
-chunk="""
- The Space Shuttle was a reusable spacecraft that transported astronauts and cargo to and from Earth's orbit. It was designed to launch like a rocket, maneuver in orbit like a spacecraft, and land like an airplane. The Space Shuttle was NASA's space transportation system and was used for many purposes, including: 
-
-    Carrying astronauts
-    The Space Shuttle could carry up to seven astronauts at a time. 
-
-Launching, recovering, and repairing satellites
-The Space Shuttle could launch satellites into orbit, recover them, and repair them. 
-Building the International Space Station
-The Space Shuttle carried large parts into space to build the International Space Station. 
-Conducting research
-Astronauts conducted experiments in the Space Shuttle, which was like a science lab in space. 
-
-The Space Shuttle was retired in 2011 after the Columbia accident in 2003. The Columbia Accident Investigation Board report found that the Space Shuttle was unsafe and expensive to make safe. 
-Here are some other facts about the Space Shuttle: 
-
-    The Space Shuttle was 184 ft tall and had a diameter of 29 ft. 
-
-The Space Shuttle had a mass of 4,480,000 lb. 
-The Space Shuttle's first flight was on April 12, 1981. 
-The Space Shuttle's last mission was in 2011. 
-"""
-
-q = "Tell me some facts in the knowledge graph"
-
-resp = p.request(
-    id="extract-definitions",
-    variables = {
-        "text": chunk,
-    }
-)
-
-print(resp)
-
-for fact in resp:
-    print(fact["entity"], "::")
-    print(fact["definition"])
-    print()
-

tests/test-prompt-french-question

@@ -1,18 +0,0 @@
-#!/usr/bin/env python3
-
-import pulsar
-from trustgraph.clients.prompt_client import PromptClient
-
-p = PromptClient(pulsar_host="pulsar://localhost:6650")
-
-question = """What is the square root of 16?"""
-
-resp = p.request(
-    id="french-question",
-    terms = {
-        "question": question
-    }
-)
-
-print(resp)
-

tests/test-prompt-knowledge

@@ -1,44 +0,0 @@
-#!/usr/bin/env python3
-
-import json
-from trustgraph.clients.prompt_client import PromptClient
-
-p = PromptClient(pulsar_host="pulsar://localhost:6650")
-
-knowledge = [
-      ("accident", "evoked", "a wide range of deeply felt public responses"),
-      ("Space Shuttle concept", "had", "genesis"),
-      ("Commission", "had", "a mandate to develop recommendations for corrective or other action based upon the Commission's findings and determinations"),
-      ("Commission", "established", "teams of persons"),
-      ("Space Shuttle Challenger", "http://www.w3.org/2004/02/skos/core#definition", "A space shuttle that was destroyed in an accident during mission 51-L."),
-      ("The mid fuselage", "contains", "the payload bay"),
-      ("Volume I", "contains", "Chapter IX"),
-      ("accident", "resulted in", "firm national resolve that those men and women be forever enshrined in the annals of American heroes"),
-      ("Volume I", "contains", "Chapter VII"),
-      ("Volume I", "contains", "Chapter II"),
-      ("Volume I", "contains", "Chapter V"),
-      ("Commission", "believes", "its investigation and report have been responsive to the request of the President and hopes that they will serve the best interests of the nation in restoring the United States space program to its preeminent position in the world"),
-      ("Commission", "construe", "mandate"),
-      ("accident", "became", "a milestone on the way to achieving the full potential that space offers to mankind"),
-      ("Volume I", "contains", "The Commission"),
-      ("Commission", "http://www.w3.org/2004/02/skos/core#definition", "A group established to investigate the space shuttle accident"),
-      ("Volume I", "contains", "Appendix D"),
-      ("Commission", "had", "a mandate to review the circumstances surrounding the accident to establish the probable cause or causes of the accident"),
-      ("Volume I", "contains", "Recommendations")
-]
-
-q = "Tell me some facts in the knowledge graph"
-
-resp = p.request(
-    id="graph-query",
-    terms = {
-        "name": "Jayney",
-        "knowledge": knowledge,
-        "question": q
-    }
-)
-
-print(resp)
-
-
-

tests/test-prompt-question

@@ -1,23 +0,0 @@
-#!/usr/bin/env python3
-
-import pulsar
-from trustgraph.clients.prompt_client import PromptClient
-
-p = PromptClient(
-    pulsar_host="pulsar://localhost:6650",
-    input_queue="non-persistent://tg/request/prompt:default",
-    output_queue="non-persistent://tg/response/prompt:default",
-    subscriber="test1",
-)
-
-question = """What is the square root of 16?"""
-
-resp = p.request(
-    id="question",
-    variables = {
-        "question": question
-    }
-)
-
-print(resp)
-

tests/test-prompt-spanish-question

@@ -1,19 +0,0 @@
-#!/usr/bin/env python3
-
-import pulsar
-from trustgraph.clients.prompt_client import PromptClient
-
-p = PromptClient(pulsar_host="pulsar://localhost:6650")
-
-question = """What is the square root of 16?"""
-
-resp = p.request(
-    id="question",
-    terms = {
-        "question": question,
-        "attitude": "Spanish-speaking bot"
-    }
-)
-
-print(resp)
-

tests/test-rows-prompt

@@ -1,51 +0,0 @@
-#!/usr/bin/env python3
-
-import pulsar
-from trustgraph.clients.prompt_client import PromptClient
-from trustgraph.objects.object import Schema
-from trustgraph.objects.field import Field, FieldType
-
-schema = Schema(
-    name="actors",
-    description="actors in this story",
-    fields=[
-        Field(
-            name="name", type=FieldType.STRING,
-            description="Name of the animal or person in the story"
-        ),
-        Field(
-            name="legs", type=FieldType.INT,
-            description="Number of legs of the animal or person"
-        ),
-        Field(
-            name="notes", type=FieldType.STRING,
-            description="Additional notes or observations about this animal or person"
-        ),
-    ]
-)
-
-chunk = """I noticed a cat in my garden.  It is a four-legged animal
-which is a mammal and can be tame or wild.  I wonder if it will be friends
-with me?  I think the cat's name is Fred and it has 4 legs.
-There is also a dog barking outside.  The dog has 4 legs also.
-The dog comes to my call when I shout "Come here, Bernard".
-
-I am also standing in the garden, my name is Steve and I have 2 legs.
-
-My friend Clifford is coming to visit shortly, he has 3 legs due to
-a freak accident at birth.
-"""
-
-p = PromptClient(pulsar_host="pulsar://localhost:6650")
-
-resp = p.request_rows(
-    schema=schema,
-    chunk=chunk,
-)
-
-for d in resp:
-    print(f"Name: {d['name']}")
-    print(f"  No. of legs: {d['legs']}")
-    print(f"  Notes: {d['notes']}")
-    print()
-

tests/test-run-extract-row

@@ -1,13 +0,0 @@
-
-scripts/object-extract-row \
-    -p pulsar://localhost:6650 \
-    --field 'name:string:100:pri:Name of the person in the story' \
-    --field 'job:string:100::Job title or role' \
-    --field 'date:string:20::Date entered into role if known' \
-    --field 'supervisor:string:100::Supervisor or manager of this person, if known' \
-    --field 'location:string:100::Main base or location of work, if known' \
-    --field 'notes:string:1000::Additional notes or observations about this animal or person' \
-    --no-metrics \
-    --name actors \
-    --description 'Relevant people'
-

tests/test-triples

@@ -1,72 +0,0 @@
-#!/usr/bin/env python3
-
-import pulsar
-from trustgraph.clients.triples_query_client import TriplesQueryClient
-
-tq = TriplesQueryClient(
-    pulsar_host="pulsar://localhost:6650",
-)
-
-e = "http://trustgraph.ai/e/shuttle"
-
-limit=3
-
-def dump(resp):
-    print("Response...")
-    for t in resp:
-        print(t.s.value, t.p.value, t.o.value)
-
-print("-- * ---------------------------")
-
-resp = tq.request(None, None, None, limit)
-dump(resp)
-
-print("-- s ---------------------------")
-
-resp = tq.request("http://trustgraph.ai/e/shuttle", None, None, limit)
-dump(resp)
-
-print("-- p ---------------------------")
-
-resp = tq.request(None, "http://trustgraph.ai/e/landed", None, limit)
-dump(resp)
-
-print("-- o ---------------------------")
-
-resp = tq.request(None, None, "President", limit)
-dump(resp)
-
-print("-- sp ---------------------------")
-
-resp = tq.request(
-    "http://trustgraph.ai/e/shuttle", "http://trustgraph.ai/e/landed", None,
-    limit
-)
-dump(resp)
-
-print("-- so ---------------------------")
-
-resp = tq.request(
-    "http://trustgraph.ai/e/shuttle", None, "the tower",
-    limit
-)
-dump(resp)
-
-print("-- po ---------------------------")
-
-resp = tq.request(
-    None, "http://trustgraph.ai/e/landed",
-    "on the concrete runway at Kennedy Space Center",
-    limit
-)
-dump(resp)
-
-print("-- spo ---------------------------")
-
-resp = tq.request(
-    "http://trustgraph.ai/e/shuttle", "http://trustgraph.ai/e/landed",
-    "on the concrete runway at Kennedy Space Center",
-    limit
-)
-dump(resp)
-

tests/unit/__init__.py

@@ -0,0 +1,3 @@
+"""
+Unit tests for TrustGraph services
+"""

tests/unit/test_agent/__init__.py

@@ -0,0 +1,10 @@
+"""
+Unit tests for agent processing and ReAct pattern logic
+
+Testing Strategy:
+- Mock external LLM calls and tool executions
+- Test core ReAct reasoning cycle logic (Think-Act-Observe)
+- Test tool selection and coordination algorithms
+- Test conversation state management and multi-turn reasoning
+- Test response synthesis and answer generation
+"""

tests/unit/test_agent/conftest.py

@@ -0,0 +1,209 @@
+"""
+Shared fixtures for agent unit tests
+"""
+
+import pytest
+from unittest.mock import Mock, AsyncMock
+
+
+# Mock agent schema classes for testing
+class AgentRequest:
+    def __init__(self, question, conversation_id=None):
+        self.question = question
+        self.conversation_id = conversation_id
+
+
+class AgentResponse:
+    def __init__(self, answer, conversation_id=None, steps=None):
+        self.answer = answer
+        self.conversation_id = conversation_id
+        self.steps = steps or []
+
+
+class AgentStep:
+    def __init__(self, step_type, content, tool_name=None, tool_result=None):
+        self.step_type = step_type  # "think", "act", "observe"
+        self.content = content
+        self.tool_name = tool_name
+        self.tool_result = tool_result
+
+
+@pytest.fixture
+def sample_agent_request():
+    """Sample agent request for testing"""
+    return AgentRequest(
+        question="What is the capital of France?",
+        conversation_id="conv-123"
+    )
+
+
+@pytest.fixture
+def sample_agent_response():
+    """Sample agent response for testing"""
+    steps = [
+        AgentStep("think", "I need to find information about France's capital"),
+        AgentStep("act", "search", tool_name="knowledge_search", tool_result="Paris is the capital of France"),
+        AgentStep("observe", "I found that Paris is the capital of France"),
+        AgentStep("think", "I can now provide a complete answer")
+    ]
+    
+    return AgentResponse(
+        answer="The capital of France is Paris.",
+        conversation_id="conv-123",
+        steps=steps
+    )
+
+
+@pytest.fixture
+def mock_llm_client():
+    """Mock LLM client for agent reasoning"""
+    mock = AsyncMock()
+    mock.generate.return_value = "I need to search for information about the capital of France."
+    return mock
+
+
+@pytest.fixture
+def mock_knowledge_search_tool():
+    """Mock knowledge search tool"""
+    def search_tool(query):
+        if "capital" in query.lower() and "france" in query.lower():
+            return "Paris is the capital and largest city of France."
+        return "No relevant information found."
+    
+    return search_tool
+
+
+@pytest.fixture
+def mock_graph_rag_tool():
+    """Mock graph RAG tool"""
+    def graph_rag_tool(query):
+        return {
+            "entities": ["France", "Paris"],
+            "relationships": [("Paris", "capital_of", "France")],
+            "context": "Paris is the capital city of France, located in northern France."
+        }
+    
+    return graph_rag_tool
+
+
+@pytest.fixture
+def mock_calculator_tool():
+    """Mock calculator tool"""
+    def calculator_tool(expression):
+        # Simple mock calculator
+        try:
+            # Very basic expression evaluation for testing
+            if "+" in expression:
+                parts = expression.split("+")
+                return str(sum(int(p.strip()) for p in parts))
+            elif "*" in expression:
+                parts = expression.split("*")
+                result = 1
+                for p in parts:
+                    result *= int(p.strip())
+                return str(result)
+            return str(eval(expression))  # Simplified for testing
+        except:
+            return "Error: Invalid expression"
+    
+    return calculator_tool
+
+
+@pytest.fixture
+def available_tools(mock_knowledge_search_tool, mock_graph_rag_tool, mock_calculator_tool):
+    """Available tools for agent testing"""
+    return {
+        "knowledge_search": {
+            "function": mock_knowledge_search_tool,
+            "description": "Search knowledge base for information",
+            "parameters": ["query"]
+        },
+        "graph_rag": {
+            "function": mock_graph_rag_tool,
+            "description": "Query knowledge graph with RAG",
+            "parameters": ["query"]
+        },
+        "calculator": {
+            "function": mock_calculator_tool,
+            "description": "Perform mathematical calculations",
+            "parameters": ["expression"]
+        }
+    }
+
+
+@pytest.fixture
+def sample_conversation_history():
+    """Sample conversation history for multi-turn testing"""
+    return [
+        {
+            "role": "user",
+            "content": "What is 2 + 2?",
+            "timestamp": "2024-01-01T10:00:00Z"
+        },
+        {
+            "role": "assistant", 
+            "content": "2 + 2 = 4",
+            "steps": [
+                {"step_type": "think", "content": "This is a simple arithmetic question"},
+                {"step_type": "act", "content": "calculator", "tool_name": "calculator", "tool_result": "4"},
+                {"step_type": "observe", "content": "The calculator returned 4"},
+                {"step_type": "think", "content": "I can provide the answer"}
+            ],
+            "timestamp": "2024-01-01T10:00:05Z"
+        },
+        {
+            "role": "user",
+            "content": "What about 3 + 3?",
+            "timestamp": "2024-01-01T10:01:00Z"
+        }
+    ]
+
+
+@pytest.fixture
+def react_prompts():
+    """ReAct prompting templates for testing"""
+    return {
+        "system_prompt": """You are a helpful AI assistant that uses the ReAct (Reasoning and Acting) pattern.
+
+For each question, follow this cycle:
+1. Think: Analyze the question and plan your approach
+2. Act: Use available tools to gather information 
+3. Observe: Review the tool results
+4. Repeat if needed, then provide final answer
+
+Available tools: {tools}
+
+Format your response as:
+Think: [your reasoning]
+Act: [tool_name: parameters]
+Observe: [analysis of results]
+Answer: [final response]""",
+
+        "think_prompt": "Think step by step about this question: {question}\nPrevious context: {context}",
+        
+        "act_prompt": "Based on your thinking, what tool should you use? Available tools: {tools}",
+        
+        "observe_prompt": "You used {tool_name} and got result: {tool_result}\nHow does this help answer the question?",
+        
+        "synthesize_prompt": "Based on all your steps, provide a complete answer to: {question}"
+    }
+
+
+@pytest.fixture
+def mock_agent_processor():
+    """Mock agent processor for testing"""
+    class MockAgentProcessor:
+        def __init__(self, llm_client=None, tools=None):
+            self.llm_client = llm_client
+            self.tools = tools or {}
+            self.conversation_history = {}
+        
+        async def process_request(self, request):
+            # Mock processing logic
+            return AgentResponse(
+                answer="Mock response",
+                conversation_id=request.conversation_id,
+                steps=[]
+            )
+    
+    return MockAgentProcessor

tests/unit/test_agent/test_conversation_state.py

@@ -0,0 +1,596 @@
+"""
+Unit tests for conversation state management
+
+Tests the core business logic for managing conversation state,
+including history tracking, context preservation, and multi-turn
+reasoning support.
+"""
+
+import pytest
+from unittest.mock import Mock
+from datetime import datetime, timedelta
+import json
+
+
+class TestConversationStateLogic:
+    """Test cases for conversation state management business logic"""
+
+    def test_conversation_initialization(self):
+        """Test initialization of new conversation state"""
+        # Arrange
+        class ConversationState:
+            def __init__(self, conversation_id=None, user_id=None):
+                self.conversation_id = conversation_id or f"conv_{datetime.now().strftime('%Y%m%d_%H%M%S')}"
+                self.user_id = user_id
+                self.created_at = datetime.now()
+                self.updated_at = datetime.now()
+                self.turns = []
+                self.context = {}
+                self.metadata = {}
+                self.is_active = True
+            
+            def to_dict(self):
+                return {
+                    "conversation_id": self.conversation_id,
+                    "user_id": self.user_id,
+                    "created_at": self.created_at.isoformat(),
+                    "updated_at": self.updated_at.isoformat(),
+                    "turns": self.turns,
+                    "context": self.context,
+                    "metadata": self.metadata,
+                    "is_active": self.is_active
+                }
+        
+        # Act
+        conv1 = ConversationState(user_id="user123")
+        conv2 = ConversationState(conversation_id="custom_conv_id", user_id="user456")
+        
+        # Assert
+        assert conv1.conversation_id.startswith("conv_")
+        assert conv1.user_id == "user123"
+        assert conv1.is_active is True
+        assert len(conv1.turns) == 0
+        assert isinstance(conv1.created_at, datetime)
+        
+        assert conv2.conversation_id == "custom_conv_id"
+        assert conv2.user_id == "user456"
+        
+        # Test serialization
+        conv_dict = conv1.to_dict()
+        assert "conversation_id" in conv_dict
+        assert "created_at" in conv_dict
+        assert isinstance(conv_dict["turns"], list)
+
+    def test_turn_management(self):
+        """Test adding and managing conversation turns"""
+        # Arrange
+        class ConversationState:
+            def __init__(self, conversation_id=None, user_id=None):
+                self.conversation_id = conversation_id or f"conv_{datetime.now().strftime('%Y%m%d_%H%M%S')}"
+                self.user_id = user_id
+                self.created_at = datetime.now()
+                self.updated_at = datetime.now()
+                self.turns = []
+                self.context = {}
+                self.metadata = {}
+                self.is_active = True
+            
+            def to_dict(self):
+                return {
+                    "conversation_id": self.conversation_id,
+                    "user_id": self.user_id,
+                    "created_at": self.created_at.isoformat(),
+                    "updated_at": self.updated_at.isoformat(),
+                    "turns": self.turns,
+                    "context": self.context,
+                    "metadata": self.metadata,
+                    "is_active": self.is_active
+                }
+        
+        class ConversationTurn:
+            def __init__(self, role, content, timestamp=None, metadata=None):
+                self.role = role  # "user" or "assistant"
+                self.content = content
+                self.timestamp = timestamp or datetime.now()
+                self.metadata = metadata or {}
+            
+            def to_dict(self):
+                return {
+                    "role": self.role,
+                    "content": self.content,
+                    "timestamp": self.timestamp.isoformat(),
+                    "metadata": self.metadata
+                }
+        
+        class ConversationManager:
+            def __init__(self):
+                self.conversations = {}
+            
+            def add_turn(self, conversation_id, role, content, metadata=None):
+                if conversation_id not in self.conversations:
+                    return False, "Conversation not found"
+                
+                turn = ConversationTurn(role, content, metadata=metadata)
+                self.conversations[conversation_id].turns.append(turn)
+                self.conversations[conversation_id].updated_at = datetime.now()
+                
+                return True, turn
+            
+            def get_recent_turns(self, conversation_id, limit=10):
+                if conversation_id not in self.conversations:
+                    return []
+                
+                turns = self.conversations[conversation_id].turns
+                return turns[-limit:] if len(turns) > limit else turns
+            
+            def get_turn_count(self, conversation_id):
+                if conversation_id not in self.conversations:
+                    return 0
+                return len(self.conversations[conversation_id].turns)
+        
+        # Act
+        manager = ConversationManager()
+        conv_id = "test_conv"
+        
+        # Create conversation - use the local ConversationState class
+        conv_state = ConversationState(conv_id)
+        manager.conversations[conv_id] = conv_state
+        
+        # Add turns
+        success1, turn1 = manager.add_turn(conv_id, "user", "Hello, what is 2+2?")
+        success2, turn2 = manager.add_turn(conv_id, "assistant", "2+2 equals 4.")
+        success3, turn3 = manager.add_turn(conv_id, "user", "What about 3+3?")
+        
+        # Assert
+        assert success1 is True
+        assert turn1.role == "user"
+        assert turn1.content == "Hello, what is 2+2?"
+        
+        assert manager.get_turn_count(conv_id) == 3
+        
+        recent_turns = manager.get_recent_turns(conv_id, limit=2)
+        assert len(recent_turns) == 2
+        assert recent_turns[0].role == "assistant"
+        assert recent_turns[1].role == "user"
+
+    def test_context_preservation(self):
+        """Test preservation and retrieval of conversation context"""
+        # Arrange
+        class ContextManager:
+            def __init__(self):
+                self.contexts = {}
+            
+            def set_context(self, conversation_id, key, value, ttl_minutes=None):
+                """Set context value with optional TTL"""
+                if conversation_id not in self.contexts:
+                    self.contexts[conversation_id] = {}
+                
+                context_entry = {
+                    "value": value,
+                    "created_at": datetime.now(),
+                    "ttl_minutes": ttl_minutes
+                }
+                
+                self.contexts[conversation_id][key] = context_entry
+            
+            def get_context(self, conversation_id, key, default=None):
+                """Get context value, respecting TTL"""
+                if conversation_id not in self.contexts:
+                    return default
+                
+                if key not in self.contexts[conversation_id]:
+                    return default
+                
+                entry = self.contexts[conversation_id][key]
+                
+                # Check TTL
+                if entry["ttl_minutes"]:
+                    age = datetime.now() - entry["created_at"]
+                    if age > timedelta(minutes=entry["ttl_minutes"]):
+                        # Expired
+                        del self.contexts[conversation_id][key]
+                        return default
+                
+                return entry["value"]
+            
+            def update_context(self, conversation_id, updates):
+                """Update multiple context values"""
+                for key, value in updates.items():
+                    self.set_context(conversation_id, key, value)
+            
+            def clear_context(self, conversation_id, keys=None):
+                """Clear specific keys or entire context"""
+                if conversation_id not in self.contexts:
+                    return
+                
+                if keys is None:
+                    # Clear all context
+                    self.contexts[conversation_id] = {}
+                else:
+                    # Clear specific keys
+                    for key in keys:
+                        self.contexts[conversation_id].pop(key, None)
+            
+            def get_all_context(self, conversation_id):
+                """Get all context for conversation"""
+                if conversation_id not in self.contexts:
+                    return {}
+                
+                # Filter out expired entries
+                valid_context = {}
+                for key, entry in self.contexts[conversation_id].items():
+                    if entry["ttl_minutes"]:
+                        age = datetime.now() - entry["created_at"]
+                        if age <= timedelta(minutes=entry["ttl_minutes"]):
+                            valid_context[key] = entry["value"]
+                    else:
+                        valid_context[key] = entry["value"]
+                
+                return valid_context
+        
+        # Act
+        context_manager = ContextManager()
+        conv_id = "test_conv"
+        
+        # Set various context values
+        context_manager.set_context(conv_id, "user_name", "Alice")
+        context_manager.set_context(conv_id, "topic", "mathematics")
+        context_manager.set_context(conv_id, "temp_calculation", "2+2=4", ttl_minutes=1)
+        
+        # Assert
+        assert context_manager.get_context(conv_id, "user_name") == "Alice"
+        assert context_manager.get_context(conv_id, "topic") == "mathematics"
+        assert context_manager.get_context(conv_id, "temp_calculation") == "2+2=4"
+        assert context_manager.get_context(conv_id, "nonexistent", "default") == "default"
+        
+        # Test bulk updates
+        context_manager.update_context(conv_id, {
+            "calculation_count": 1,
+            "last_operation": "addition"
+        })
+        
+        all_context = context_manager.get_all_context(conv_id)
+        assert "calculation_count" in all_context
+        assert "last_operation" in all_context
+        assert len(all_context) == 5
+        
+        # Test clearing specific keys
+        context_manager.clear_context(conv_id, ["temp_calculation"])
+        assert context_manager.get_context(conv_id, "temp_calculation") is None
+        assert context_manager.get_context(conv_id, "user_name") == "Alice"
+
+    def test_multi_turn_reasoning_state(self):
+        """Test state management for multi-turn reasoning"""
+        # Arrange
+        class ReasoningStateManager:
+            def __init__(self):
+                self.reasoning_states = {}
+            
+            def start_reasoning_session(self, conversation_id, question, reasoning_type="sequential"):
+                """Start a new reasoning session"""
+                session_id = f"{conversation_id}_reasoning_{datetime.now().strftime('%H%M%S')}"
+                
+                self.reasoning_states[session_id] = {
+                    "conversation_id": conversation_id,
+                    "original_question": question,
+                    "reasoning_type": reasoning_type,
+                    "status": "active",
+                    "steps": [],
+                    "intermediate_results": {},
+                    "final_answer": None,
+                    "created_at": datetime.now(),
+                    "updated_at": datetime.now()
+                }
+                
+                return session_id
+            
+            def add_reasoning_step(self, session_id, step_type, content, tool_result=None):
+                """Add a step to reasoning session"""
+                if session_id not in self.reasoning_states:
+                    return False
+                
+                step = {
+                    "step_number": len(self.reasoning_states[session_id]["steps"]) + 1,
+                    "step_type": step_type,  # "think", "act", "observe"
+                    "content": content,
+                    "tool_result": tool_result,
+                    "timestamp": datetime.now()
+                }
+                
+                self.reasoning_states[session_id]["steps"].append(step)
+                self.reasoning_states[session_id]["updated_at"] = datetime.now()
+                
+                return True
+            
+            def set_intermediate_result(self, session_id, key, value):
+                """Store intermediate result for later use"""
+                if session_id not in self.reasoning_states:
+                    return False
+                
+                self.reasoning_states[session_id]["intermediate_results"][key] = value
+                return True
+            
+            def get_intermediate_result(self, session_id, key):
+                """Retrieve intermediate result"""
+                if session_id not in self.reasoning_states:
+                    return None
+                
+                return self.reasoning_states[session_id]["intermediate_results"].get(key)
+            
+            def complete_reasoning_session(self, session_id, final_answer):
+                """Mark reasoning session as complete"""
+                if session_id not in self.reasoning_states:
+                    return False
+                
+                self.reasoning_states[session_id]["final_answer"] = final_answer
+                self.reasoning_states[session_id]["status"] = "completed"
+                self.reasoning_states[session_id]["updated_at"] = datetime.now()
+                
+                return True
+            
+            def get_reasoning_summary(self, session_id):
+                """Get summary of reasoning session"""
+                if session_id not in self.reasoning_states:
+                    return None
+                
+                state = self.reasoning_states[session_id]
+                return {
+                    "original_question": state["original_question"],
+                    "step_count": len(state["steps"]),
+                    "status": state["status"],
+                    "final_answer": state["final_answer"],
+                    "reasoning_chain": [step["content"] for step in state["steps"] if step["step_type"] == "think"]
+                }
+        
+        # Act
+        reasoning_manager = ReasoningStateManager()
+        conv_id = "test_conv"
+        
+        # Start reasoning session
+        session_id = reasoning_manager.start_reasoning_session(
+            conv_id, 
+            "What is the population of the capital of France?"
+        )
+        
+        # Add reasoning steps
+        reasoning_manager.add_reasoning_step(session_id, "think", "I need to find the capital first")
+        reasoning_manager.add_reasoning_step(session_id, "act", "search for capital of France", "Paris")
+        reasoning_manager.set_intermediate_result(session_id, "capital", "Paris")
+        
+        reasoning_manager.add_reasoning_step(session_id, "observe", "Found that Paris is the capital")
+        reasoning_manager.add_reasoning_step(session_id, "think", "Now I need to find Paris population")
+        reasoning_manager.add_reasoning_step(session_id, "act", "search for Paris population", "2.1 million")
+        
+        reasoning_manager.complete_reasoning_session(session_id, "The population of Paris is approximately 2.1 million")
+        
+        # Assert
+        assert session_id.startswith(f"{conv_id}_reasoning_")
+        
+        capital = reasoning_manager.get_intermediate_result(session_id, "capital")
+        assert capital == "Paris"
+        
+        summary = reasoning_manager.get_reasoning_summary(session_id)
+        assert summary["original_question"] == "What is the population of the capital of France?"
+        assert summary["step_count"] == 5
+        assert summary["status"] == "completed"
+        assert "2.1 million" in summary["final_answer"]
+        assert len(summary["reasoning_chain"]) == 2  # Two "think" steps
+
+    def test_conversation_memory_management(self):
+        """Test memory management for long conversations"""
+        # Arrange
+        class ConversationMemoryManager:
+            def __init__(self, max_turns=100, max_context_age_hours=24):
+                self.max_turns = max_turns
+                self.max_context_age_hours = max_context_age_hours
+                self.conversations = {}
+            
+            def add_conversation_turn(self, conversation_id, role, content, metadata=None):
+                """Add turn with automatic memory management"""
+                if conversation_id not in self.conversations:
+                    self.conversations[conversation_id] = {
+                        "turns": [],
+                        "context": {},
+                        "created_at": datetime.now()
+                    }
+                
+                turn = {
+                    "role": role,
+                    "content": content,
+                    "timestamp": datetime.now(),
+                    "metadata": metadata or {}
+                }
+                
+                self.conversations[conversation_id]["turns"].append(turn)
+                
+                # Apply memory management
+                self._manage_memory(conversation_id)
+            
+            def _manage_memory(self, conversation_id):
+                """Apply memory management policies"""
+                conv = self.conversations[conversation_id]
+                
+                # Limit turn count
+                if len(conv["turns"]) > self.max_turns:
+                    # Keep recent turns and important summary turns
+                    turns_to_keep = self.max_turns // 2
+                    important_turns = self._identify_important_turns(conv["turns"])
+                    recent_turns = conv["turns"][-turns_to_keep:]
+                    
+                    # Combine important and recent turns, avoiding duplicates
+                    kept_turns = []
+                    seen_indices = set()
+                    
+                    # Add important turns first
+                    for turn_index, turn in important_turns:
+                        if turn_index not in seen_indices:
+                            kept_turns.append(turn)
+                            seen_indices.add(turn_index)
+                    
+                    # Add recent turns
+                    for i, turn in enumerate(recent_turns):
+                        original_index = len(conv["turns"]) - len(recent_turns) + i
+                        if original_index not in seen_indices:
+                            kept_turns.append(turn)
+                    
+                    conv["turns"] = kept_turns[-self.max_turns:]  # Final limit
+                
+                # Clean old context
+                self._clean_old_context(conversation_id)
+            
+            def _identify_important_turns(self, turns):
+                """Identify important turns to preserve"""
+                important = []
+                
+                for i, turn in enumerate(turns):
+                    # Keep turns with high information content
+                    if (len(turn["content"]) > 100 or 
+                        any(keyword in turn["content"].lower() for keyword in ["calculate", "result", "answer", "conclusion"])):
+                        important.append((i, turn))
+                
+                return important[:10]  # Limit important turns
+            
+            def _clean_old_context(self, conversation_id):
+                """Remove old context entries"""
+                if conversation_id not in self.conversations:
+                    return
+                
+                cutoff_time = datetime.now() - timedelta(hours=self.max_context_age_hours)
+                context = self.conversations[conversation_id]["context"]
+                
+                keys_to_remove = []
+                for key, entry in context.items():
+                    if isinstance(entry, dict) and "timestamp" in entry:
+                        if entry["timestamp"] < cutoff_time:
+                            keys_to_remove.append(key)
+                
+                for key in keys_to_remove:
+                    del context[key]
+            
+            def get_conversation_summary(self, conversation_id):
+                """Get summary of conversation state"""
+                if conversation_id not in self.conversations:
+                    return None
+                
+                conv = self.conversations[conversation_id]
+                return {
+                    "turn_count": len(conv["turns"]),
+                    "context_keys": list(conv["context"].keys()),
+                    "age_hours": (datetime.now() - conv["created_at"]).total_seconds() / 3600,
+                    "last_activity": conv["turns"][-1]["timestamp"] if conv["turns"] else None
+                }
+        
+        # Act
+        memory_manager = ConversationMemoryManager(max_turns=5, max_context_age_hours=1)
+        conv_id = "test_memory_conv"
+        
+        # Add many turns to test memory management
+        for i in range(10):
+            memory_manager.add_conversation_turn(
+                conv_id, 
+                "user" if i % 2 == 0 else "assistant",
+                f"Turn {i}: {'Important calculation result' if i == 5 else 'Regular content'}"
+            )
+        
+        # Assert
+        summary = memory_manager.get_conversation_summary(conv_id)
+        assert summary["turn_count"] <= 5  # Should be limited
+        
+        # Check that important turns are preserved
+        turns = memory_manager.conversations[conv_id]["turns"]
+        important_preserved = any("Important calculation" in turn["content"] for turn in turns)
+        assert important_preserved, "Important turns should be preserved"
+
+    def test_conversation_state_persistence(self):
+        """Test serialization and deserialization of conversation state"""
+        # Arrange
+        class ConversationStatePersistence:
+            def __init__(self):
+                pass
+            
+            def serialize_conversation(self, conversation_state):
+                """Serialize conversation state to JSON-compatible format"""
+                def datetime_serializer(obj):
+                    if isinstance(obj, datetime):
+                        return obj.isoformat()
+                    raise TypeError(f"Object of type {type(obj)} is not JSON serializable")
+                
+                return json.dumps(conversation_state, default=datetime_serializer, indent=2)
+            
+            def deserialize_conversation(self, serialized_data):
+                """Deserialize conversation state from JSON"""
+                def datetime_deserializer(data):
+                    """Convert ISO datetime strings back to datetime objects"""
+                    if isinstance(data, dict):
+                        for key, value in data.items():
+                            if isinstance(value, str) and self._is_iso_datetime(value):
+                                data[key] = datetime.fromisoformat(value)
+                            elif isinstance(value, (dict, list)):
+                                data[key] = datetime_deserializer(value)
+                    elif isinstance(data, list):
+                        for i, item in enumerate(data):
+                            data[i] = datetime_deserializer(item)
+                    
+                    return data
+                
+                parsed_data = json.loads(serialized_data)
+                return datetime_deserializer(parsed_data)
+            
+            def _is_iso_datetime(self, value):
+                """Check if string is ISO datetime format"""
+                try:
+                    datetime.fromisoformat(value.replace('Z', '+00:00'))
+                    return True
+                except (ValueError, AttributeError):
+                    return False
+        
+        # Create sample conversation state
+        conversation_state = {
+            "conversation_id": "test_conv_123",
+            "user_id": "user456",
+            "created_at": datetime.now(),
+            "updated_at": datetime.now(),
+            "turns": [
+                {
+                    "role": "user",
+                    "content": "Hello",
+                    "timestamp": datetime.now(),
+                    "metadata": {}
+                },
+                {
+                    "role": "assistant", 
+                    "content": "Hi there!",
+                    "timestamp": datetime.now(),
+                    "metadata": {"confidence": 0.9}
+                }
+            ],
+            "context": {
+                "user_preference": "detailed_answers",
+                "topic": "general"
+            },
+            "metadata": {
+                "platform": "web",
+                "session_start": datetime.now()
+            }
+        }
+        
+        # Act
+        persistence = ConversationStatePersistence()
+        
+        # Serialize
+        serialized = persistence.serialize_conversation(conversation_state)
+        assert isinstance(serialized, str)
+        assert "test_conv_123" in serialized
+        
+        # Deserialize
+        deserialized = persistence.deserialize_conversation(serialized)
+        
+        # Assert
+        assert deserialized["conversation_id"] == "test_conv_123"
+        assert deserialized["user_id"] == "user456"
+        assert isinstance(deserialized["created_at"], datetime)
+        assert len(deserialized["turns"]) == 2
+        assert deserialized["turns"][0]["role"] == "user"
+        assert isinstance(deserialized["turns"][0]["timestamp"], datetime)
+        assert deserialized["context"]["topic"] == "general"
+        assert deserialized["metadata"]["platform"] == "web"

tests/unit/test_agent/test_react_processor.py

@@ -0,0 +1,477 @@
+"""
+Unit tests for ReAct processor logic
+
+Tests the core business logic for the ReAct (Reasoning and Acting) pattern
+without relying on external LLM services, focusing on the Think-Act-Observe
+cycle and tool coordination.
+"""
+
+import pytest
+from unittest.mock import Mock, AsyncMock, patch
+import re
+
+
+class TestReActProcessorLogic:
+    """Test cases for ReAct processor business logic"""
+
+    def test_react_cycle_parsing(self):
+        """Test parsing of ReAct cycle components from LLM output"""
+        # Arrange
+        llm_output = """Think: I need to find information about the capital of France.
+Act: knowledge_search: capital of France
+Observe: The search returned that Paris is the capital of France.
+Think: I now have enough information to answer.
+Answer: The capital of France is Paris."""
+        
+        def parse_react_output(text):
+            """Parse ReAct format output into structured steps"""
+            steps = []
+            lines = text.strip().split('\n')
+            
+            for line in lines:
+                line = line.strip()
+                if line.startswith('Think:'):
+                    steps.append({
+                        'type': 'think',
+                        'content': line[6:].strip()
+                    })
+                elif line.startswith('Act:'):
+                    act_content = line[4:].strip()
+                    # Parse "tool_name: parameters" format
+                    if ':' in act_content:
+                        tool_name, params = act_content.split(':', 1)
+                        steps.append({
+                            'type': 'act',
+                            'tool_name': tool_name.strip(),
+                            'parameters': params.strip()
+                        })
+                    else:
+                        steps.append({
+                            'type': 'act',
+                            'content': act_content
+                        })
+                elif line.startswith('Observe:'):
+                    steps.append({
+                        'type': 'observe',
+                        'content': line[8:].strip()
+                    })
+                elif line.startswith('Answer:'):
+                    steps.append({
+                        'type': 'answer',
+                        'content': line[7:].strip()
+                    })
+            
+            return steps
+        
+        # Act
+        steps = parse_react_output(llm_output)
+        
+        # Assert
+        assert len(steps) == 5
+        assert steps[0]['type'] == 'think'
+        assert steps[1]['type'] == 'act'
+        assert steps[1]['tool_name'] == 'knowledge_search'
+        assert steps[1]['parameters'] == 'capital of France'
+        assert steps[2]['type'] == 'observe'
+        assert steps[3]['type'] == 'think'
+        assert steps[4]['type'] == 'answer'
+
+    def test_tool_selection_logic(self):
+        """Test tool selection based on question type and context"""
+        # Arrange
+        test_cases = [
+            ("What is 2 + 2?", "calculator"),
+            ("Who is the president of France?", "knowledge_search"),
+            ("Tell me about the relationship between Paris and France", "graph_rag"),
+            ("What time is it?", "knowledge_search")  # Default to general search
+        ]
+        
+        available_tools = {
+            "calculator": {"description": "Perform mathematical calculations"},
+            "knowledge_search": {"description": "Search knowledge base for facts"},
+            "graph_rag": {"description": "Query knowledge graph for relationships"}
+        }
+        
+        def select_tool(question, tools):
+            """Select appropriate tool based on question content"""
+            question_lower = question.lower()
+            
+            # Math keywords
+            if any(word in question_lower for word in ['+', '-', '*', '/', 'calculate', 'math']):
+                return "calculator"
+            
+            # Relationship/graph keywords
+            if any(word in question_lower for word in ['relationship', 'between', 'connected', 'related']):
+                return "graph_rag"
+            
+            # General knowledge keywords or default case
+            if any(word in question_lower for word in ['who', 'what', 'where', 'when', 'why', 'how', 'time']):
+                return "knowledge_search"
+            
+            return None
+        
+        # Act & Assert
+        for question, expected_tool in test_cases:
+            selected_tool = select_tool(question, available_tools)
+            assert selected_tool == expected_tool, f"Question '{question}' should select {expected_tool}"
+
+    def test_tool_execution_logic(self):
+        """Test tool execution and result processing"""
+        # Arrange
+        def mock_knowledge_search(query):
+            if "capital" in query.lower() and "france" in query.lower():
+                return "Paris is the capital of France."
+            return "Information not found."
+        
+        def mock_calculator(expression):
+            try:
+                # Simple expression evaluation
+                if '+' in expression:
+                    parts = expression.split('+')
+                    return str(sum(int(p.strip()) for p in parts))
+                return str(eval(expression))
+            except:
+                return "Error: Invalid expression"
+        
+        tools = {
+            "knowledge_search": mock_knowledge_search,
+            "calculator": mock_calculator
+        }
+        
+        def execute_tool(tool_name, parameters, available_tools):
+            """Execute tool with given parameters"""
+            if tool_name not in available_tools:
+                return {"error": f"Tool {tool_name} not available"}
+            
+            try:
+                tool_function = available_tools[tool_name]
+                result = tool_function(parameters)
+                return {"success": True, "result": result}
+            except Exception as e:
+                return {"error": str(e)}
+        
+        # Act & Assert
+        test_cases = [
+            ("knowledge_search", "capital of France", "Paris is the capital of France."),
+            ("calculator", "2 + 2", "4"),
+            ("calculator", "invalid expression", "Error: Invalid expression"),
+            ("nonexistent_tool", "anything", None)  # Error case
+        ]
+        
+        for tool_name, params, expected in test_cases:
+            result = execute_tool(tool_name, params, tools)
+            
+            if expected is None:
+                assert "error" in result
+            else:
+                assert result.get("result") == expected
+
+    def test_conversation_context_integration(self):
+        """Test integration of conversation history into ReAct reasoning"""
+        # Arrange
+        conversation_history = [
+            {"role": "user", "content": "What is 2 + 2?"},
+            {"role": "assistant", "content": "2 + 2 = 4"},
+            {"role": "user", "content": "What about 3 + 3?"}
+        ]
+        
+        def build_context_prompt(question, history, max_turns=3):
+            """Build context prompt from conversation history"""
+            context_parts = []
+            
+            # Include recent conversation turns
+            recent_history = history[-(max_turns*2):] if history else []
+            
+            for turn in recent_history:
+                role = turn["role"]
+                content = turn["content"]
+                context_parts.append(f"{role}: {content}")
+            
+            current_question = f"user: {question}"
+            context_parts.append(current_question)
+            
+            return "\n".join(context_parts)
+        
+        # Act
+        context_prompt = build_context_prompt("What about 3 + 3?", conversation_history)
+        
+        # Assert
+        assert "2 + 2" in context_prompt
+        assert "2 + 2 = 4" in context_prompt
+        assert "3 + 3" in context_prompt
+        assert context_prompt.count("user:") == 3
+        assert context_prompt.count("assistant:") == 1
+
+    def test_react_cycle_validation(self):
+        """Test validation of complete ReAct cycles"""
+        # Arrange
+        complete_cycle = [
+            {"type": "think", "content": "I need to solve this math problem"},
+            {"type": "act", "tool_name": "calculator", "parameters": "2 + 2"},
+            {"type": "observe", "content": "The calculator returned 4"},
+            {"type": "think", "content": "I can now provide the answer"},
+            {"type": "answer", "content": "2 + 2 = 4"}
+        ]
+        
+        incomplete_cycle = [
+            {"type": "think", "content": "I need to solve this"},
+            {"type": "act", "tool_name": "calculator", "parameters": "2 + 2"}
+            # Missing observe and answer steps
+        ]
+        
+        def validate_react_cycle(steps):
+            """Validate that ReAct cycle is complete"""
+            step_types = [step.get("type") for step in steps]
+            
+            # Must have at least one think, act, observe, and answer
+            required_types = ["think", "act", "observe", "answer"]
+            
+            validation_results = {
+                "is_complete": all(req_type in step_types for req_type in required_types),
+                "has_reasoning": "think" in step_types,
+                "has_action": "act" in step_types,
+                "has_observation": "observe" in step_types,
+                "has_answer": "answer" in step_types,
+                "step_count": len(steps)
+            }
+            
+            return validation_results
+        
+        # Act & Assert
+        complete_validation = validate_react_cycle(complete_cycle)
+        assert complete_validation["is_complete"] is True
+        assert complete_validation["has_reasoning"] is True
+        assert complete_validation["has_action"] is True
+        assert complete_validation["has_observation"] is True
+        assert complete_validation["has_answer"] is True
+        
+        incomplete_validation = validate_react_cycle(incomplete_cycle)
+        assert incomplete_validation["is_complete"] is False
+        assert incomplete_validation["has_reasoning"] is True
+        assert incomplete_validation["has_action"] is True
+        assert incomplete_validation["has_observation"] is False
+        assert incomplete_validation["has_answer"] is False
+
+    def test_multi_step_reasoning_logic(self):
+        """Test multi-step reasoning chains"""
+        # Arrange
+        complex_question = "What is the population of the capital of France?"
+        
+        def plan_reasoning_steps(question):
+            """Plan the reasoning steps needed for complex questions"""
+            steps = []
+            
+            question_lower = question.lower()
+            
+            # Check if question requires multiple pieces of information
+            if "capital of" in question_lower and ("population" in question_lower or "how many" in question_lower):
+                steps.append({
+                    "step": 1,
+                    "action": "find_capital",
+                    "description": "First find the capital city"
+                })
+                steps.append({
+                    "step": 2,
+                    "action": "find_population",
+                    "description": "Then find the population of that city"
+                })
+            elif "capital of" in question_lower:
+                steps.append({
+                    "step": 1,
+                    "action": "find_capital",
+                    "description": "Find the capital city"
+                })
+            elif "population" in question_lower:
+                steps.append({
+                    "step": 1,
+                    "action": "find_population",
+                    "description": "Find the population"
+                })
+            else:
+                steps.append({
+                    "step": 1,
+                    "action": "general_search",
+                    "description": "Search for relevant information"
+                })
+            
+            return steps
+        
+        # Act
+        reasoning_plan = plan_reasoning_steps(complex_question)
+        
+        # Assert
+        assert len(reasoning_plan) == 2
+        assert reasoning_plan[0]["action"] == "find_capital"
+        assert reasoning_plan[1]["action"] == "find_population"
+        assert all("step" in step for step in reasoning_plan)
+
+    def test_error_handling_in_react_cycle(self):
+        """Test error handling during ReAct execution"""
+        # Arrange
+        def execute_react_step_with_errors(step_type, content, tools=None):
+            """Execute ReAct step with potential error handling"""
+            try:
+                if step_type == "think":
+                    # Thinking step - validate reasoning
+                    if not content or len(content.strip()) < 5:
+                        return {"error": "Reasoning too brief"}
+                    return {"success": True, "content": content}
+                
+                elif step_type == "act":
+                    # Action step - validate tool exists and execute
+                    if not tools or not content:
+                        return {"error": "No tools available or no action specified"}
+                    
+                    # Parse tool and parameters
+                    if ":" in content:
+                        tool_name, params = content.split(":", 1)
+                        tool_name = tool_name.strip()
+                        params = params.strip()
+                        
+                        if tool_name not in tools:
+                            return {"error": f"Tool {tool_name} not available"}
+                        
+                        # Execute tool
+                        result = tools[tool_name](params)
+                        return {"success": True, "tool_result": result}
+                    else:
+                        return {"error": "Invalid action format"}
+                
+                elif step_type == "observe":
+                    # Observation step - validate observation
+                    if not content:
+                        return {"error": "No observation provided"}
+                    return {"success": True, "content": content}
+                
+                else:
+                    return {"error": f"Unknown step type: {step_type}"}
+                    
+            except Exception as e:
+                return {"error": f"Execution error: {str(e)}"}
+        
+        # Test cases
+        mock_tools = {
+            "calculator": lambda x: str(eval(x)) if x.replace('+', '').replace('-', '').replace('*', '').replace('/', '').replace(' ', '').isdigit() else "Error"
+        }
+        
+        test_cases = [
+            ("think", "I need to calculate", {"success": True}),
+            ("think", "", {"error": True}),  # Empty reasoning
+            ("act", "calculator: 2 + 2", {"success": True}),
+            ("act", "nonexistent: something", {"error": True}),  # Tool doesn't exist
+            ("act", "invalid format", {"error": True}),  # Invalid format
+            ("observe", "The result is 4", {"success": True}),
+            ("observe", "", {"error": True}),  # Empty observation
+            ("invalid_step", "content", {"error": True})  # Invalid step type
+        ]
+        
+        # Act & Assert
+        for step_type, content, expected in test_cases:
+            result = execute_react_step_with_errors(step_type, content, mock_tools)
+            
+            if expected.get("error"):
+                assert "error" in result, f"Expected error for step {step_type}: {content}"
+            else:
+                assert "success" in result, f"Expected success for step {step_type}: {content}"
+
+    def test_response_synthesis_logic(self):
+        """Test synthesis of final response from ReAct steps"""
+        # Arrange
+        react_steps = [
+            {"type": "think", "content": "I need to find the capital of France"},
+            {"type": "act", "tool_name": "knowledge_search", "tool_result": "Paris is the capital of France"},
+            {"type": "observe", "content": "The search confirmed Paris is the capital"},
+            {"type": "think", "content": "I have the information needed to answer"}
+        ]
+        
+        def synthesize_response(steps, original_question):
+            """Synthesize final response from ReAct steps"""
+            # Extract key information from steps
+            tool_results = []
+            observations = []
+            reasoning = []
+            
+            for step in steps:
+                if step["type"] == "think":
+                    reasoning.append(step["content"])
+                elif step["type"] == "act" and "tool_result" in step:
+                    tool_results.append(step["tool_result"])
+                elif step["type"] == "observe":
+                    observations.append(step["content"])
+            
+            # Build response based on available information
+            if tool_results:
+                # Use tool results as primary information source
+                primary_info = tool_results[0]
+                
+                # Extract specific answer from tool result
+                if "capital" in original_question.lower() and "Paris" in primary_info:
+                    return "The capital of France is Paris."
+                elif "+" in original_question and any(char.isdigit() for char in primary_info):
+                    return f"The answer is {primary_info}."
+                else:
+                    return primary_info
+            else:
+                # Fallback to reasoning if no tool results
+                return "I need more information to answer this question."
+        
+        # Act
+        response = synthesize_response(react_steps, "What is the capital of France?")
+        
+        # Assert
+        assert "Paris" in response
+        assert "capital of france" in response.lower()
+        assert len(response) > 10  # Should be a complete sentence
+
+    def test_tool_parameter_extraction(self):
+        """Test extraction and validation of tool parameters"""
+        # Arrange
+        def extract_tool_parameters(action_content, tool_schema):
+            """Extract and validate parameters for tool execution"""
+            # Parse action content for tool name and parameters
+            if ":" not in action_content:
+                return {"error": "Invalid action format - missing tool parameters"}
+            
+            tool_name, params_str = action_content.split(":", 1)
+            tool_name = tool_name.strip()
+            params_str = params_str.strip()
+            
+            if tool_name not in tool_schema:
+                return {"error": f"Unknown tool: {tool_name}"}
+            
+            schema = tool_schema[tool_name]
+            required_params = schema.get("required_parameters", [])
+            
+            # Simple parameter extraction (for more complex tools, this would be more sophisticated)
+            if len(required_params) == 1 and required_params[0] == "query":
+                # Single query parameter
+                return {"tool_name": tool_name, "parameters": {"query": params_str}}
+            elif len(required_params) == 1 and required_params[0] == "expression":
+                # Single expression parameter  
+                return {"tool_name": tool_name, "parameters": {"expression": params_str}}
+            else:
+                # Multiple parameters would need more complex parsing
+                return {"tool_name": tool_name, "parameters": {"input": params_str}}
+        
+        tool_schema = {
+            "knowledge_search": {"required_parameters": ["query"]},
+            "calculator": {"required_parameters": ["expression"]},
+            "graph_rag": {"required_parameters": ["query"]}
+        }
+        
+        test_cases = [
+            ("knowledge_search: capital of France", "knowledge_search", {"query": "capital of France"}),
+            ("calculator: 2 + 2", "calculator", {"expression": "2 + 2"}),
+            ("invalid format", None, None),  # No colon
+            ("unknown_tool: something", None, None)  # Unknown tool
+        ]
+        
+        # Act & Assert
+        for action_content, expected_tool, expected_params in test_cases:
+            result = extract_tool_parameters(action_content, tool_schema)
+            
+            if expected_tool is None:
+                assert "error" in result
+            else:
+                assert result["tool_name"] == expected_tool
+                assert result["parameters"] == expected_params

tests/unit/test_agent/test_reasoning_engine.py

@@ -0,0 +1,532 @@
+"""
+Unit tests for reasoning engine logic
+
+Tests the core reasoning algorithms that power agent decision-making,
+including question analysis, reasoning chain construction, and 
+decision-making processes.
+"""
+
+import pytest
+from unittest.mock import Mock, AsyncMock
+
+
+class TestReasoningEngineLogic:
+    """Test cases for reasoning engine business logic"""
+
+    def test_question_analysis_and_categorization(self):
+        """Test analysis and categorization of user questions"""
+        # Arrange
+        def analyze_question(question):
+            """Analyze question to determine type and complexity"""
+            question_lower = question.lower().strip()
+            
+            analysis = {
+                "type": "unknown",
+                "complexity": "simple",
+                "entities": [],
+                "intent": "information_seeking",
+                "requires_tools": [],
+                "confidence": 0.5
+            }
+            
+            # Determine question type
+            question_words = question_lower.split()
+            if any(word in question_words for word in ["what", "who", "where", "when"]):
+                analysis["type"] = "factual"
+                analysis["intent"] = "information_seeking"
+                analysis["confidence"] = 0.8
+            elif any(word in question_words for word in ["how", "why"]):
+                analysis["type"] = "explanatory"
+                analysis["intent"] = "explanation_seeking"
+                analysis["complexity"] = "moderate"
+                analysis["confidence"] = 0.7
+            elif any(word in question_lower for word in ["calculate", "+", "-", "*", "/", "="]):
+                analysis["type"] = "computational"
+                analysis["intent"] = "calculation"
+                analysis["requires_tools"] = ["calculator"]
+                analysis["confidence"] = 0.9
+            elif any(phrase in question_lower for phrase in ["tell me about", "about"]):
+                analysis["type"] = "factual"
+                analysis["intent"] = "information_seeking"
+                analysis["confidence"] = 0.7
+            
+            # Detect entities (simplified)
+            known_entities = ["france", "paris", "openai", "microsoft", "python", "ai"]
+            analysis["entities"] = [entity for entity in known_entities if entity in question_lower]
+            
+            # Determine complexity
+            if len(question.split()) > 15:
+                analysis["complexity"] = "complex"
+            elif len(question.split()) > 8:
+                analysis["complexity"] = "moderate"
+            
+            # Determine required tools
+            if analysis["type"] == "computational":
+                analysis["requires_tools"] = ["calculator"]
+            elif analysis["entities"]:
+                analysis["requires_tools"] = ["knowledge_search", "graph_rag"]
+            elif analysis["type"] in ["factual", "explanatory"]:
+                analysis["requires_tools"] = ["knowledge_search"]
+            
+            return analysis
+        
+        test_cases = [
+            ("What is the capital of France?", "factual", ["france"], ["knowledge_search", "graph_rag"]),
+            ("How does machine learning work?", "explanatory", [], ["knowledge_search"]),
+            ("Calculate 15 * 8", "computational", [], ["calculator"]),
+            ("Tell me about OpenAI", "factual", ["openai"], ["knowledge_search", "graph_rag"]),
+            ("Why is Python popular for AI development?", "explanatory", ["python", "ai"], ["knowledge_search"])
+        ]
+        
+        # Act & Assert
+        for question, expected_type, expected_entities, expected_tools in test_cases:
+            analysis = analyze_question(question)
+            
+            assert analysis["type"] == expected_type, f"Question '{question}' got type '{analysis['type']}', expected '{expected_type}'"
+            assert all(entity in analysis["entities"] for entity in expected_entities)
+            assert any(tool in expected_tools for tool in analysis["requires_tools"])
+            assert analysis["confidence"] > 0.5
+
+    def test_reasoning_chain_construction(self):
+        """Test construction of logical reasoning chains"""
+        # Arrange
+        def construct_reasoning_chain(question, available_tools, context=None):
+            """Construct a logical chain of reasoning steps"""
+            reasoning_chain = []
+            
+            # Analyze question
+            question_lower = question.lower()
+            
+            # Multi-step questions requiring decomposition
+            if "capital of" in question_lower and ("population" in question_lower or "size" in question_lower):
+                reasoning_chain.extend([
+                    {
+                        "step": 1,
+                        "type": "decomposition",
+                        "description": "Break down complex question into sub-questions",
+                        "sub_questions": ["What is the capital?", "What is the population/size?"]
+                    },
+                    {
+                        "step": 2,
+                        "type": "information_gathering",
+                        "description": "Find the capital city",
+                        "tool": "knowledge_search",
+                        "query": f"capital of {question_lower.split('capital of')[1].split()[0]}"
+                    },
+                    {
+                        "step": 3,
+                        "type": "information_gathering",
+                        "description": "Find population/size of the capital",
+                        "tool": "knowledge_search",
+                        "query": "population size [CAPITAL_CITY]"
+                    },
+                    {
+                        "step": 4,
+                        "type": "synthesis",
+                        "description": "Combine information to answer original question"
+                    }
+                ])
+            
+            elif "relationship" in question_lower or "connection" in question_lower:
+                reasoning_chain.extend([
+                    {
+                        "step": 1,
+                        "type": "entity_identification",
+                        "description": "Identify entities mentioned in question"
+                    },
+                    {
+                        "step": 2,
+                        "type": "relationship_exploration",
+                        "description": "Explore relationships between entities",
+                        "tool": "graph_rag"
+                    },
+                    {
+                        "step": 3,
+                        "type": "analysis",
+                        "description": "Analyze relationship patterns and significance"
+                    }
+                ])
+            
+            elif any(op in question_lower for op in ["+", "-", "*", "/", "calculate"]):
+                reasoning_chain.extend([
+                    {
+                        "step": 1,
+                        "type": "expression_parsing",
+                        "description": "Parse mathematical expression from question"
+                    },
+                    {
+                        "step": 2,
+                        "type": "calculation",
+                        "description": "Perform calculation",
+                        "tool": "calculator"
+                    },
+                    {
+                        "step": 3,
+                        "type": "result_formatting",
+                        "description": "Format result appropriately"
+                    }
+                ])
+            
+            else:
+                # Simple information seeking
+                reasoning_chain.extend([
+                    {
+                        "step": 1,
+                        "type": "information_gathering",
+                        "description": "Search for relevant information",
+                        "tool": "knowledge_search"
+                    },
+                    {
+                        "step": 2,
+                        "type": "response_formulation",
+                        "description": "Formulate clear response"
+                    }
+                ])
+            
+            return reasoning_chain
+        
+        available_tools = ["knowledge_search", "graph_rag", "calculator"]
+        
+        # Act & Assert
+        # Test complex multi-step question
+        complex_chain = construct_reasoning_chain(
+            "What is the population of the capital of France?", 
+            available_tools
+        )
+        assert len(complex_chain) == 4
+        assert complex_chain[0]["type"] == "decomposition"
+        assert complex_chain[1]["tool"] == "knowledge_search"
+        
+        # Test relationship question
+        relationship_chain = construct_reasoning_chain(
+            "What is the relationship between Paris and France?",
+            available_tools
+        )
+        assert any(step["type"] == "relationship_exploration" for step in relationship_chain)
+        assert any(step.get("tool") == "graph_rag" for step in relationship_chain)
+        
+        # Test calculation question
+        calc_chain = construct_reasoning_chain("Calculate 15 * 8", available_tools)
+        assert any(step["type"] == "calculation" for step in calc_chain)
+        assert any(step.get("tool") == "calculator" for step in calc_chain)
+
+    def test_decision_making_algorithms(self):
+        """Test decision-making algorithms for tool selection and strategy"""
+        # Arrange
+        def make_reasoning_decisions(question, available_tools, context=None, constraints=None):
+            """Make decisions about reasoning approach and tool usage"""
+            decisions = {
+                "primary_strategy": "direct_search",
+                "selected_tools": [],
+                "reasoning_depth": "shallow",
+                "confidence": 0.5,
+                "fallback_strategy": "general_search"
+            }
+            
+            question_lower = question.lower()
+            constraints = constraints or {}
+            
+            # Strategy selection based on question type
+            if "calculate" in question_lower or any(op in question_lower for op in ["+", "-", "*", "/"]):
+                decisions["primary_strategy"] = "calculation"
+                decisions["selected_tools"] = ["calculator"]
+                decisions["reasoning_depth"] = "shallow"
+                decisions["confidence"] = 0.9
+            
+            elif "relationship" in question_lower or "connect" in question_lower:
+                decisions["primary_strategy"] = "graph_exploration"
+                decisions["selected_tools"] = ["graph_rag", "knowledge_search"]
+                decisions["reasoning_depth"] = "deep"
+                decisions["confidence"] = 0.8
+            
+            elif any(word in question_lower for word in ["what", "who", "where", "when"]):
+                decisions["primary_strategy"] = "factual_lookup"
+                decisions["selected_tools"] = ["knowledge_search"]
+                decisions["reasoning_depth"] = "moderate"
+                decisions["confidence"] = 0.7
+            
+            elif any(word in question_lower for word in ["how", "why", "explain"]):
+                decisions["primary_strategy"] = "explanatory_reasoning"
+                decisions["selected_tools"] = ["knowledge_search", "graph_rag"]
+                decisions["reasoning_depth"] = "deep"
+                decisions["confidence"] = 0.6
+            
+            # Apply constraints
+            if constraints.get("max_tools", 0) > 0:
+                decisions["selected_tools"] = decisions["selected_tools"][:constraints["max_tools"]]
+            
+            if constraints.get("fast_mode", False):
+                decisions["reasoning_depth"] = "shallow"
+                decisions["selected_tools"] = decisions["selected_tools"][:1]
+            
+            # Filter by available tools
+            decisions["selected_tools"] = [tool for tool in decisions["selected_tools"] if tool in available_tools]
+            
+            if not decisions["selected_tools"]:
+                decisions["primary_strategy"] = "general_search"
+                decisions["selected_tools"] = ["knowledge_search"] if "knowledge_search" in available_tools else []
+                decisions["confidence"] = 0.3
+            
+            return decisions
+        
+        available_tools = ["knowledge_search", "graph_rag", "calculator"]
+        
+        test_cases = [
+            ("What is 2 + 2?", "calculation", ["calculator"], 0.9),
+            ("What is the relationship between Paris and France?", "graph_exploration", ["graph_rag"], 0.8),
+            ("Who is the president of France?", "factual_lookup", ["knowledge_search"], 0.7),
+            ("How does photosynthesis work?", "explanatory_reasoning", ["knowledge_search"], 0.6)
+        ]
+        
+        # Act & Assert
+        for question, expected_strategy, expected_tools, min_confidence in test_cases:
+            decisions = make_reasoning_decisions(question, available_tools)
+            
+            assert decisions["primary_strategy"] == expected_strategy
+            assert any(tool in decisions["selected_tools"] for tool in expected_tools)
+            assert decisions["confidence"] >= min_confidence
+        
+        # Test with constraints
+        constrained_decisions = make_reasoning_decisions(
+            "How does machine learning work?", 
+            available_tools,
+            constraints={"fast_mode": True}
+        )
+        assert constrained_decisions["reasoning_depth"] == "shallow"
+        assert len(constrained_decisions["selected_tools"]) <= 1
+
+    def test_confidence_scoring_logic(self):
+        """Test confidence scoring for reasoning steps and decisions"""
+        # Arrange
+        def calculate_confidence_score(reasoning_step, available_evidence, tool_reliability=None):
+            """Calculate confidence score for a reasoning step"""
+            base_confidence = 0.5
+            tool_reliability = tool_reliability or {}
+            
+            step_type = reasoning_step.get("type", "unknown")
+            tool_used = reasoning_step.get("tool")
+            evidence_quality = available_evidence.get("quality", "medium")
+            evidence_sources = available_evidence.get("sources", 1)
+            
+            # Adjust confidence based on step type
+            confidence_modifiers = {
+                "calculation": 0.4,  # High confidence for math
+                "factual_lookup": 0.2,  # Moderate confidence for facts
+                "relationship_exploration": 0.1,  # Lower confidence for complex relationships
+                "synthesis": -0.1,  # Slightly lower for synthesized information
+                "speculation": -0.3   # Much lower for speculative reasoning
+            }
+            
+            base_confidence += confidence_modifiers.get(step_type, 0)
+            
+            # Adjust for tool reliability
+            if tool_used and tool_used in tool_reliability:
+                tool_score = tool_reliability[tool_used]
+                base_confidence += (tool_score - 0.5) * 0.2  # Scale tool reliability impact
+            
+            # Adjust for evidence quality
+            evidence_modifiers = {
+                "high": 0.2,
+                "medium": 0.0,
+                "low": -0.2,
+                "none": -0.4
+            }
+            base_confidence += evidence_modifiers.get(evidence_quality, 0)
+            
+            # Adjust for multiple sources
+            if evidence_sources > 1:
+                base_confidence += min(0.2, evidence_sources * 0.05)
+            
+            # Cap between 0 and 1
+            return max(0.0, min(1.0, base_confidence))
+        
+        tool_reliability = {
+            "calculator": 0.95,
+            "knowledge_search": 0.8,
+            "graph_rag": 0.7
+        }
+        
+        test_cases = [
+            (
+                {"type": "calculation", "tool": "calculator"},
+                {"quality": "high", "sources": 1},
+                0.9  # Should be very high confidence
+            ),
+            (
+                {"type": "factual_lookup", "tool": "knowledge_search"},
+                {"quality": "medium", "sources": 2},
+                0.8  # Good confidence with multiple sources
+            ),
+            (
+                {"type": "speculation", "tool": None},
+                {"quality": "low", "sources": 1},
+                0.0  # Very low confidence for speculation with low quality evidence
+            ),
+            (
+                {"type": "relationship_exploration", "tool": "graph_rag"},
+                {"quality": "high", "sources": 3},
+                0.7  # Moderate-high confidence
+            )
+        ]
+        
+        # Act & Assert
+        for reasoning_step, evidence, expected_min_confidence in test_cases:
+            confidence = calculate_confidence_score(reasoning_step, evidence, tool_reliability)
+            assert confidence >= expected_min_confidence - 0.15  # Allow larger tolerance for confidence calculations
+            assert 0 <= confidence <= 1
+
+    def test_reasoning_validation_logic(self):
+        """Test validation of reasoning chains for logical consistency"""
+        # Arrange
+        def validate_reasoning_chain(reasoning_chain):
+            """Validate logical consistency of reasoning chain"""
+            validation_results = {
+                "is_valid": True,
+                "issues": [],
+                "completeness_score": 0.0,
+                "logical_consistency": 0.0
+            }
+            
+            if not reasoning_chain:
+                validation_results["is_valid"] = False
+                validation_results["issues"].append("Empty reasoning chain")
+                return validation_results
+            
+            # Check for required components
+            step_types = [step.get("type") for step in reasoning_chain]
+            
+            # Must have some form of information gathering or processing
+            has_information_step = any(t in step_types for t in [
+                "information_gathering", "calculation", "relationship_exploration"
+            ])
+            
+            if not has_information_step:
+                validation_results["issues"].append("No information gathering step")
+            
+            # Check for logical flow
+            for i, step in enumerate(reasoning_chain):
+                # Each step should have required fields
+                if "type" not in step:
+                    validation_results["issues"].append(f"Step {i+1} missing type")
+                
+                if "description" not in step:
+                    validation_results["issues"].append(f"Step {i+1} missing description")
+                
+                # Tool steps should specify tool
+                if step.get("type") in ["information_gathering", "calculation", "relationship_exploration"]:
+                    if "tool" not in step:
+                        validation_results["issues"].append(f"Step {i+1} missing tool specification")
+            
+            # Check for synthesis or conclusion
+            has_synthesis = any(t in step_types for t in [
+                "synthesis", "response_formulation", "result_formatting"
+            ])
+            
+            if not has_synthesis and len(reasoning_chain) > 1:
+                validation_results["issues"].append("Multi-step reasoning missing synthesis")
+            
+            # Calculate scores
+            completeness_items = [
+                has_information_step,
+                has_synthesis or len(reasoning_chain) == 1,
+                all("description" in step for step in reasoning_chain),
+                len(reasoning_chain) >= 1
+            ]
+            validation_results["completeness_score"] = sum(completeness_items) / len(completeness_items)
+            
+            consistency_items = [
+                len(validation_results["issues"]) == 0,
+                len(reasoning_chain) > 0,
+                all("type" in step for step in reasoning_chain)
+            ]
+            validation_results["logical_consistency"] = sum(consistency_items) / len(consistency_items)
+            
+            validation_results["is_valid"] = len(validation_results["issues"]) == 0
+            
+            return validation_results
+        
+        # Test cases
+        valid_chain = [
+            {"type": "information_gathering", "description": "Search for information", "tool": "knowledge_search"},
+            {"type": "response_formulation", "description": "Formulate response"}
+        ]
+        
+        invalid_chain = [
+            {"description": "Do something"},  # Missing type
+            {"type": "information_gathering"}  # Missing description and tool
+        ]
+        
+        empty_chain = []
+        
+        # Act & Assert
+        valid_result = validate_reasoning_chain(valid_chain)
+        assert valid_result["is_valid"] is True
+        assert len(valid_result["issues"]) == 0
+        assert valid_result["completeness_score"] > 0.8
+        
+        invalid_result = validate_reasoning_chain(invalid_chain)
+        assert invalid_result["is_valid"] is False
+        assert len(invalid_result["issues"]) > 0
+        
+        empty_result = validate_reasoning_chain(empty_chain)
+        assert empty_result["is_valid"] is False
+        assert "Empty reasoning chain" in empty_result["issues"]
+
+    def test_adaptive_reasoning_strategies(self):
+        """Test adaptive reasoning that adjusts based on context and feedback"""
+        # Arrange
+        def adapt_reasoning_strategy(initial_strategy, feedback, context=None):
+            """Adapt reasoning strategy based on feedback and context"""
+            adapted_strategy = initial_strategy.copy()
+            context = context or {}
+            
+            # Analyze feedback
+            if feedback.get("accuracy", 0) < 0.5:
+                # Low accuracy - need different approach
+                if initial_strategy["primary_strategy"] == "direct_search":
+                    adapted_strategy["primary_strategy"] = "multi_source_verification"
+                    adapted_strategy["selected_tools"].extend(["graph_rag"])
+                    adapted_strategy["reasoning_depth"] = "deep"
+                
+                elif initial_strategy["primary_strategy"] == "factual_lookup":
+                    adapted_strategy["primary_strategy"] = "explanatory_reasoning" 
+                    adapted_strategy["reasoning_depth"] = "deep"
+            
+            if feedback.get("completeness", 0) < 0.5:
+                # Incomplete answer - need more comprehensive approach
+                adapted_strategy["reasoning_depth"] = "deep"
+                if "graph_rag" not in adapted_strategy["selected_tools"]:
+                    adapted_strategy["selected_tools"].append("graph_rag")
+            
+            if feedback.get("response_time", 0) > context.get("max_response_time", 30):
+                # Too slow - simplify approach
+                adapted_strategy["reasoning_depth"] = "shallow"
+                adapted_strategy["selected_tools"] = adapted_strategy["selected_tools"][:1]
+            
+            # Update confidence based on adaptation
+            if adapted_strategy != initial_strategy:
+                adapted_strategy["confidence"] = max(0.3, adapted_strategy["confidence"] - 0.2)
+            
+            return adapted_strategy
+        
+        initial_strategy = {
+            "primary_strategy": "direct_search",
+            "selected_tools": ["knowledge_search"],
+            "reasoning_depth": "shallow",
+            "confidence": 0.7
+        }
+        
+        # Test adaptation to low accuracy feedback
+        low_accuracy_feedback = {"accuracy": 0.3, "completeness": 0.8, "response_time": 10}
+        adapted = adapt_reasoning_strategy(initial_strategy, low_accuracy_feedback)
+        
+        assert adapted["primary_strategy"] != initial_strategy["primary_strategy"]
+        assert "graph_rag" in adapted["selected_tools"]
+        assert adapted["reasoning_depth"] == "deep"
+        
+        # Test adaptation to slow response
+        slow_feedback = {"accuracy": 0.8, "completeness": 0.8, "response_time": 40}
+        adapted_fast = adapt_reasoning_strategy(initial_strategy, slow_feedback, {"max_response_time": 30})
+        
+        assert adapted_fast["reasoning_depth"] == "shallow"
+        assert len(adapted_fast["selected_tools"]) <= 1

tests/unit/test_agent/test_tool_coordination.py

@@ -0,0 +1,726 @@
+"""
+Unit tests for tool coordination logic
+
+Tests the core business logic for coordinating multiple tools,
+managing tool execution, handling failures, and optimizing
+tool usage patterns.
+"""
+
+import pytest
+from unittest.mock import Mock, AsyncMock
+import asyncio
+from collections import defaultdict
+
+
+class TestToolCoordinationLogic:
+    """Test cases for tool coordination business logic"""
+
+    def test_tool_registry_management(self):
+        """Test tool registration and availability management"""
+        # Arrange
+        class ToolRegistry:
+            def __init__(self):
+                self.tools = {}
+                self.tool_metadata = {}
+            
+            def register_tool(self, name, tool_function, metadata=None):
+                """Register a tool with optional metadata"""
+                self.tools[name] = tool_function
+                self.tool_metadata[name] = metadata or {}
+                return True
+            
+            def unregister_tool(self, name):
+                """Remove a tool from registry"""
+                if name in self.tools:
+                    del self.tools[name]
+                    del self.tool_metadata[name]
+                    return True
+                return False
+            
+            def get_available_tools(self):
+                """Get list of available tools"""
+                return list(self.tools.keys())
+            
+            def get_tool_info(self, name):
+                """Get tool function and metadata"""
+                if name not in self.tools:
+                    return None
+                return {
+                    "function": self.tools[name],
+                    "metadata": self.tool_metadata[name]
+                }
+            
+            def is_tool_available(self, name):
+                """Check if tool is available"""
+                return name in self.tools
+        
+        # Act
+        registry = ToolRegistry()
+        
+        # Register tools
+        def mock_calculator(expr):
+            return str(eval(expr))
+        
+        def mock_search(query):
+            return f"Search results for: {query}"
+        
+        registry.register_tool("calculator", mock_calculator, {
+            "description": "Perform calculations",
+            "parameters": ["expression"],
+            "category": "math"
+        })
+        
+        registry.register_tool("search", mock_search, {
+            "description": "Search knowledge base",
+            "parameters": ["query"],
+            "category": "information"
+        })
+        
+        # Assert
+        assert registry.is_tool_available("calculator")
+        assert registry.is_tool_available("search")
+        assert not registry.is_tool_available("nonexistent")
+        
+        available_tools = registry.get_available_tools()
+        assert "calculator" in available_tools
+        assert "search" in available_tools
+        assert len(available_tools) == 2
+        
+        # Test tool info retrieval
+        calc_info = registry.get_tool_info("calculator")
+        assert calc_info["metadata"]["category"] == "math"
+        assert "expression" in calc_info["metadata"]["parameters"]
+        
+        # Test unregistration
+        assert registry.unregister_tool("calculator") is True
+        assert not registry.is_tool_available("calculator")
+        assert len(registry.get_available_tools()) == 1
+
+    def test_tool_execution_coordination(self):
+        """Test coordination of tool execution with proper sequencing"""
+        # Arrange
+        async def execute_tool_sequence(tool_sequence, tool_registry):
+            """Execute a sequence of tools with coordination"""
+            results = []
+            context = {}
+            
+            for step in tool_sequence:
+                tool_name = step["tool"]
+                parameters = step["parameters"]
+                
+                # Check if tool is available
+                if not tool_registry.is_tool_available(tool_name):
+                    results.append({
+                        "step": step,
+                        "status": "error",
+                        "error": f"Tool {tool_name} not available"
+                    })
+                    continue
+                
+                try:
+                    # Get tool function
+                    tool_info = tool_registry.get_tool_info(tool_name)
+                    tool_function = tool_info["function"]
+                    
+                    # Substitute context variables in parameters
+                    resolved_params = {}
+                    for key, value in parameters.items():
+                        if isinstance(value, str) and value.startswith("${") and value.endswith("}"):
+                            # Context variable substitution
+                            var_name = value[2:-1]
+                            resolved_params[key] = context.get(var_name, value)
+                        else:
+                            resolved_params[key] = value
+                    
+                    # Execute tool
+                    if asyncio.iscoroutinefunction(tool_function):
+                        result = await tool_function(**resolved_params)
+                    else:
+                        result = tool_function(**resolved_params)
+                    
+                    # Store result
+                    step_result = {
+                        "step": step,
+                        "status": "success",
+                        "result": result
+                    }
+                    results.append(step_result)
+                    
+                    # Update context for next steps
+                    if "context_key" in step:
+                        context[step["context_key"]] = result
+                
+                except Exception as e:
+                    results.append({
+                        "step": step,
+                        "status": "error", 
+                        "error": str(e)
+                    })
+            
+            return results, context
+        
+        # Create mock tool registry
+        class MockToolRegistry:
+            def __init__(self):
+                self.tools = {
+                    "search": lambda query: f"Found: {query}",
+                    "calculator": lambda expression: str(eval(expression)),
+                    "formatter": lambda text, format_type: f"[{format_type}] {text}"
+                }
+            
+            def is_tool_available(self, name):
+                return name in self.tools
+            
+            def get_tool_info(self, name):
+                return {"function": self.tools[name]}
+        
+        registry = MockToolRegistry()
+        
+        # Test sequence with context passing
+        tool_sequence = [
+            {
+                "tool": "search",
+                "parameters": {"query": "capital of France"},
+                "context_key": "search_result"
+            },
+            {
+                "tool": "formatter",
+                "parameters": {"text": "${search_result}", "format_type": "markdown"},
+                "context_key": "formatted_result"
+            }
+        ]
+        
+        # Act
+        results, context = asyncio.run(execute_tool_sequence(tool_sequence, registry))
+        
+        # Assert
+        assert len(results) == 2
+        assert all(result["status"] == "success" for result in results)
+        assert "search_result" in context
+        assert "formatted_result" in context
+        assert "Found: capital of France" in context["search_result"]
+        assert "[markdown]" in context["formatted_result"]
+
+    def test_parallel_tool_execution(self):
+        """Test parallel execution of independent tools"""
+        # Arrange
+        async def execute_tools_parallel(tool_requests, tool_registry, max_concurrent=3):
+            """Execute multiple tools in parallel with concurrency limit"""
+            semaphore = asyncio.Semaphore(max_concurrent)
+            
+            async def execute_single_tool(tool_request):
+                async with semaphore:
+                    tool_name = tool_request["tool"]
+                    parameters = tool_request["parameters"]
+                    
+                    if not tool_registry.is_tool_available(tool_name):
+                        return {
+                            "request": tool_request,
+                            "status": "error",
+                            "error": f"Tool {tool_name} not available"
+                        }
+                    
+                    try:
+                        tool_info = tool_registry.get_tool_info(tool_name)
+                        tool_function = tool_info["function"]
+                        
+                        # Simulate async execution with delay
+                        await asyncio.sleep(0.001)  # Small delay to simulate work
+                        
+                        if asyncio.iscoroutinefunction(tool_function):
+                            result = await tool_function(**parameters)
+                        else:
+                            result = tool_function(**parameters)
+                        
+                        return {
+                            "request": tool_request,
+                            "status": "success",
+                            "result": result
+                        }
+                    
+                    except Exception as e:
+                        return {
+                            "request": tool_request,
+                            "status": "error",
+                            "error": str(e)
+                        }
+            
+            # Execute all tools concurrently
+            tasks = [execute_single_tool(request) for request in tool_requests]
+            results = await asyncio.gather(*tasks, return_exceptions=True)
+            
+            # Handle any exceptions
+            processed_results = []
+            for result in results:
+                if isinstance(result, Exception):
+                    processed_results.append({
+                        "status": "error",
+                        "error": str(result)
+                    })
+                else:
+                    processed_results.append(result)
+            
+            return processed_results
+        
+        # Create mock async tools
+        class MockAsyncToolRegistry:
+            def __init__(self):
+                self.tools = {
+                    "fast_search": self._fast_search,
+                    "slow_calculation": self._slow_calculation,
+                    "medium_analysis": self._medium_analysis
+                }
+            
+            async def _fast_search(self, query):
+                await asyncio.sleep(0.01)
+                return f"Fast result for: {query}"
+            
+            async def _slow_calculation(self, expression):
+                await asyncio.sleep(0.05)
+                return f"Calculated: {expression} = {eval(expression)}"
+            
+            async def _medium_analysis(self, text):
+                await asyncio.sleep(0.03)
+                return f"Analysis of: {text}"
+            
+            def is_tool_available(self, name):
+                return name in self.tools
+            
+            def get_tool_info(self, name):
+                return {"function": self.tools[name]}
+        
+        registry = MockAsyncToolRegistry()
+        
+        tool_requests = [
+            {"tool": "fast_search", "parameters": {"query": "test query 1"}},
+            {"tool": "slow_calculation", "parameters": {"expression": "2 + 2"}},
+            {"tool": "medium_analysis", "parameters": {"text": "sample text"}},
+            {"tool": "fast_search", "parameters": {"query": "test query 2"}}
+        ]
+        
+        # Act
+        import time
+        start_time = time.time()
+        results = asyncio.run(execute_tools_parallel(tool_requests, registry))
+        execution_time = time.time() - start_time
+        
+        # Assert
+        assert len(results) == 4
+        assert all(result["status"] == "success" for result in results)
+        # Should be faster than sequential execution
+        assert execution_time < 0.15  # Much faster than 0.01+0.05+0.03+0.01 = 0.10
+        
+        # Check specific results
+        search_results = [r for r in results if r["request"]["tool"] == "fast_search"]
+        assert len(search_results) == 2
+        calc_results = [r for r in results if r["request"]["tool"] == "slow_calculation"]
+        assert "Calculated: 2 + 2 = 4" in calc_results[0]["result"]
+
+    def test_tool_failure_handling_and_retry(self):
+        """Test handling of tool failures with retry logic"""
+        # Arrange
+        class RetryableToolExecutor:
+            def __init__(self, max_retries=3, backoff_factor=1.5):
+                self.max_retries = max_retries
+                self.backoff_factor = backoff_factor
+                self.call_counts = defaultdict(int)
+            
+            async def execute_with_retry(self, tool_name, tool_function, parameters):
+                """Execute tool with retry logic"""
+                last_error = None
+                
+                for attempt in range(self.max_retries + 1):
+                    try:
+                        self.call_counts[tool_name] += 1
+                        
+                        # Simulate delay for retries
+                        if attempt > 0:
+                            await asyncio.sleep(0.001 * (self.backoff_factor ** attempt))
+                        
+                        if asyncio.iscoroutinefunction(tool_function):
+                            result = await tool_function(**parameters)
+                        else:
+                            result = tool_function(**parameters)
+                        
+                        return {
+                            "status": "success",
+                            "result": result,
+                            "attempts": attempt + 1
+                        }
+                    
+                    except Exception as e:
+                        last_error = e
+                        if attempt < self.max_retries:
+                            continue  # Retry
+                        else:
+                            break  # Max retries exceeded
+                
+                return {
+                    "status": "failed",
+                    "error": str(last_error),
+                    "attempts": self.max_retries + 1
+                }
+        
+        # Create flaky tools that fail sometimes
+        class FlakyTools:
+            def __init__(self):
+                self.search_calls = 0
+                self.calc_calls = 0
+            
+            def flaky_search(self, query):
+                self.search_calls += 1
+                if self.search_calls <= 2:  # Fail first 2 attempts
+                    raise Exception("Network timeout")
+                return f"Search result for: {query}"
+            
+            def always_failing_calc(self, expression):
+                self.calc_calls += 1
+                raise Exception("Calculator service unavailable")
+            
+            def reliable_tool(self, input_text):
+                return f"Processed: {input_text}"
+        
+        flaky_tools = FlakyTools()
+        executor = RetryableToolExecutor(max_retries=3)
+        
+        # Act & Assert
+        # Test successful retry after failures
+        search_result = asyncio.run(executor.execute_with_retry(
+            "flaky_search", 
+            flaky_tools.flaky_search, 
+            {"query": "test"}
+        ))
+        
+        assert search_result["status"] == "success"
+        assert search_result["attempts"] == 3  # Failed twice, succeeded on third attempt
+        assert "Search result for: test" in search_result["result"]
+        
+        # Test tool that always fails
+        calc_result = asyncio.run(executor.execute_with_retry(
+            "always_failing_calc",
+            flaky_tools.always_failing_calc,
+            {"expression": "2 + 2"}
+        ))
+        
+        assert calc_result["status"] == "failed"
+        assert calc_result["attempts"] == 4  # Initial + 3 retries
+        assert "Calculator service unavailable" in calc_result["error"]
+        
+        # Test reliable tool (no retries needed)
+        reliable_result = asyncio.run(executor.execute_with_retry(
+            "reliable_tool",
+            flaky_tools.reliable_tool,
+            {"input_text": "hello"}
+        ))
+        
+        assert reliable_result["status"] == "success"
+        assert reliable_result["attempts"] == 1
+
+    def test_tool_dependency_resolution(self):
+        """Test resolution of tool dependencies and execution ordering"""
+        # Arrange
+        def resolve_tool_dependencies(tool_requests):
+            """Resolve dependencies and create execution plan"""
+            # Build dependency graph
+            dependency_graph = {}
+            all_tools = set()
+            
+            for request in tool_requests:
+                tool_name = request["tool"]
+                dependencies = request.get("depends_on", [])
+                dependency_graph[tool_name] = dependencies
+                all_tools.add(tool_name)
+                all_tools.update(dependencies)
+            
+            # Topological sort to determine execution order
+            def topological_sort(graph):
+                in_degree = {node: 0 for node in graph}
+                
+                # Calculate in-degrees
+                for node in graph:
+                    for dependency in graph[node]:
+                        if dependency in in_degree:
+                            in_degree[node] += 1
+                
+                # Find nodes with no dependencies
+                queue = [node for node in in_degree if in_degree[node] == 0]
+                result = []
+                
+                while queue:
+                    node = queue.pop(0)
+                    result.append(node)
+                    
+                    # Remove this node and update in-degrees
+                    for dependent in graph:
+                        if node in graph[dependent]:
+                            in_degree[dependent] -= 1
+                            if in_degree[dependent] == 0:
+                                queue.append(dependent)
+                
+                # Check for cycles
+                if len(result) != len(graph):
+                    remaining = set(graph.keys()) - set(result)
+                    return None, f"Circular dependency detected among: {list(remaining)}"
+                
+                return result, None
+            
+            execution_order, error = topological_sort(dependency_graph)
+            
+            if error:
+                return None, error
+            
+            # Create execution plan
+            execution_plan = []
+            for tool_name in execution_order:
+                # Find the request for this tool
+                tool_request = next((req for req in tool_requests if req["tool"] == tool_name), None)
+                if tool_request:
+                    execution_plan.append(tool_request)
+            
+            return execution_plan, None
+        
+        # Test case 1: Simple dependency chain
+        requests_simple = [
+            {"tool": "fetch_data", "depends_on": []},
+            {"tool": "process_data", "depends_on": ["fetch_data"]},
+            {"tool": "generate_report", "depends_on": ["process_data"]}
+        ]
+        
+        plan, error = resolve_tool_dependencies(requests_simple)
+        assert error is None
+        assert len(plan) == 3
+        assert plan[0]["tool"] == "fetch_data"
+        assert plan[1]["tool"] == "process_data"
+        assert plan[2]["tool"] == "generate_report"
+        
+        # Test case 2: Complex dependencies
+        requests_complex = [
+            {"tool": "tool_d", "depends_on": ["tool_b", "tool_c"]},
+            {"tool": "tool_b", "depends_on": ["tool_a"]},
+            {"tool": "tool_c", "depends_on": ["tool_a"]},
+            {"tool": "tool_a", "depends_on": []}
+        ]
+        
+        plan, error = resolve_tool_dependencies(requests_complex)
+        assert error is None
+        assert plan[0]["tool"] == "tool_a"  # No dependencies
+        assert plan[3]["tool"] == "tool_d"  # Depends on others
+        
+        # Test case 3: Circular dependency
+        requests_circular = [
+            {"tool": "tool_x", "depends_on": ["tool_y"]},
+            {"tool": "tool_y", "depends_on": ["tool_z"]},
+            {"tool": "tool_z", "depends_on": ["tool_x"]}
+        ]
+        
+        plan, error = resolve_tool_dependencies(requests_circular)
+        assert plan is None
+        assert "Circular dependency" in error
+
+    def test_tool_resource_management(self):
+        """Test management of tool resources and limits"""
+        # Arrange
+        class ToolResourceManager:
+            def __init__(self, resource_limits=None):
+                self.resource_limits = resource_limits or {}
+                self.current_usage = defaultdict(int)
+                self.tool_resource_requirements = {}
+            
+            def register_tool_resources(self, tool_name, resource_requirements):
+                """Register resource requirements for a tool"""
+                self.tool_resource_requirements[tool_name] = resource_requirements
+            
+            def can_execute_tool(self, tool_name):
+                """Check if tool can be executed within resource limits"""
+                if tool_name not in self.tool_resource_requirements:
+                    return True, "No resource requirements"
+                
+                requirements = self.tool_resource_requirements[tool_name]
+                
+                for resource, required_amount in requirements.items():
+                    available = self.resource_limits.get(resource, float('inf'))
+                    current = self.current_usage[resource]
+                    
+                    if current + required_amount > available:
+                        return False, f"Insufficient {resource}: need {required_amount}, available {available - current}"
+                
+                return True, "Resources available"
+            
+            def allocate_resources(self, tool_name):
+                """Allocate resources for tool execution"""
+                if tool_name not in self.tool_resource_requirements:
+                    return True
+                
+                can_execute, reason = self.can_execute_tool(tool_name)
+                if not can_execute:
+                    return False
+                
+                requirements = self.tool_resource_requirements[tool_name]
+                for resource, amount in requirements.items():
+                    self.current_usage[resource] += amount
+                
+                return True
+            
+            def release_resources(self, tool_name):
+                """Release resources after tool execution"""
+                if tool_name not in self.tool_resource_requirements:
+                    return
+                
+                requirements = self.tool_resource_requirements[tool_name]
+                for resource, amount in requirements.items():
+                    self.current_usage[resource] = max(0, self.current_usage[resource] - amount)
+            
+            def get_resource_usage(self):
+                """Get current resource usage"""
+                return dict(self.current_usage)
+        
+        # Set up resource manager
+        resource_manager = ToolResourceManager({
+            "memory": 800,  # MB (reduced to make test fail properly)
+            "cpu": 4,       # cores
+            "network": 10   # concurrent connections
+        })
+        
+        # Register tool resource requirements
+        resource_manager.register_tool_resources("heavy_analysis", {
+            "memory": 500,
+            "cpu": 2
+        })
+        
+        resource_manager.register_tool_resources("network_fetch", {
+            "memory": 100,
+            "network": 3
+        })
+        
+        resource_manager.register_tool_resources("light_calc", {
+            "cpu": 1
+        })
+        
+        # Test resource allocation
+        assert resource_manager.allocate_resources("heavy_analysis") is True
+        assert resource_manager.get_resource_usage()["memory"] == 500
+        assert resource_manager.get_resource_usage()["cpu"] == 2
+        
+        # Test trying to allocate another heavy_analysis (would exceed limit)
+        can_execute, reason = resource_manager.can_execute_tool("heavy_analysis")
+        assert can_execute is False  # Would exceed memory limit (500 + 500 > 800)
+        assert "memory" in reason.lower()
+        
+        # Test resource release
+        resource_manager.release_resources("heavy_analysis")
+        assert resource_manager.get_resource_usage()["memory"] == 0
+        assert resource_manager.get_resource_usage()["cpu"] == 0
+        
+        # Test multiple tool execution
+        assert resource_manager.allocate_resources("network_fetch") is True
+        assert resource_manager.allocate_resources("light_calc") is True
+        
+        usage = resource_manager.get_resource_usage()
+        assert usage["memory"] == 100
+        assert usage["cpu"] == 1
+        assert usage["network"] == 3
+
+    def test_tool_performance_monitoring(self):
+        """Test monitoring of tool performance and optimization"""
+        # Arrange
+        class ToolPerformanceMonitor:
+            def __init__(self):
+                self.execution_stats = defaultdict(list)
+                self.error_counts = defaultdict(int)
+                self.total_executions = defaultdict(int)
+            
+            def record_execution(self, tool_name, execution_time, success, error=None):
+                """Record tool execution statistics"""
+                self.total_executions[tool_name] += 1
+                self.execution_stats[tool_name].append({
+                    "execution_time": execution_time,
+                    "success": success,
+                    "error": error
+                })
+                
+                if not success:
+                    self.error_counts[tool_name] += 1
+            
+            def get_tool_performance(self, tool_name):
+                """Get performance statistics for a tool"""
+                if tool_name not in self.execution_stats:
+                    return None
+                
+                stats = self.execution_stats[tool_name]
+                execution_times = [s["execution_time"] for s in stats if s["success"]]
+                
+                if not execution_times:
+                    return {
+                        "total_executions": self.total_executions[tool_name],
+                        "success_rate": 0.0,
+                        "average_execution_time": 0.0,
+                        "error_count": self.error_counts[tool_name]
+                    }
+                
+                return {
+                    "total_executions": self.total_executions[tool_name],
+                    "success_rate": len(execution_times) / self.total_executions[tool_name],
+                    "average_execution_time": sum(execution_times) / len(execution_times),
+                    "min_execution_time": min(execution_times),
+                    "max_execution_time": max(execution_times),
+                    "error_count": self.error_counts[tool_name]
+                }
+            
+            def get_performance_recommendations(self, tool_name):
+                """Get performance optimization recommendations"""
+                performance = self.get_tool_performance(tool_name)
+                if not performance:
+                    return []
+                
+                recommendations = []
+                
+                if performance["success_rate"] < 0.8:
+                    recommendations.append("High error rate - consider implementing retry logic or health checks")
+                
+                if performance["average_execution_time"] > 10.0:
+                    recommendations.append("Slow execution time - consider optimization or caching")
+                
+                if performance["total_executions"] > 100 and performance["success_rate"] > 0.95:
+                    recommendations.append("Highly reliable tool - suitable for critical operations")
+                
+                return recommendations
+        
+        # Test performance monitoring
+        monitor = ToolPerformanceMonitor()
+        
+        # Record various execution scenarios
+        monitor.record_execution("fast_tool", 0.5, True)
+        monitor.record_execution("fast_tool", 0.6, True)
+        monitor.record_execution("fast_tool", 0.4, True)
+        
+        monitor.record_execution("slow_tool", 15.0, True)
+        monitor.record_execution("slow_tool", 12.0, True)
+        monitor.record_execution("slow_tool", 18.0, False, "Timeout")
+        
+        monitor.record_execution("unreliable_tool", 2.0, False, "Network error")
+        monitor.record_execution("unreliable_tool", 1.8, False, "Auth error") 
+        monitor.record_execution("unreliable_tool", 2.2, True)
+        
+        # Test performance statistics
+        fast_performance = monitor.get_tool_performance("fast_tool")
+        assert fast_performance["success_rate"] == 1.0
+        assert fast_performance["average_execution_time"] == 0.5
+        assert fast_performance["total_executions"] == 3
+        
+        slow_performance = monitor.get_tool_performance("slow_tool")
+        assert slow_performance["success_rate"] == 2/3  # 2 successes out of 3
+        assert slow_performance["average_execution_time"] == 13.5  # (15.0 + 12.0) / 2
+        
+        unreliable_performance = monitor.get_tool_performance("unreliable_tool")
+        assert unreliable_performance["success_rate"] == 1/3
+        assert unreliable_performance["error_count"] == 2
+        
+        # Test recommendations
+        fast_recommendations = monitor.get_performance_recommendations("fast_tool")
+        assert len(fast_recommendations) == 0  # No issues
+        
+        slow_recommendations = monitor.get_performance_recommendations("slow_tool")
+        assert any("slow execution" in rec.lower() for rec in slow_recommendations)
+        
+        unreliable_recommendations = monitor.get_performance_recommendations("unreliable_tool")
+        assert any("error rate" in rec.lower() for rec in unreliable_recommendations)

tests/unit/test_base/test_async_processor.py

@@ -0,0 +1,58 @@
+"""
+Unit tests for trustgraph.base.async_processor
+Starting small with a single test to verify basic functionality
+"""
+
+import pytest
+from unittest.mock import AsyncMock, MagicMock, patch
+from unittest import IsolatedAsyncioTestCase
+
+# Import the service under test
+from trustgraph.base.async_processor import AsyncProcessor
+
+
+class TestAsyncProcessorSimple(IsolatedAsyncioTestCase):
+    """Test AsyncProcessor base class functionality"""
+
+    @patch('trustgraph.base.async_processor.PulsarClient')
+    @patch('trustgraph.base.async_processor.Consumer')
+    @patch('trustgraph.base.async_processor.ProcessorMetrics')
+    @patch('trustgraph.base.async_processor.ConsumerMetrics')
+    async def test_async_processor_initialization_basic(self, mock_consumer_metrics, mock_processor_metrics, 
+                                                       mock_consumer, mock_pulsar_client):
+        """Test basic AsyncProcessor initialization"""
+        # Arrange
+        mock_pulsar_client.return_value = MagicMock()
+        mock_consumer.return_value = MagicMock()
+        mock_processor_metrics.return_value = MagicMock()
+        mock_consumer_metrics.return_value = MagicMock()
+        
+        config = {
+            'id': 'test-async-processor',
+            'taskgroup': AsyncMock()
+        }
+
+        # Act
+        processor = AsyncProcessor(**config)
+
+        # Assert
+        # Verify basic attributes are set
+        assert processor.id == 'test-async-processor'
+        assert processor.taskgroup == config['taskgroup']
+        assert processor.running == True
+        assert hasattr(processor, 'config_handlers')
+        assert processor.config_handlers == []
+        
+        # Verify PulsarClient was created
+        mock_pulsar_client.assert_called_once_with(**config)
+        
+        # Verify metrics were initialized
+        mock_processor_metrics.assert_called_once()
+        mock_consumer_metrics.assert_called_once()
+        
+        # Verify Consumer was created for config subscription
+        mock_consumer.assert_called_once()
+
+
+if __name__ == '__main__':
+    pytest.main([__file__])

tests/unit/test_base/test_flow_processor.py

@@ -0,0 +1,347 @@
+"""
+Unit tests for trustgraph.base.flow_processor
+Starting small with a single test to verify basic functionality
+"""
+
+import pytest
+from unittest.mock import AsyncMock, MagicMock, patch
+from unittest import IsolatedAsyncioTestCase
+
+# Import the service under test
+from trustgraph.base.flow_processor import FlowProcessor
+
+
+class TestFlowProcessorSimple(IsolatedAsyncioTestCase):
+    """Test FlowProcessor base class functionality"""
+
+    @patch('trustgraph.base.async_processor.AsyncProcessor.__init__')
+    @patch('trustgraph.base.async_processor.AsyncProcessor.register_config_handler')
+    async def test_flow_processor_initialization_basic(self, mock_register_config, mock_async_init):
+        """Test basic FlowProcessor initialization"""
+        # Arrange
+        mock_async_init.return_value = None
+        mock_register_config.return_value = None
+        
+        config = {
+            'id': 'test-flow-processor',
+            'taskgroup': AsyncMock()
+        }
+
+        # Act
+        processor = FlowProcessor(**config)
+
+        # Assert
+        # Verify AsyncProcessor.__init__ was called
+        mock_async_init.assert_called_once()
+        
+        # Verify register_config_handler was called with the correct handler
+        mock_register_config.assert_called_once_with(processor.on_configure_flows)
+        
+        # Verify FlowProcessor-specific initialization
+        assert hasattr(processor, 'flows')
+        assert processor.flows == {}
+        assert hasattr(processor, 'specifications')
+        assert processor.specifications == []
+
+    @patch('trustgraph.base.async_processor.AsyncProcessor.__init__')
+    @patch('trustgraph.base.async_processor.AsyncProcessor.register_config_handler')
+    async def test_register_specification(self, mock_register_config, mock_async_init):
+        """Test registering a specification"""
+        # Arrange
+        mock_async_init.return_value = None
+        mock_register_config.return_value = None
+        
+        config = {
+            'id': 'test-flow-processor',
+            'taskgroup': AsyncMock()
+        }
+
+        processor = FlowProcessor(**config)
+        mock_spec = MagicMock()
+        mock_spec.name = 'test-spec'
+
+        # Act
+        processor.register_specification(mock_spec)
+
+        # Assert
+        assert len(processor.specifications) == 1
+        assert processor.specifications[0] == mock_spec
+
+    @patch('trustgraph.base.flow_processor.Flow')
+    @patch('trustgraph.base.async_processor.AsyncProcessor.__init__')
+    @patch('trustgraph.base.async_processor.AsyncProcessor.register_config_handler')
+    async def test_start_flow(self, mock_register_config, mock_async_init, mock_flow_class):
+        """Test starting a flow"""
+        # Arrange
+        mock_async_init.return_value = None
+        mock_register_config.return_value = None
+        
+        config = {
+            'id': 'test-flow-processor',
+            'taskgroup': AsyncMock()
+        }
+
+        processor = FlowProcessor(**config)
+        processor.id = 'test-processor'  # Set id for Flow creation
+        
+        mock_flow = AsyncMock()
+        mock_flow_class.return_value = mock_flow
+        
+        flow_name = 'test-flow'
+        flow_defn = {'config': 'test-config'}
+
+        # Act
+        await processor.start_flow(flow_name, flow_defn)
+
+        # Assert
+        assert flow_name in processor.flows
+        # Verify Flow was created with correct parameters
+        mock_flow_class.assert_called_once_with('test-processor', flow_name, processor, flow_defn)
+        # Verify the flow's start method was called
+        mock_flow.start.assert_called_once()
+
+    @patch('trustgraph.base.flow_processor.Flow')
+    @patch('trustgraph.base.async_processor.AsyncProcessor.__init__')
+    @patch('trustgraph.base.async_processor.AsyncProcessor.register_config_handler')
+    async def test_stop_flow(self, mock_register_config, mock_async_init, mock_flow_class):
+        """Test stopping a flow"""
+        # Arrange
+        mock_async_init.return_value = None
+        mock_register_config.return_value = None
+        
+        config = {
+            'id': 'test-flow-processor',
+            'taskgroup': AsyncMock()
+        }
+
+        processor = FlowProcessor(**config)
+        processor.id = 'test-processor'
+        
+        mock_flow = AsyncMock()
+        mock_flow_class.return_value = mock_flow
+        
+        flow_name = 'test-flow'
+        flow_defn = {'config': 'test-config'}
+
+        # Start a flow first
+        await processor.start_flow(flow_name, flow_defn)
+        
+        # Act
+        await processor.stop_flow(flow_name)
+
+        # Assert
+        assert flow_name not in processor.flows
+        mock_flow.stop.assert_called_once()
+
+    @patch('trustgraph.base.flow_processor.Flow')
+    @patch('trustgraph.base.async_processor.AsyncProcessor.__init__')
+    @patch('trustgraph.base.async_processor.AsyncProcessor.register_config_handler')
+    async def test_stop_flow_not_exists(self, mock_register_config, mock_async_init, mock_flow_class):
+        """Test stopping a flow that doesn't exist"""
+        # Arrange
+        mock_async_init.return_value = None
+        mock_register_config.return_value = None
+        
+        config = {
+            'id': 'test-flow-processor',
+            'taskgroup': AsyncMock()
+        }
+
+        processor = FlowProcessor(**config)
+        
+        # Act - should not raise an exception
+        await processor.stop_flow('non-existent-flow')
+
+        # Assert - flows dict should still be empty
+        assert processor.flows == {}
+
+    @patch('trustgraph.base.flow_processor.Flow')
+    @patch('trustgraph.base.async_processor.AsyncProcessor.__init__')
+    @patch('trustgraph.base.async_processor.AsyncProcessor.register_config_handler')
+    async def test_on_configure_flows_basic(self, mock_register_config, mock_async_init, mock_flow_class):
+        """Test basic flow configuration handling"""
+        # Arrange
+        mock_async_init.return_value = None
+        mock_register_config.return_value = None
+        
+        config = {
+            'id': 'test-flow-processor',
+            'taskgroup': AsyncMock()
+        }
+
+        processor = FlowProcessor(**config)
+        processor.id = 'test-processor'
+        
+        mock_flow = AsyncMock()
+        mock_flow_class.return_value = mock_flow
+        
+        # Configuration with flows for this processor
+        flow_config = {
+            'test-flow': {'config': 'test-config'}
+        }
+        config_data = {
+            'flows-active': {
+                'test-processor': '{"test-flow": {"config": "test-config"}}'
+            }
+        }
+        
+        # Act
+        await processor.on_configure_flows(config_data, version=1)
+
+        # Assert
+        assert 'test-flow' in processor.flows
+        mock_flow_class.assert_called_once_with('test-processor', 'test-flow', processor, {'config': 'test-config'})
+        mock_flow.start.assert_called_once()
+
+    @patch('trustgraph.base.flow_processor.Flow')
+    @patch('trustgraph.base.async_processor.AsyncProcessor.__init__')
+    @patch('trustgraph.base.async_processor.AsyncProcessor.register_config_handler')
+    async def test_on_configure_flows_no_config(self, mock_register_config, mock_async_init, mock_flow_class):
+        """Test flow configuration handling when no config exists for this processor"""
+        # Arrange
+        mock_async_init.return_value = None
+        mock_register_config.return_value = None
+        
+        config = {
+            'id': 'test-flow-processor',
+            'taskgroup': AsyncMock()
+        }
+
+        processor = FlowProcessor(**config)
+        processor.id = 'test-processor'
+        
+        # Configuration without flows for this processor
+        config_data = {
+            'flows-active': {
+                'other-processor': '{"other-flow": {"config": "other-config"}}'
+            }
+        }
+        
+        # Act
+        await processor.on_configure_flows(config_data, version=1)
+
+        # Assert
+        assert processor.flows == {}
+        mock_flow_class.assert_not_called()
+
+    @patch('trustgraph.base.flow_processor.Flow')
+    @patch('trustgraph.base.async_processor.AsyncProcessor.__init__')
+    @patch('trustgraph.base.async_processor.AsyncProcessor.register_config_handler')
+    async def test_on_configure_flows_invalid_config(self, mock_register_config, mock_async_init, mock_flow_class):
+        """Test flow configuration handling with invalid config format"""
+        # Arrange
+        mock_async_init.return_value = None
+        mock_register_config.return_value = None
+        
+        config = {
+            'id': 'test-flow-processor',
+            'taskgroup': AsyncMock()
+        }
+
+        processor = FlowProcessor(**config)
+        processor.id = 'test-processor'
+        
+        # Configuration without flows-active key
+        config_data = {
+            'other-data': 'some-value'
+        }
+        
+        # Act
+        await processor.on_configure_flows(config_data, version=1)
+
+        # Assert
+        assert processor.flows == {}
+        mock_flow_class.assert_not_called()
+
+    @patch('trustgraph.base.flow_processor.Flow')
+    @patch('trustgraph.base.async_processor.AsyncProcessor.__init__')
+    @patch('trustgraph.base.async_processor.AsyncProcessor.register_config_handler')
+    async def test_on_configure_flows_start_and_stop(self, mock_register_config, mock_async_init, mock_flow_class):
+        """Test flow configuration handling with starting and stopping flows"""
+        # Arrange
+        mock_async_init.return_value = None
+        mock_register_config.return_value = None
+        
+        config = {
+            'id': 'test-flow-processor',
+            'taskgroup': AsyncMock()
+        }
+
+        processor = FlowProcessor(**config)
+        processor.id = 'test-processor'
+        
+        mock_flow1 = AsyncMock()
+        mock_flow2 = AsyncMock()
+        mock_flow_class.side_effect = [mock_flow1, mock_flow2]
+        
+        # First configuration - start flow1
+        config_data1 = {
+            'flows-active': {
+                'test-processor': '{"flow1": {"config": "config1"}}'
+            }
+        }
+        
+        await processor.on_configure_flows(config_data1, version=1)
+        
+        # Second configuration - stop flow1, start flow2
+        config_data2 = {
+            'flows-active': {
+                'test-processor': '{"flow2": {"config": "config2"}}'
+            }
+        }
+        
+        # Act
+        await processor.on_configure_flows(config_data2, version=2)
+
+        # Assert
+        # flow1 should be stopped and removed
+        assert 'flow1' not in processor.flows
+        mock_flow1.stop.assert_called_once()
+        
+        # flow2 should be started and added
+        assert 'flow2' in processor.flows
+        mock_flow2.start.assert_called_once()
+
+    @patch('trustgraph.base.async_processor.AsyncProcessor.__init__')
+    @patch('trustgraph.base.async_processor.AsyncProcessor.register_config_handler')
+    @patch('trustgraph.base.async_processor.AsyncProcessor.start')
+    async def test_start_calls_parent(self, mock_parent_start, mock_register_config, mock_async_init):
+        """Test that start() calls parent start method"""
+        # Arrange
+        mock_async_init.return_value = None
+        mock_register_config.return_value = None
+        mock_parent_start.return_value = None
+        
+        config = {
+            'id': 'test-flow-processor',
+            'taskgroup': AsyncMock()
+        }
+
+        processor = FlowProcessor(**config)
+        
+        # Act
+        await processor.start()
+
+        # Assert
+        mock_parent_start.assert_called_once()
+
+    @patch('trustgraph.base.async_processor.AsyncProcessor.__init__')
+    @patch('trustgraph.base.async_processor.AsyncProcessor.register_config_handler')
+    async def test_add_args_calls_parent(self, mock_register_config, mock_async_init):
+        """Test that add_args() calls parent add_args method"""
+        # Arrange
+        mock_async_init.return_value = None
+        mock_register_config.return_value = None
+        
+        mock_parser = MagicMock()
+        
+        # Act
+        with patch('trustgraph.base.async_processor.AsyncProcessor.add_args') as mock_parent_add_args:
+            FlowProcessor.add_args(mock_parser)
+
+        # Assert
+        mock_parent_add_args.assert_called_once_with(mock_parser)
+
+
+if __name__ == '__main__':
+    pytest.main([__file__])

tests/unit/test_chunking/conftest.py

@@ -0,0 +1,153 @@
+import pytest
+from unittest.mock import AsyncMock, Mock, patch
+from trustgraph.schema import TextDocument, Metadata
+from trustgraph.chunking.recursive.chunker import Processor as RecursiveChunker
+from trustgraph.chunking.token.chunker import Processor as TokenChunker
+from prometheus_client import REGISTRY
+
+
+@pytest.fixture
+def mock_flow():
+    """Mock flow function that returns a mock output producer."""
+    output_mock = AsyncMock()
+    flow_mock = Mock(return_value=output_mock)
+    return flow_mock, output_mock
+
+
+@pytest.fixture
+def mock_consumer():
+    """Mock consumer with test attributes."""
+    consumer = Mock()
+    consumer.id = "test-consumer"
+    consumer.flow = "test-flow"
+    return consumer
+
+
+@pytest.fixture
+def sample_text_document():
+    """Sample document with moderate length text."""
+    metadata = Metadata(
+        id="test-doc-1",
+        metadata=[],
+        user="test-user",
+        collection="test-collection"
+    )
+    text = "The quick brown fox jumps over the lazy dog. " * 20
+    return TextDocument(
+        metadata=metadata,
+        text=text.encode("utf-8")
+    )
+
+
+@pytest.fixture
+def long_text_document():
+    """Long document for testing multiple chunks."""
+    metadata = Metadata(
+        id="test-doc-long",
+        metadata=[],
+        user="test-user",
+        collection="test-collection"
+    )
+    # Create a long text that will definitely be chunked
+    text = " ".join([f"Sentence number {i}. This is part of a long document." for i in range(200)])
+    return TextDocument(
+        metadata=metadata,
+        text=text.encode("utf-8")
+    )
+
+
+@pytest.fixture
+def unicode_text_document():
+    """Document with various unicode characters."""
+    metadata = Metadata(
+        id="test-doc-unicode",
+        metadata=[],
+        user="test-user",
+        collection="test-collection"
+    )
+    text = """
+    English: Hello World!
+    Chinese: 你好世界
+    Japanese: こんにちは世界
+    Korean: 안녕하세요 세계
+    Arabic: مرحبا بالعالم
+    Russian: Привет мир
+    Emoji: 🌍 🌎 🌏 😀 🎉
+    Math: ∑ ∏ ∫ ∞ √ π
+    Symbols: © ® ™ € £ ¥
+    """
+    return TextDocument(
+        metadata=metadata,
+        text=text.encode("utf-8")
+    )
+
+
+@pytest.fixture
+def empty_text_document():
+    """Empty document for edge case testing."""
+    metadata = Metadata(
+        id="test-doc-empty",
+        metadata=[],
+        user="test-user",
+        collection="test-collection"
+    )
+    return TextDocument(
+        metadata=metadata,
+        text=b""
+    )
+
+
+@pytest.fixture
+def mock_message(sample_text_document):
+    """Mock message containing a document."""
+    msg = Mock()
+    msg.value.return_value = sample_text_document
+    return msg
+
+
+@pytest.fixture(autouse=True)
+def clear_metrics():
+    """Clear metrics before each test to avoid duplicates."""
+    # Clear the chunk_metric class attribute if it exists
+    if hasattr(RecursiveChunker, 'chunk_metric'):
+        # Unregister from Prometheus registry first
+        try:
+            REGISTRY.unregister(RecursiveChunker.chunk_metric)
+        except KeyError:
+            pass  # Already unregistered
+        delattr(RecursiveChunker, 'chunk_metric')
+    if hasattr(TokenChunker, 'chunk_metric'):
+        try:
+            REGISTRY.unregister(TokenChunker.chunk_metric)
+        except KeyError:
+            pass  # Already unregistered
+        delattr(TokenChunker, 'chunk_metric')
+    yield
+    # Clean up after test as well
+    if hasattr(RecursiveChunker, 'chunk_metric'):
+        try:
+            REGISTRY.unregister(RecursiveChunker.chunk_metric)
+        except KeyError:
+            pass
+        delattr(RecursiveChunker, 'chunk_metric')
+    if hasattr(TokenChunker, 'chunk_metric'):
+        try:
+            REGISTRY.unregister(TokenChunker.chunk_metric)
+        except KeyError:
+            pass
+        delattr(TokenChunker, 'chunk_metric')
+
+
+@pytest.fixture
+def mock_async_processor_init():
+    """Mock AsyncProcessor.__init__ to avoid taskgroup requirement."""
+    def init_mock(self, **kwargs):
+        # Set attributes that AsyncProcessor would normally set
+        self.config_handlers = []
+        self.specifications = []
+        self.flows = {}
+        self.id = kwargs.get('id', 'test-processor')
+        # Don't call the real __init__
+    
+    with patch('trustgraph.base.async_processor.AsyncProcessor.__init__', init_mock):
+        yield

tests/unit/test_chunking/test_recursive_chunker.py

@@ -0,0 +1,211 @@
+import pytest
+import asyncio
+from unittest.mock import AsyncMock, Mock, patch, MagicMock
+from trustgraph.schema import TextDocument, Chunk, Metadata
+from trustgraph.chunking.recursive.chunker import Processor as RecursiveChunker
+
+
+@pytest.fixture
+def mock_flow():
+    output_mock = AsyncMock()
+    flow_mock = Mock(return_value=output_mock)
+    return flow_mock, output_mock
+
+
+@pytest.fixture
+def mock_consumer():
+    consumer = Mock()
+    consumer.id = "test-consumer"
+    consumer.flow = "test-flow"
+    return consumer
+
+
+@pytest.fixture
+def sample_document():
+    metadata = Metadata(
+        id="test-doc-1",
+        metadata=[],
+        user="test-user",
+        collection="test-collection"
+    )
+    text = "This is a test document. " * 100  # Create text long enough to be chunked
+    return TextDocument(
+        metadata=metadata,
+        text=text.encode("utf-8")
+    )
+
+
+@pytest.fixture
+def short_document():
+    metadata = Metadata(
+        id="test-doc-2",
+        metadata=[],
+        user="test-user",
+        collection="test-collection"
+    )
+    text = "This is a very short document."
+    return TextDocument(
+        metadata=metadata,
+        text=text.encode("utf-8")
+    )
+
+
+class TestRecursiveChunker:
+    
+    def test_init_default_params(self, mock_async_processor_init):
+        processor = RecursiveChunker()
+        assert processor.text_splitter._chunk_size == 2000
+        assert processor.text_splitter._chunk_overlap == 100
+        
+    def test_init_custom_params(self, mock_async_processor_init):
+        processor = RecursiveChunker(chunk_size=500, chunk_overlap=50)
+        assert processor.text_splitter._chunk_size == 500
+        assert processor.text_splitter._chunk_overlap == 50
+        
+    def test_init_with_id(self, mock_async_processor_init):
+        processor = RecursiveChunker(id="custom-chunker")
+        assert processor.id == "custom-chunker"
+        
+    @pytest.mark.asyncio
+    async def test_on_message_single_chunk(self, mock_async_processor_init, mock_flow, mock_consumer, short_document):
+        flow_mock, output_mock = mock_flow
+        processor = RecursiveChunker(chunk_size=2000, chunk_overlap=100)
+        
+        msg = Mock()
+        msg.value.return_value = short_document
+        
+        await processor.on_message(msg, mock_consumer, flow_mock)
+        
+        # Should produce exactly one chunk for short text
+        assert output_mock.send.call_count == 1
+        
+        # Verify the chunk was created correctly
+        chunk_call = output_mock.send.call_args[0][0]
+        assert isinstance(chunk_call, Chunk)
+        assert chunk_call.metadata == short_document.metadata
+        assert chunk_call.chunk.decode("utf-8") == short_document.text.decode("utf-8")
+        
+    @pytest.mark.asyncio
+    async def test_on_message_multiple_chunks(self, mock_async_processor_init, mock_flow, mock_consumer, sample_document):
+        flow_mock, output_mock = mock_flow
+        processor = RecursiveChunker(chunk_size=100, chunk_overlap=20)
+        
+        msg = Mock()
+        msg.value.return_value = sample_document
+        
+        await processor.on_message(msg, mock_consumer, flow_mock)
+        
+        # Should produce multiple chunks
+        assert output_mock.send.call_count > 1
+        
+        # Verify all chunks have correct metadata
+        for call in output_mock.send.call_args_list:
+            chunk = call[0][0]
+            assert isinstance(chunk, Chunk)
+            assert chunk.metadata == sample_document.metadata
+            assert len(chunk.chunk) > 0
+            
+    @pytest.mark.asyncio
+    async def test_on_message_chunk_overlap(self, mock_async_processor_init, mock_flow, mock_consumer):
+        flow_mock, output_mock = mock_flow
+        processor = RecursiveChunker(chunk_size=50, chunk_overlap=10)
+        
+        # Create a document with predictable content
+        metadata = Metadata(id="test", metadata=[], user="test-user", collection="test-collection")
+        text = "ABCDEFGHIJ" * 10  # 100 characters
+        document = TextDocument(metadata=metadata, text=text.encode("utf-8"))
+        
+        msg = Mock()
+        msg.value.return_value = document
+        
+        await processor.on_message(msg, mock_consumer, flow_mock)
+        
+        # Collect all chunks
+        chunks = []
+        for call in output_mock.send.call_args_list:
+            chunk_text = call[0][0].chunk.decode("utf-8")
+            chunks.append(chunk_text)
+            
+        # Verify chunks have expected overlap
+        for i in range(len(chunks) - 1):
+            # The end of chunk i should overlap with the beginning of chunk i+1
+            # Check if there's some overlap (exact overlap depends on text splitter logic)
+            assert len(chunks[i]) <= 50 + 10  # chunk_size + some tolerance
+            
+    @pytest.mark.asyncio
+    async def test_on_message_empty_document(self, mock_async_processor_init, mock_flow, mock_consumer):
+        flow_mock, output_mock = mock_flow
+        processor = RecursiveChunker()
+        
+        metadata = Metadata(id="empty", metadata=[], user="test-user", collection="test-collection")
+        document = TextDocument(metadata=metadata, text=b"")
+        
+        msg = Mock()
+        msg.value.return_value = document
+        
+        await processor.on_message(msg, mock_consumer, flow_mock)
+        
+        # Empty documents typically don't produce chunks with langchain splitters
+        # This behavior is expected - no chunks should be produced
+        assert output_mock.send.call_count == 0
+        
+    @pytest.mark.asyncio
+    async def test_on_message_unicode_handling(self, mock_async_processor_init, mock_flow, mock_consumer):
+        flow_mock, output_mock = mock_flow
+        processor = RecursiveChunker(chunk_size=500, chunk_overlap=20)  # Fixed overlap < chunk_size
+        
+        metadata = Metadata(id="unicode", metadata=[], user="test-user", collection="test-collection")
+        text = "Hello 世界! 🌍 This is a test with émojis and spëcial characters."
+        document = TextDocument(metadata=metadata, text=text.encode("utf-8"))
+        
+        msg = Mock()
+        msg.value.return_value = document
+        
+        await processor.on_message(msg, mock_consumer, flow_mock)
+        
+        # Verify unicode is preserved correctly
+        all_chunks = []
+        for call in output_mock.send.call_args_list:
+            chunk_text = call[0][0].chunk.decode("utf-8")
+            all_chunks.append(chunk_text)
+            
+        # Reconstruct text (approximately, due to overlap)
+        reconstructed = "".join(all_chunks)
+        assert "世界" in reconstructed
+        assert "🌍" in reconstructed
+        assert "émojis" in reconstructed
+        
+    @pytest.mark.asyncio
+    async def test_metrics_recorded(self, mock_async_processor_init, mock_flow, mock_consumer, sample_document):
+        flow_mock, output_mock = mock_flow
+        processor = RecursiveChunker(chunk_size=100)
+        
+        msg = Mock()
+        msg.value.return_value = sample_document
+        
+        # Mock the metric
+        with patch.object(RecursiveChunker.chunk_metric, 'labels') as mock_labels:
+            mock_observe = Mock()
+            mock_labels.return_value.observe = mock_observe
+            
+            await processor.on_message(msg, mock_consumer, flow_mock)
+            
+            # Verify metrics were recorded
+            mock_labels.assert_called_with(id="test-consumer", flow="test-flow")
+            assert mock_observe.call_count > 0
+            
+            # Verify chunk sizes were observed
+            for call in mock_observe.call_args_list:
+                chunk_size = call[0][0]
+                assert chunk_size > 0
+                
+    def test_add_args(self):
+        parser = Mock()
+        RecursiveChunker.add_args(parser)
+        
+        # Verify arguments were added
+        calls = parser.add_argument.call_args_list
+        arg_names = [call[0][0] for call in calls]
+        
+        assert '-z' in arg_names or '--chunk-size' in arg_names
+        assert '-v' in arg_names or '--chunk-overlap' in arg_names

tests/unit/test_chunking/test_token_chunker.py

@@ -0,0 +1,275 @@
+import pytest
+import asyncio
+from unittest.mock import AsyncMock, Mock, patch
+from trustgraph.schema import TextDocument, Chunk, Metadata
+from trustgraph.chunking.token.chunker import Processor as TokenChunker
+
+
+@pytest.fixture
+def mock_flow():
+    output_mock = AsyncMock()
+    flow_mock = Mock(return_value=output_mock)
+    return flow_mock, output_mock
+
+
+@pytest.fixture
+def mock_consumer():
+    consumer = Mock()
+    consumer.id = "test-consumer"
+    consumer.flow = "test-flow"
+    return consumer
+
+
+@pytest.fixture
+def sample_document():
+    metadata = Metadata(
+        id="test-doc-1",
+        metadata=[],
+        user="test-user",
+        collection="test-collection"
+    )
+    # Create text that will result in multiple token chunks
+    text = "The quick brown fox jumps over the lazy dog. " * 50
+    return TextDocument(
+        metadata=metadata,
+        text=text.encode("utf-8")
+    )
+
+
+@pytest.fixture
+def short_document():
+    metadata = Metadata(
+        id="test-doc-2",
+        metadata=[],
+        user="test-user",
+        collection="test-collection"
+    )
+    text = "Short text."
+    return TextDocument(
+        metadata=metadata,
+        text=text.encode("utf-8")
+    )
+
+
+class TestTokenChunker:
+    
+    def test_init_default_params(self, mock_async_processor_init):
+        processor = TokenChunker()
+        assert processor.text_splitter._chunk_size == 250
+        assert processor.text_splitter._chunk_overlap == 15
+        # Just verify the text splitter was created (encoding verification is complex)
+        assert processor.text_splitter is not None
+        assert hasattr(processor.text_splitter, 'split_text')
+        
+    def test_init_custom_params(self, mock_async_processor_init):
+        processor = TokenChunker(chunk_size=100, chunk_overlap=10)
+        assert processor.text_splitter._chunk_size == 100
+        assert processor.text_splitter._chunk_overlap == 10
+        
+    def test_init_with_id(self, mock_async_processor_init):
+        processor = TokenChunker(id="custom-token-chunker")
+        assert processor.id == "custom-token-chunker"
+        
+    @pytest.mark.asyncio
+    async def test_on_message_single_chunk(self, mock_async_processor_init, mock_flow, mock_consumer, short_document):
+        flow_mock, output_mock = mock_flow
+        processor = TokenChunker(chunk_size=250, chunk_overlap=15)
+        
+        msg = Mock()
+        msg.value.return_value = short_document
+        
+        await processor.on_message(msg, mock_consumer, flow_mock)
+        
+        # Short text should produce exactly one chunk
+        assert output_mock.send.call_count == 1
+        
+        # Verify the chunk was created correctly
+        chunk_call = output_mock.send.call_args[0][0]
+        assert isinstance(chunk_call, Chunk)
+        assert chunk_call.metadata == short_document.metadata
+        assert chunk_call.chunk.decode("utf-8") == short_document.text.decode("utf-8")
+        
+    @pytest.mark.asyncio
+    async def test_on_message_multiple_chunks(self, mock_async_processor_init, mock_flow, mock_consumer, sample_document):
+        flow_mock, output_mock = mock_flow
+        processor = TokenChunker(chunk_size=50, chunk_overlap=5)
+        
+        msg = Mock()
+        msg.value.return_value = sample_document
+        
+        await processor.on_message(msg, mock_consumer, flow_mock)
+        
+        # Should produce multiple chunks
+        assert output_mock.send.call_count > 1
+        
+        # Verify all chunks have correct metadata
+        for call in output_mock.send.call_args_list:
+            chunk = call[0][0]
+            assert isinstance(chunk, Chunk)
+            assert chunk.metadata == sample_document.metadata
+            assert len(chunk.chunk) > 0
+            
+    @pytest.mark.asyncio
+    async def test_on_message_token_overlap(self, mock_async_processor_init, mock_flow, mock_consumer):
+        flow_mock, output_mock = mock_flow
+        processor = TokenChunker(chunk_size=20, chunk_overlap=5)
+        
+        # Create a document with repeated pattern
+        metadata = Metadata(id="test", metadata=[], user="test-user", collection="test-collection")
+        text = "one two three four five six seven eight nine ten " * 5
+        document = TextDocument(metadata=metadata, text=text.encode("utf-8"))
+        
+        msg = Mock()
+        msg.value.return_value = document
+        
+        await processor.on_message(msg, mock_consumer, flow_mock)
+        
+        # Collect all chunks
+        chunks = []
+        for call in output_mock.send.call_args_list:
+            chunk_text = call[0][0].chunk.decode("utf-8")
+            chunks.append(chunk_text)
+            
+        # Should have multiple chunks
+        assert len(chunks) > 1
+        
+        # Verify chunks are not empty
+        for chunk in chunks:
+            assert len(chunk) > 0
+            
+    @pytest.mark.asyncio
+    async def test_on_message_empty_document(self, mock_async_processor_init, mock_flow, mock_consumer):
+        flow_mock, output_mock = mock_flow
+        processor = TokenChunker()
+        
+        metadata = Metadata(id="empty", metadata=[], user="test-user", collection="test-collection")
+        document = TextDocument(metadata=metadata, text=b"")
+        
+        msg = Mock()
+        msg.value.return_value = document
+        
+        await processor.on_message(msg, mock_consumer, flow_mock)
+        
+        # Empty documents typically don't produce chunks with langchain splitters
+        # This behavior is expected - no chunks should be produced
+        assert output_mock.send.call_count == 0
+        
+    @pytest.mark.asyncio
+    async def test_on_message_unicode_handling(self, mock_async_processor_init, mock_flow, mock_consumer):
+        flow_mock, output_mock = mock_flow
+        processor = TokenChunker(chunk_size=50)
+        
+        metadata = Metadata(id="unicode", metadata=[], user="test-user", collection="test-collection")
+        # Test with various unicode characters
+        text = "Hello 世界! 🌍 Test émojis café naïve résumé. Greek: αβγδε Hebrew: אבגדה"
+        document = TextDocument(metadata=metadata, text=text.encode("utf-8"))
+        
+        msg = Mock()
+        msg.value.return_value = document
+        
+        await processor.on_message(msg, mock_consumer, flow_mock)
+        
+        # Verify unicode is preserved correctly
+        all_chunks = []
+        for call in output_mock.send.call_args_list:
+            chunk_text = call[0][0].chunk.decode("utf-8")
+            all_chunks.append(chunk_text)
+            
+        # Reconstruct text
+        reconstructed = "".join(all_chunks)
+        assert "世界" in reconstructed
+        assert "🌍" in reconstructed
+        assert "émojis" in reconstructed
+        assert "αβγδε" in reconstructed
+        assert "אבגדה" in reconstructed
+        
+    @pytest.mark.asyncio
+    async def test_on_message_token_boundary_preservation(self, mock_async_processor_init, mock_flow, mock_consumer):
+        flow_mock, output_mock = mock_flow
+        processor = TokenChunker(chunk_size=10, chunk_overlap=2)
+        
+        metadata = Metadata(id="boundary", metadata=[], user="test-user", collection="test-collection")
+        # Text with clear word boundaries
+        text = "This is a test of token boundaries and proper splitting."
+        document = TextDocument(metadata=metadata, text=text.encode("utf-8"))
+        
+        msg = Mock()
+        msg.value.return_value = document
+        
+        await processor.on_message(msg, mock_consumer, flow_mock)
+        
+        # Collect all chunks
+        chunks = []
+        for call in output_mock.send.call_args_list:
+            chunk_text = call[0][0].chunk.decode("utf-8")
+            chunks.append(chunk_text)
+            
+        # Token chunker should respect token boundaries
+        for chunk in chunks:
+            # Chunks should not start or end with partial words (in most cases)
+            assert len(chunk.strip()) > 0
+            
+    @pytest.mark.asyncio
+    async def test_metrics_recorded(self, mock_async_processor_init, mock_flow, mock_consumer, sample_document):
+        flow_mock, output_mock = mock_flow
+        processor = TokenChunker(chunk_size=50)
+        
+        msg = Mock()
+        msg.value.return_value = sample_document
+        
+        # Mock the metric
+        with patch.object(TokenChunker.chunk_metric, 'labels') as mock_labels:
+            mock_observe = Mock()
+            mock_labels.return_value.observe = mock_observe
+            
+            await processor.on_message(msg, mock_consumer, flow_mock)
+            
+            # Verify metrics were recorded
+            mock_labels.assert_called_with(id="test-consumer", flow="test-flow")
+            assert mock_observe.call_count > 0
+            
+            # Verify chunk sizes were observed
+            for call in mock_observe.call_args_list:
+                chunk_size = call[0][0]
+                assert chunk_size > 0
+                
+    def test_add_args(self):
+        parser = Mock()
+        TokenChunker.add_args(parser)
+        
+        # Verify arguments were added
+        calls = parser.add_argument.call_args_list
+        arg_names = [call[0][0] for call in calls]
+        
+        assert '-z' in arg_names or '--chunk-size' in arg_names
+        assert '-v' in arg_names or '--chunk-overlap' in arg_names
+        
+    @pytest.mark.asyncio
+    async def test_encoding_specific_behavior(self, mock_async_processor_init, mock_flow, mock_consumer):
+        flow_mock, output_mock = mock_flow
+        processor = TokenChunker(chunk_size=10, chunk_overlap=0)
+        
+        metadata = Metadata(id="encoding", metadata=[], user="test-user", collection="test-collection")
+        # Test text that might tokenize differently with cl100k_base encoding
+        text = "GPT-4 is an AI model. It uses tokens."
+        document = TextDocument(metadata=metadata, text=text.encode("utf-8"))
+        
+        msg = Mock()
+        msg.value.return_value = document
+        
+        await processor.on_message(msg, mock_consumer, flow_mock)
+        
+        # Verify chunking happened
+        assert output_mock.send.call_count >= 1
+        
+        # Collect all chunks
+        chunks = []
+        for call in output_mock.send.call_args_list:
+            chunk_text = call[0][0].chunk.decode("utf-8")
+            chunks.append(chunk_text)
+            
+        # Verify all text is preserved (allowing for overlap)
+        all_text = " ".join(chunks)
+        assert "GPT-4" in all_text
+        assert "AI model" in all_text
+        assert "tokens" in all_text

tests/unit/test_cli/__init__.py

@@ -0,0 +1,3 @@
+"""
+Unit tests for CLI modules.
+"""

tests/unit/test_cli/conftest.py

@@ -0,0 +1,48 @@
+"""
+Shared fixtures for CLI unit tests.
+"""
+
+import pytest
+from unittest.mock import AsyncMock, MagicMock
+
+
+@pytest.fixture
+def mock_websocket_connection():
+    """Mock WebSocket connection for CLI tools."""
+    mock_ws = MagicMock()
+    
+    # Create simple async functions that don't leave coroutines hanging
+    async def mock_send(data):
+        return None
+        
+    async def mock_recv():
+        return ""
+        
+    async def mock_close():
+        return None
+    
+    mock_ws.send = mock_send
+    mock_ws.recv = mock_recv
+    mock_ws.close = mock_close
+    return mock_ws
+
+
+@pytest.fixture
+def mock_pulsar_client():
+    """Mock Pulsar client for CLI tools that use messaging."""
+    mock_client = MagicMock()
+    mock_client.create_consumer = MagicMock()
+    mock_client.create_producer = MagicMock()
+    mock_client.close = MagicMock()
+    return mock_client
+
+
+@pytest.fixture
+def sample_metadata():
+    """Sample metadata structure used across CLI tools."""
+    return {
+        "id": "test-doc-123",
+        "metadata": [],
+        "user": "test-user",
+        "collection": "test-collection"
+    }

tests/unit/test_cli/test_load_knowledge.py

@@ -0,0 +1,479 @@
+"""
+Unit tests for the load_knowledge CLI module.
+
+Tests the business logic of loading triples and entity contexts from Turtle files
+while mocking WebSocket connections and external dependencies.
+"""
+
+import pytest
+import json
+import tempfile
+import asyncio
+from unittest.mock import AsyncMock, Mock, patch, mock_open, MagicMock
+from pathlib import Path
+
+from trustgraph.cli.load_knowledge import KnowledgeLoader, main
+
+
+@pytest.fixture
+def sample_turtle_content():
+    """Sample Turtle RDF content for testing."""
+    return """
+@prefix ex: <http://example.org/> .
+@prefix foaf: <http://xmlns.com/foaf/0.1/> .
+
+ex:john foaf:name "John Smith" ;
+        foaf:age "30" ;
+        foaf:knows ex:mary .
+
+ex:mary foaf:name "Mary Johnson" ;
+        foaf:email "mary@example.com" .
+"""
+
+
+@pytest.fixture
+def temp_turtle_file(sample_turtle_content):
+    """Create a temporary Turtle file for testing."""
+    with tempfile.NamedTemporaryFile(mode='w', suffix='.ttl', delete=False) as f:
+        f.write(sample_turtle_content)
+        f.flush()
+        yield f.name
+    
+    # Cleanup
+    Path(f.name).unlink(missing_ok=True)
+
+
+@pytest.fixture
+def mock_websocket():
+    """Mock WebSocket connection."""
+    mock_ws = MagicMock()
+    
+    async def async_send(data):
+        return None
+    
+    async def async_recv():
+        return ""
+        
+    async def async_close():
+        return None
+    
+    mock_ws.send = Mock(side_effect=async_send)
+    mock_ws.recv = Mock(side_effect=async_recv) 
+    mock_ws.close = Mock(side_effect=async_close)
+    return mock_ws
+
+
+@pytest.fixture
+def knowledge_loader():
+    """Create a KnowledgeLoader instance with test parameters."""
+    return KnowledgeLoader(
+        files=["test.ttl"],
+        flow="test-flow",
+        user="test-user", 
+        collection="test-collection",
+        document_id="test-doc-123",
+        url="ws://test.example.com/"
+    )
+
+
+class TestKnowledgeLoader:
+    """Test the KnowledgeLoader class business logic."""
+
+    def test_init_constructs_urls_correctly(self):
+        """Test that URLs are constructed properly."""
+        loader = KnowledgeLoader(
+            files=["test.ttl"],
+            flow="my-flow",
+            user="user1",
+            collection="col1", 
+            document_id="doc1",
+            url="ws://example.com/"
+        )
+        
+        assert loader.triples_url == "ws://example.com/api/v1/flow/my-flow/import/triples"
+        assert loader.entity_contexts_url == "ws://example.com/api/v1/flow/my-flow/import/entity-contexts"
+        assert loader.user == "user1"
+        assert loader.collection == "col1"
+        assert loader.document_id == "doc1"
+
+    def test_init_adds_trailing_slash(self):
+        """Test that trailing slash is added to URL if missing."""
+        loader = KnowledgeLoader(
+            files=["test.ttl"],
+            flow="my-flow", 
+            user="user1",
+            collection="col1",
+            document_id="doc1",
+            url="ws://example.com"  # No trailing slash
+        )
+        
+        assert loader.triples_url == "ws://example.com/api/v1/flow/my-flow/import/triples"
+
+    @pytest.mark.asyncio
+    async def test_load_triples_sends_correct_messages(self, temp_turtle_file, mock_websocket):
+        """Test that triple loading sends correctly formatted messages."""
+        loader = KnowledgeLoader(
+            files=[temp_turtle_file],
+            flow="test-flow",
+            user="test-user",
+            collection="test-collection", 
+            document_id="test-doc"
+        )
+        
+        await loader.load_triples(temp_turtle_file, mock_websocket)
+        
+        # Verify WebSocket send was called
+        assert mock_websocket.send.call_count > 0
+        
+        # Check message format for one of the calls
+        sent_messages = [json.loads(call.args[0]) for call in mock_websocket.send.call_args_list]
+        
+        # Verify message structure
+        sample_message = sent_messages[0]
+        assert "metadata" in sample_message
+        assert "triples" in sample_message
+        
+        metadata = sample_message["metadata"]
+        assert metadata["id"] == "test-doc"
+        assert metadata["user"] == "test-user"
+        assert metadata["collection"] == "test-collection"
+        assert isinstance(metadata["metadata"], list)
+        
+        triple = sample_message["triples"][0]
+        assert "s" in triple
+        assert "p" in triple
+        assert "o" in triple
+        
+        # Check Value structure
+        assert "v" in triple["s"]
+        assert "e" in triple["s"]
+        assert triple["s"]["e"] is True  # Subject should be URI
+
+    @pytest.mark.asyncio
+    async def test_load_entity_contexts_processes_literals_only(self, temp_turtle_file, mock_websocket):
+        """Test that entity contexts are created only for literals."""
+        loader = KnowledgeLoader(
+            files=[temp_turtle_file],
+            flow="test-flow",
+            user="test-user",
+            collection="test-collection",
+            document_id="test-doc"
+        )
+        
+        await loader.load_entity_contexts(temp_turtle_file, mock_websocket)
+        
+        # Get all sent messages
+        sent_messages = [json.loads(call.args[0]) for call in mock_websocket.send.call_args_list]
+        
+        # Verify we got entity context messages
+        assert len(sent_messages) > 0
+        
+        for message in sent_messages:
+            assert "metadata" in message
+            assert "entities" in message
+            
+            metadata = message["metadata"]
+            assert metadata["id"] == "test-doc"
+            assert metadata["user"] == "test-user"
+            assert metadata["collection"] == "test-collection"
+            
+            entity_context = message["entities"][0]
+            assert "entity" in entity_context
+            assert "context" in entity_context
+            
+            entity = entity_context["entity"]
+            assert "v" in entity
+            assert "e" in entity
+            assert entity["e"] is True  # Entity should be URI (subject)
+            
+            # Context should be a string (the literal value)
+            assert isinstance(entity_context["context"], str)
+
+    @pytest.mark.asyncio 
+    async def test_load_entity_contexts_skips_uri_objects(self, mock_websocket):
+        """Test that URI objects don't generate entity contexts."""
+        # Create turtle with only URI objects (no literals)
+        turtle_content = """
+@prefix ex: <http://example.org/> .
+ex:john ex:knows ex:mary .
+ex:mary ex:knows ex:bob .
+"""
+        
+        with tempfile.NamedTemporaryFile(mode='w', suffix='.ttl', delete=False) as f:
+            f.write(turtle_content)
+            f.flush()
+            
+            loader = KnowledgeLoader(
+                files=[f.name],
+                flow="test-flow",
+                user="test-user", 
+                collection="test-collection",
+                document_id="test-doc"
+            )
+            
+            await loader.load_entity_contexts(f.name, mock_websocket)
+            
+        Path(f.name).unlink(missing_ok=True)
+        
+        # Should not send any messages since there are no literals
+        mock_websocket.send.assert_not_called()
+
+    @pytest.mark.asyncio
+    @patch('trustgraph.cli.load_knowledge.connect')
+    async def test_run_calls_both_loaders(self, mock_connect, knowledge_loader, temp_turtle_file):
+        """Test that run() calls both triple and entity context loaders."""
+        knowledge_loader.files = [temp_turtle_file]
+        
+        # Create a simple mock websocket
+        mock_ws = MagicMock()
+        async def mock_send(data):
+            pass
+        mock_ws.send = mock_send
+        
+        # Create async context manager mock
+        async def mock_aenter(self):
+            return mock_ws
+            
+        async def mock_aexit(self, exc_type, exc_val, exc_tb):
+            return None
+            
+        mock_connection = MagicMock()
+        mock_connection.__aenter__ = mock_aenter
+        mock_connection.__aexit__ = mock_aexit
+        mock_connect.return_value = mock_connection
+        
+        # Create AsyncMock objects that can track calls properly
+        mock_load_triples = AsyncMock(return_value=None)
+        mock_load_contexts = AsyncMock(return_value=None)
+        
+        with patch.object(knowledge_loader, 'load_triples', mock_load_triples), \
+             patch.object(knowledge_loader, 'load_entity_contexts', mock_load_contexts):
+            
+            await knowledge_loader.run()
+            
+            # Verify both methods were called
+            mock_load_triples.assert_called_once_with(temp_turtle_file, mock_ws)
+            mock_load_contexts.assert_called_once_with(temp_turtle_file, mock_ws)
+            
+            # Verify WebSocket connections were made to both URLs
+            assert mock_connect.call_count == 2
+
+
+class TestCLIArgumentParsing:
+    """Test CLI argument parsing and main function."""
+
+    @patch('trustgraph.cli.load_knowledge.KnowledgeLoader')
+    @patch('trustgraph.cli.load_knowledge.asyncio.run')
+    def test_main_parses_args_correctly(self, mock_asyncio_run, mock_loader_class):
+        """Test that main() parses arguments correctly."""
+        mock_loader_instance = MagicMock()
+        mock_loader_class.return_value = mock_loader_instance
+        
+        test_args = [
+            'tg-load-knowledge',
+            '-i', 'doc-123',
+            '-f', 'my-flow', 
+            '-U', 'my-user',
+            '-C', 'my-collection',
+            '-u', 'ws://custom.example.com/',
+            'file1.ttl',
+            'file2.ttl'
+        ]
+        
+        with patch('sys.argv', test_args):
+            main()
+        
+        # Verify KnowledgeLoader was instantiated with correct args
+        mock_loader_class.assert_called_once_with(
+            document_id='doc-123',
+            url='ws://custom.example.com/',
+            flow='my-flow',
+            files=['file1.ttl', 'file2.ttl'],
+            user='my-user',
+            collection='my-collection'
+        )
+        
+        # Verify asyncio.run was called once
+        mock_asyncio_run.assert_called_once()
+
+    @patch('trustgraph.cli.load_knowledge.KnowledgeLoader')
+    @patch('trustgraph.cli.load_knowledge.asyncio.run')
+    def test_main_uses_defaults(self, mock_asyncio_run, mock_loader_class):
+        """Test that main() uses default values when not specified."""
+        mock_loader_instance = MagicMock()
+        mock_loader_class.return_value = mock_loader_instance
+        
+        test_args = [
+            'tg-load-knowledge',
+            '-i', 'doc-123',
+            'file1.ttl'
+        ]
+        
+        with patch('sys.argv', test_args):
+            main()
+        
+        # Verify defaults were used
+        call_args = mock_loader_class.call_args[1]
+        assert call_args['flow'] == 'default'
+        assert call_args['user'] == 'trustgraph'
+        assert call_args['collection'] == 'default'
+        assert call_args['url'] == 'ws://localhost:8088/'
+
+
+class TestErrorHandling:
+    """Test error handling scenarios."""
+
+    @pytest.mark.asyncio
+    async def test_load_triples_handles_invalid_turtle(self, mock_websocket):
+        """Test handling of invalid Turtle content."""
+        # Create file with invalid Turtle content
+        with tempfile.NamedTemporaryFile(mode='w', suffix='.ttl', delete=False) as f:
+            f.write("Invalid Turtle Content {{{")
+            f.flush()
+            
+            loader = KnowledgeLoader(
+                files=[f.name],
+                flow="test-flow",
+                user="test-user",
+                collection="test-collection",
+                document_id="test-doc"
+            )
+            
+            # Should raise an exception for invalid Turtle
+            with pytest.raises(Exception):
+                await loader.load_triples(f.name, mock_websocket)
+                
+        Path(f.name).unlink(missing_ok=True)
+
+    @pytest.mark.asyncio
+    async def test_load_entity_contexts_handles_invalid_turtle(self, mock_websocket):
+        """Test handling of invalid Turtle content in entity contexts."""
+        # Create file with invalid Turtle content
+        with tempfile.NamedTemporaryFile(mode='w', suffix='.ttl', delete=False) as f:
+            f.write("Invalid Turtle Content {{{")
+            f.flush()
+            
+            loader = KnowledgeLoader(
+                files=[f.name],
+                flow="test-flow",
+                user="test-user", 
+                collection="test-collection",
+                document_id="test-doc"
+            )
+            
+            # Should raise an exception for invalid Turtle
+            with pytest.raises(Exception):
+                await loader.load_entity_contexts(f.name, mock_websocket)
+                
+        Path(f.name).unlink(missing_ok=True)
+
+    @pytest.mark.asyncio
+    @patch('trustgraph.cli.load_knowledge.connect')
+    @patch('builtins.print')  # Mock print to avoid output during tests
+    async def test_run_handles_connection_errors(self, mock_print, mock_connect, knowledge_loader, temp_turtle_file):
+        """Test handling of WebSocket connection errors."""
+        knowledge_loader.files = [temp_turtle_file]
+        
+        # Mock connection failure
+        mock_connect.side_effect = ConnectionError("Failed to connect")
+        
+        # Should not raise exception, just print error
+        await knowledge_loader.run()
+
+    @patch('trustgraph.cli.load_knowledge.KnowledgeLoader')
+    @patch('trustgraph.cli.load_knowledge.asyncio.run')
+    @patch('trustgraph.cli.load_knowledge.time.sleep')
+    @patch('builtins.print')  # Mock print to avoid output during tests
+    def test_main_retries_on_exception(self, mock_print, mock_sleep, mock_asyncio_run, mock_loader_class):
+        """Test that main() retries on exceptions."""
+        mock_loader_instance = MagicMock()
+        mock_loader_class.return_value = mock_loader_instance
+        
+        # First call raises exception, second succeeds
+        mock_asyncio_run.side_effect = [Exception("Test error"), None]
+        
+        test_args = [
+            'tg-load-knowledge',
+            '-i', 'doc-123', 
+            'file1.ttl'
+        ]
+        
+        with patch('sys.argv', test_args):
+            main()
+        
+        # Should have been called twice (first failed, second succeeded)
+        assert mock_asyncio_run.call_count == 2
+        mock_sleep.assert_called_once_with(10)
+
+
+class TestDataValidation:
+    """Test data validation and edge cases."""
+
+    @pytest.mark.asyncio
+    async def test_empty_turtle_file(self, mock_websocket):
+        """Test handling of empty Turtle files."""
+        with tempfile.NamedTemporaryFile(mode='w', suffix='.ttl', delete=False) as f:
+            f.write("")  # Empty file
+            f.flush()
+            
+            loader = KnowledgeLoader(
+                files=[f.name],
+                flow="test-flow",
+                user="test-user",
+                collection="test-collection",
+                document_id="test-doc"
+            )
+            
+            await loader.load_triples(f.name, mock_websocket)
+            await loader.load_entity_contexts(f.name, mock_websocket)
+            
+            # Should not send any messages for empty file
+            mock_websocket.send.assert_not_called()
+            
+        Path(f.name).unlink(missing_ok=True)
+
+    @pytest.mark.asyncio
+    async def test_turtle_with_mixed_literals_and_uris(self, mock_websocket):
+        """Test handling of Turtle with mixed literal and URI objects."""
+        turtle_content = """
+@prefix ex: <http://example.org/> .
+ex:john ex:name "John Smith" ;
+        ex:age "25" ;
+        ex:knows ex:mary ;
+        ex:city "New York" .
+ex:mary ex:name "Mary Johnson" .
+"""
+        
+        with tempfile.NamedTemporaryFile(mode='w', suffix='.ttl', delete=False) as f:
+            f.write(turtle_content)
+            f.flush()
+            
+            loader = KnowledgeLoader(
+                files=[f.name],
+                flow="test-flow",
+                user="test-user",
+                collection="test-collection", 
+                document_id="test-doc"
+            )
+            
+            await loader.load_entity_contexts(f.name, mock_websocket)
+            
+            sent_messages = [json.loads(call.args[0]) for call in mock_websocket.send.call_args_list]
+            
+            # Should have 4 entity contexts (for the 4 literals: "John Smith", "25", "New York", "Mary Johnson")
+            # URI ex:mary should be skipped
+            assert len(sent_messages) == 4
+            
+            # Verify all contexts are for literals (subjects should be URIs)
+            contexts = []
+            for message in sent_messages:
+                entity_context = message["entities"][0]
+                assert entity_context["entity"]["e"] is True  # Subject is URI
+                contexts.append(entity_context["context"])
+            
+            assert "John Smith" in contexts
+            assert "25" in contexts  
+            assert "New York" in contexts
+            assert "Mary Johnson" in contexts
+            
+        Path(f.name).unlink(missing_ok=True)

tests/unit/test_config/__init__.py

@@ -0,0 +1 @@
+# Configuration service tests

tests/unit/test_config/test_config_logic.py

@@ -0,0 +1,421 @@
+"""
+Standalone unit tests for Configuration Service Logic
+
+Tests core configuration logic without requiring full package imports.
+This focuses on testing the business logic that would be used by the
+configuration service components.
+"""
+
+import pytest
+import json
+from unittest.mock import Mock, AsyncMock
+from typing import Dict, Any
+
+
+class MockConfigurationLogic:
+    """Mock implementation of configuration logic for testing"""
+    
+    def __init__(self):
+        self.data = {}
+    
+    def parse_key(self, full_key: str) -> tuple[str, str]:
+        """Parse 'type.key' format into (type, key)"""
+        if '.' not in full_key:
+            raise ValueError(f"Invalid key format: {full_key}")
+        type_name, key = full_key.split('.', 1)
+        return type_name, key
+    
+    def validate_schema_json(self, schema_json: str) -> bool:
+        """Validate that schema JSON is properly formatted"""
+        try:
+            schema = json.loads(schema_json)
+            
+            # Check required fields
+            if "fields" not in schema:
+                return False
+                
+            for field in schema["fields"]:
+                if "name" not in field or "type" not in field:
+                    return False
+                    
+                # Validate field type
+                valid_types = ["string", "integer", "float", "boolean", "timestamp", "date", "time", "uuid"]
+                if field["type"] not in valid_types:
+                    return False
+                    
+            return True
+        except (json.JSONDecodeError, KeyError):
+            return False
+    
+    def put_values(self, values: Dict[str, str]) -> Dict[str, bool]:
+        """Store configuration values, return success status for each"""
+        results = {}
+        
+        for full_key, value in values.items():
+            try:
+                type_name, key = self.parse_key(full_key)
+                
+                # Validate schema if it's a schema type
+                if type_name == "schema" and not self.validate_schema_json(value):
+                    results[full_key] = False
+                    continue
+                
+                # Store the value
+                if type_name not in self.data:
+                    self.data[type_name] = {}
+                self.data[type_name][key] = value
+                results[full_key] = True
+                
+            except Exception:
+                results[full_key] = False
+                
+        return results
+    
+    def get_values(self, keys: list[str]) -> Dict[str, str | None]:
+        """Retrieve configuration values"""
+        results = {}
+        
+        for full_key in keys:
+            try:
+                type_name, key = self.parse_key(full_key)
+                value = self.data.get(type_name, {}).get(key)
+                results[full_key] = value
+            except Exception:
+                results[full_key] = None
+                
+        return results
+    
+    def delete_values(self, keys: list[str]) -> Dict[str, bool]:
+        """Delete configuration values"""
+        results = {}
+        
+        for full_key in keys:
+            try:
+                type_name, key = self.parse_key(full_key)
+                if type_name in self.data and key in self.data[type_name]:
+                    del self.data[type_name][key]
+                    results[full_key] = True
+                else:
+                    results[full_key] = False
+            except Exception:
+                results[full_key] = False
+                
+        return results
+    
+    def list_keys(self, type_name: str) -> list[str]:
+        """List all keys for a given type"""
+        return list(self.data.get(type_name, {}).keys())
+    
+    def get_type_values(self, type_name: str) -> Dict[str, str]:
+        """Get all key-value pairs for a type"""
+        return dict(self.data.get(type_name, {}))
+    
+    def get_all_data(self) -> Dict[str, Dict[str, str]]:
+        """Get all configuration data"""
+        return dict(self.data)
+
+
+class TestConfigurationLogic:
+    """Test cases for configuration business logic"""
+    
+    @pytest.fixture
+    def config_logic(self):
+        return MockConfigurationLogic()
+    
+    @pytest.fixture
+    def sample_schema_json(self):
+        return json.dumps({
+            "name": "customer_records",
+            "description": "Customer information schema",
+            "fields": [
+                {
+                    "name": "customer_id",
+                    "type": "string",
+                    "primary_key": True,
+                    "required": True,
+                    "indexed": True,
+                    "description": "Unique customer identifier"
+                },
+                {
+                    "name": "name",
+                    "type": "string",
+                    "required": True,
+                    "description": "Customer full name"
+                },
+                {
+                    "name": "email",
+                    "type": "string",
+                    "required": True,
+                    "indexed": True,
+                    "description": "Customer email address"
+                }
+            ]
+        })
+    
+    def test_parse_key_valid(self, config_logic):
+        """Test parsing valid configuration keys"""
+        # Act & Assert
+        type_name, key = config_logic.parse_key("schema.customer_records")
+        assert type_name == "schema"
+        assert key == "customer_records"
+        
+        type_name, key = config_logic.parse_key("flows.processing_flow")
+        assert type_name == "flows"
+        assert key == "processing_flow"
+    
+    def test_parse_key_invalid(self, config_logic):
+        """Test parsing invalid configuration keys"""
+        with pytest.raises(ValueError):
+            config_logic.parse_key("invalid_key")
+    
+    def test_validate_schema_json_valid(self, config_logic, sample_schema_json):
+        """Test validation of valid schema JSON"""
+        assert config_logic.validate_schema_json(sample_schema_json) is True
+    
+    def test_validate_schema_json_invalid(self, config_logic):
+        """Test validation of invalid schema JSON"""
+        # Invalid JSON
+        assert config_logic.validate_schema_json("not json") is False
+        
+        # Missing fields
+        assert config_logic.validate_schema_json('{"name": "test"}') is False
+        
+        # Invalid field type
+        invalid_schema = json.dumps({
+            "fields": [{"name": "test", "type": "invalid_type"}]
+        })
+        assert config_logic.validate_schema_json(invalid_schema) is False
+        
+        # Missing field name
+        invalid_schema2 = json.dumps({
+            "fields": [{"type": "string"}]
+        })
+        assert config_logic.validate_schema_json(invalid_schema2) is False
+    
+    def test_put_values_success(self, config_logic, sample_schema_json):
+        """Test storing configuration values successfully"""
+        # Arrange
+        values = {
+            "schema.customer_records": sample_schema_json,
+            "flows.test_flow": '{"steps": []}',
+            "schema.product_catalog": json.dumps({
+                "fields": [{"name": "sku", "type": "string"}]
+            })
+        }
+        
+        # Act
+        results = config_logic.put_values(values)
+        
+        # Assert
+        assert all(results.values())  # All should succeed
+        assert len(results) == 3
+        
+        # Verify data was stored
+        assert "schema" in config_logic.data
+        assert "customer_records" in config_logic.data["schema"]
+        assert config_logic.data["schema"]["customer_records"] == sample_schema_json
+    
+    def test_put_values_with_invalid_schema(self, config_logic):
+        """Test storing values with invalid schema"""
+        # Arrange
+        values = {
+            "schema.valid": json.dumps({"fields": [{"name": "id", "type": "string"}]}),
+            "schema.invalid": "not valid json",
+            "flows.test": '{"steps": []}'  # Non-schema should still work
+        }
+        
+        # Act
+        results = config_logic.put_values(values)
+        
+        # Assert
+        assert results["schema.valid"] is True
+        assert results["schema.invalid"] is False
+        assert results["flows.test"] is True
+        
+        # Only valid values should be stored
+        assert "valid" in config_logic.data.get("schema", {})
+        assert "invalid" not in config_logic.data.get("schema", {})
+        assert "test" in config_logic.data.get("flows", {})
+    
+    def test_get_values(self, config_logic, sample_schema_json):
+        """Test retrieving configuration values"""
+        # Arrange
+        config_logic.data = {
+            "schema": {"customer_records": sample_schema_json},
+            "flows": {"test_flow": '{"steps": []}'}
+        }
+        
+        keys = ["schema.customer_records", "schema.nonexistent", "flows.test_flow"]
+        
+        # Act
+        results = config_logic.get_values(keys)
+        
+        # Assert
+        assert results["schema.customer_records"] == sample_schema_json
+        assert results["schema.nonexistent"] is None
+        assert results["flows.test_flow"] == '{"steps": []}'
+    
+    def test_delete_values(self, config_logic, sample_schema_json):
+        """Test deleting configuration values"""
+        # Arrange
+        config_logic.data = {
+            "schema": {
+                "customer_records": sample_schema_json,
+                "product_catalog": '{"fields": []}'
+            }
+        }
+        
+        keys = ["schema.customer_records", "schema.nonexistent"]
+        
+        # Act
+        results = config_logic.delete_values(keys)
+        
+        # Assert
+        assert results["schema.customer_records"] is True
+        assert results["schema.nonexistent"] is False
+        
+        # Verify deletion
+        assert "customer_records" not in config_logic.data["schema"]
+        assert "product_catalog" in config_logic.data["schema"]  # Should remain
+    
+    def test_list_keys(self, config_logic):
+        """Test listing keys for a type"""
+        # Arrange
+        config_logic.data = {
+            "schema": {"customer_records": "...", "product_catalog": "..."},
+            "flows": {"flow1": "...", "flow2": "..."}
+        }
+        
+        # Act
+        schema_keys = config_logic.list_keys("schema")
+        flow_keys = config_logic.list_keys("flows")
+        empty_keys = config_logic.list_keys("nonexistent")
+        
+        # Assert
+        assert set(schema_keys) == {"customer_records", "product_catalog"}
+        assert set(flow_keys) == {"flow1", "flow2"}
+        assert empty_keys == []
+    
+    def test_get_type_values(self, config_logic, sample_schema_json):
+        """Test getting all values for a type"""
+        # Arrange
+        config_logic.data = {
+            "schema": {
+                "customer_records": sample_schema_json,
+                "product_catalog": '{"fields": []}'
+            }
+        }
+        
+        # Act
+        schema_values = config_logic.get_type_values("schema")
+        
+        # Assert
+        assert len(schema_values) == 2
+        assert schema_values["customer_records"] == sample_schema_json
+        assert schema_values["product_catalog"] == '{"fields": []}'
+    
+    def test_get_all_data(self, config_logic):
+        """Test getting all configuration data"""
+        # Arrange
+        test_data = {
+            "schema": {"test_schema": "{}"},
+            "flows": {"test_flow": "{}"}
+        }
+        config_logic.data = test_data
+        
+        # Act
+        all_data = config_logic.get_all_data()
+        
+        # Assert
+        assert all_data == test_data
+        assert all_data is not config_logic.data  # Should be a copy
+
+
+class TestSchemaValidationLogic:
+    """Test schema validation business logic"""
+    
+    def test_valid_schema_all_field_types(self):
+        """Test schema with all supported field types"""
+        schema = {
+            "name": "all_types_schema",
+            "description": "Schema with all field types",
+            "fields": [
+                {"name": "text_field", "type": "string", "required": True},
+                {"name": "int_field", "type": "integer", "size": 4},
+                {"name": "bigint_field", "type": "integer", "size": 8},
+                {"name": "float_field", "type": "float", "size": 4},
+                {"name": "double_field", "type": "float", "size": 8},
+                {"name": "bool_field", "type": "boolean"},
+                {"name": "timestamp_field", "type": "timestamp"},
+                {"name": "date_field", "type": "date"},
+                {"name": "time_field", "type": "time"},
+                {"name": "uuid_field", "type": "uuid"},
+                {"name": "primary_field", "type": "string", "primary_key": True},
+                {"name": "indexed_field", "type": "string", "indexed": True},
+                {"name": "enum_field", "type": "string", "enum": ["active", "inactive"]}
+            ]
+        }
+        
+        schema_json = json.dumps(schema)
+        logic = MockConfigurationLogic()
+        
+        assert logic.validate_schema_json(schema_json) is True
+    
+    def test_schema_field_constraints(self):
+        """Test various schema field constraint scenarios"""
+        logic = MockConfigurationLogic()
+        
+        # Test required vs optional fields
+        schema_with_required = {
+            "fields": [
+                {"name": "required_field", "type": "string", "required": True},
+                {"name": "optional_field", "type": "string", "required": False}
+            ]
+        }
+        assert logic.validate_schema_json(json.dumps(schema_with_required)) is True
+        
+        # Test primary key fields
+        schema_with_primary = {
+            "fields": [
+                {"name": "id", "type": "string", "primary_key": True},
+                {"name": "data", "type": "string"}
+            ]
+        }
+        assert logic.validate_schema_json(json.dumps(schema_with_primary)) is True
+        
+        # Test indexed fields
+        schema_with_indexes = {
+            "fields": [
+                {"name": "searchable", "type": "string", "indexed": True},
+                {"name": "non_searchable", "type": "string", "indexed": False}
+            ]
+        }
+        assert logic.validate_schema_json(json.dumps(schema_with_indexes)) is True
+    
+    def test_configuration_versioning_logic(self):
+        """Test configuration versioning concepts"""
+        # This tests the logical concepts around versioning
+        # that would be used in the actual implementation
+        
+        version_history = []
+        
+        def increment_version(current_version: int) -> int:
+            new_version = current_version + 1
+            version_history.append(new_version)
+            return new_version
+        
+        def get_latest_version() -> int:
+            return max(version_history) if version_history else 0
+        
+        # Test version progression
+        assert get_latest_version() == 0
+        
+        v1 = increment_version(0)
+        assert v1 == 1
+        assert get_latest_version() == 1
+        
+        v2 = increment_version(v1)
+        assert v2 == 2
+        assert get_latest_version() == 2
+        
+        assert len(version_history) == 2

tests/unit/test_decoding/test_mistral_ocr_processor.py

@@ -0,0 +1,296 @@
+"""
+Unit tests for trustgraph.decoding.mistral_ocr.processor
+"""
+
+import pytest
+import base64
+import uuid
+from unittest.mock import AsyncMock, MagicMock, patch, Mock
+from unittest import IsolatedAsyncioTestCase
+from io import BytesIO
+
+from trustgraph.decoding.mistral_ocr.processor import Processor
+from trustgraph.schema import Document, TextDocument, Metadata
+
+
+class TestMistralOcrProcessor(IsolatedAsyncioTestCase):
+    """Test Mistral OCR processor functionality"""
+
+    @patch('trustgraph.decoding.mistral_ocr.processor.Mistral')
+    @patch('trustgraph.base.flow_processor.FlowProcessor.__init__')
+    async def test_processor_initialization_with_api_key(self, mock_flow_init, mock_mistral_class):
+        """Test Mistral OCR processor initialization with API key"""
+        # Arrange
+        mock_flow_init.return_value = None
+        mock_mistral = MagicMock()
+        mock_mistral_class.return_value = mock_mistral
+        
+        config = {
+            'id': 'test-mistral-ocr',
+            'api_key': 'test-api-key',
+            'taskgroup': AsyncMock()
+        }
+
+        # Act
+        with patch.object(Processor, 'register_specification') as mock_register:
+            processor = Processor(**config)
+
+        # Assert
+        mock_flow_init.assert_called_once()
+        mock_mistral_class.assert_called_once_with(api_key='test-api-key')
+        
+        # Verify register_specification was called twice (consumer and producer)
+        assert mock_register.call_count == 2
+        
+        # Check consumer spec
+        consumer_call = mock_register.call_args_list[0]
+        consumer_spec = consumer_call[0][0]
+        assert consumer_spec.name == "input"
+        assert consumer_spec.schema == Document
+        assert consumer_spec.handler == processor.on_message
+        
+        # Check producer spec
+        producer_call = mock_register.call_args_list[1]
+        producer_spec = producer_call[0][0]
+        assert producer_spec.name == "output"
+        assert producer_spec.schema == TextDocument
+
+    @patch('trustgraph.base.flow_processor.FlowProcessor.__init__')
+    async def test_processor_initialization_without_api_key(self, mock_flow_init):
+        """Test Mistral OCR processor initialization without API key raises error"""
+        # Arrange
+        mock_flow_init.return_value = None
+        
+        config = {
+            'id': 'test-mistral-ocr',
+            'taskgroup': AsyncMock()
+        }
+
+        # Act & Assert
+        with patch.object(Processor, 'register_specification'):
+            with pytest.raises(RuntimeError, match="Mistral API key not specified"):
+                processor = Processor(**config)
+
+    @patch('trustgraph.decoding.mistral_ocr.processor.uuid.uuid4')
+    @patch('trustgraph.decoding.mistral_ocr.processor.Mistral')
+    @patch('trustgraph.base.flow_processor.FlowProcessor.__init__')
+    async def test_ocr_single_chunk(self, mock_flow_init, mock_mistral_class, mock_uuid):
+        """Test OCR processing with a single chunk (less than 5 pages)"""
+        # Arrange
+        mock_flow_init.return_value = None
+        mock_uuid.return_value = "test-uuid-1234"
+        
+        # Mock Mistral client
+        mock_mistral = MagicMock()
+        mock_mistral_class.return_value = mock_mistral
+        
+        # Mock file upload
+        mock_uploaded_file = MagicMock(id="file-123")
+        mock_mistral.files.upload.return_value = mock_uploaded_file
+        
+        # Mock signed URL
+        mock_signed_url = MagicMock(url="https://example.com/signed-url")
+        mock_mistral.files.get_signed_url.return_value = mock_signed_url
+        
+        # Mock OCR response
+        mock_page = MagicMock(
+            markdown="# Page 1\nContent ![img1](img1)",
+            images=[MagicMock(id="img1", image_base64="data:image/png;base64,abc123")]
+        )
+        mock_ocr_response = MagicMock(pages=[mock_page])
+        mock_mistral.ocr.process.return_value = mock_ocr_response
+        
+        # Mock PyPDF
+        mock_pdf_reader = MagicMock()
+        mock_pdf_reader.pages = [MagicMock(), MagicMock(), MagicMock()]  # 3 pages
+        
+        config = {
+            'id': 'test-mistral-ocr',
+            'api_key': 'test-api-key',
+            'taskgroup': AsyncMock()
+        }
+
+        with patch.object(Processor, 'register_specification'):
+            with patch('trustgraph.decoding.mistral_ocr.processor.PdfReader', return_value=mock_pdf_reader):
+                with patch('trustgraph.decoding.mistral_ocr.processor.PdfWriter') as mock_pdf_writer_class:
+                    mock_pdf_writer = MagicMock()
+                    mock_pdf_writer_class.return_value = mock_pdf_writer
+                    
+                    processor = Processor(**config)
+                    
+                    # Act
+                    result = processor.ocr(b"fake pdf content")
+
+        # Assert
+        assert result == "# Page 1\nContent ![img1](data:image/png;base64,abc123)"
+        
+        # Verify PDF writer was used to create chunk
+        assert mock_pdf_writer.add_page.call_count == 3
+        mock_pdf_writer.write_stream.assert_called_once()
+        
+        # Verify Mistral API calls
+        mock_mistral.files.upload.assert_called_once()
+        upload_call = mock_mistral.files.upload.call_args[1]
+        assert upload_call['file']['file_name'] == "test-uuid-1234"
+        assert upload_call['purpose'] == 'ocr'
+        
+        mock_mistral.files.get_signed_url.assert_called_once_with(
+            file_id="file-123", expiry=1
+        )
+        
+        mock_mistral.ocr.process.assert_called_once_with(
+            model="mistral-ocr-latest",
+            include_image_base64=True,
+            document={
+                "type": "document_url",
+                "document_url": "https://example.com/signed-url",
+            }
+        )
+
+    @patch('trustgraph.decoding.mistral_ocr.processor.uuid.uuid4')
+    @patch('trustgraph.decoding.mistral_ocr.processor.Mistral')
+    @patch('trustgraph.base.flow_processor.FlowProcessor.__init__')
+    async def test_on_message_success(self, mock_flow_init, mock_mistral_class, mock_uuid):
+        """Test successful message processing"""
+        # Arrange
+        mock_flow_init.return_value = None
+        mock_uuid.return_value = "test-uuid-5678"
+        
+        # Mock Mistral client with simple OCR response
+        mock_mistral = MagicMock()
+        mock_mistral_class.return_value = mock_mistral
+        
+        # Mock the ocr method to return simple markdown
+        ocr_result = "# Document Title\nThis is the OCR content"
+        
+        # Mock message
+        pdf_content = b"fake pdf content"
+        pdf_base64 = base64.b64encode(pdf_content).decode('utf-8')
+        mock_metadata = Metadata(id="test-doc")
+        mock_document = Document(metadata=mock_metadata, data=pdf_base64)
+        mock_msg = MagicMock()
+        mock_msg.value.return_value = mock_document
+        
+        # Mock flow - needs to be a callable that returns an object with send method
+        mock_output_flow = AsyncMock()
+        mock_flow = MagicMock(return_value=mock_output_flow)
+        
+        config = {
+            'id': 'test-mistral-ocr',
+            'api_key': 'test-api-key',
+            'taskgroup': AsyncMock()
+        }
+
+        with patch.object(Processor, 'register_specification'):
+            processor = Processor(**config)
+            
+            # Mock the ocr method
+            with patch.object(processor, 'ocr', return_value=ocr_result):
+                # Act
+                await processor.on_message(mock_msg, None, mock_flow)
+
+        # Assert
+        # Verify output was sent
+        mock_output_flow.send.assert_called_once()
+        
+        # Check output
+        call_args = mock_output_flow.send.call_args[0][0]
+        assert isinstance(call_args, TextDocument)
+        assert call_args.metadata == mock_metadata
+        assert call_args.text == ocr_result.encode('utf-8')
+
+    @patch('trustgraph.decoding.mistral_ocr.processor.Mistral')
+    @patch('trustgraph.base.flow_processor.FlowProcessor.__init__')
+    async def test_chunks_function(self, mock_flow_init, mock_mistral_class):
+        """Test the chunks utility function"""
+        # Arrange
+        from trustgraph.decoding.mistral_ocr.processor import chunks
+        
+        test_list = list(range(12))
+        
+        # Act
+        result = list(chunks(test_list, 5))
+        
+        # Assert
+        assert len(result) == 3
+        assert result[0] == [0, 1, 2, 3, 4]
+        assert result[1] == [5, 6, 7, 8, 9]
+        assert result[2] == [10, 11]
+
+    @patch('trustgraph.decoding.mistral_ocr.processor.Mistral')
+    @patch('trustgraph.base.flow_processor.FlowProcessor.__init__')
+    async def test_replace_images_in_markdown(self, mock_flow_init, mock_mistral_class):
+        """Test the replace_images_in_markdown function"""
+        # Arrange
+        from trustgraph.decoding.mistral_ocr.processor import replace_images_in_markdown
+        
+        markdown = "# Title\n![image1](image1)\nSome text\n![image2](image2)"
+        images_dict = {
+            "image1": "data:image/png;base64,abc123",
+            "image2": "data:image/png;base64,def456"
+        }
+        
+        # Act
+        result = replace_images_in_markdown(markdown, images_dict)
+        
+        # Assert
+        expected = "# Title\n![image1](data:image/png;base64,abc123)\nSome text\n![image2](data:image/png;base64,def456)"
+        assert result == expected
+
+    @patch('trustgraph.decoding.mistral_ocr.processor.Mistral')
+    @patch('trustgraph.base.flow_processor.FlowProcessor.__init__')
+    async def test_get_combined_markdown(self, mock_flow_init, mock_mistral_class):
+        """Test the get_combined_markdown function"""
+        # Arrange
+        from trustgraph.decoding.mistral_ocr.processor import get_combined_markdown
+        from mistralai.models import OCRResponse
+        
+        # Mock OCR response with multiple pages
+        mock_page1 = MagicMock(
+            markdown="# Page 1\n![img1](img1)",
+            images=[MagicMock(id="img1", image_base64="base64_img1")]
+        )
+        mock_page2 = MagicMock(
+            markdown="# Page 2\n![img2](img2)",
+            images=[MagicMock(id="img2", image_base64="base64_img2")]
+        )
+        mock_ocr_response = MagicMock(pages=[mock_page1, mock_page2])
+        
+        # Act
+        result = get_combined_markdown(mock_ocr_response)
+        
+        # Assert
+        expected = "# Page 1\n![img1](base64_img1)\n\n# Page 2\n![img2](base64_img2)"
+        assert result == expected
+
+    @patch('trustgraph.base.flow_processor.FlowProcessor.add_args')
+    def test_add_args(self, mock_parent_add_args):
+        """Test add_args adds API key argument"""
+        # Arrange
+        mock_parser = MagicMock()
+        
+        # Act
+        Processor.add_args(mock_parser)
+        
+        # Assert
+        mock_parent_add_args.assert_called_once_with(mock_parser)
+        mock_parser.add_argument.assert_called_once_with(
+            '-k', '--api-key',
+            default=None,  # default_api_key is None in test environment
+            help='Mistral API Key'
+        )
+
+    @patch('trustgraph.decoding.mistral_ocr.processor.Processor.launch')
+    def test_run(self, mock_launch):
+        """Test run function"""
+        # Act
+        from trustgraph.decoding.mistral_ocr.processor import run
+        run()
+        
+        # Assert
+        mock_launch.assert_called_once_with("pdf-decoder",
+            "\nSimple decoder, accepts PDF documents on input, outputs pages from the\nPDF document as text as separate output objects.\n")
+
+
+if __name__ == '__main__':
+    pytest.main([__file__])

tests/unit/test_decoding/test_pdf_decoder.py

@@ -0,0 +1,229 @@
+"""
+Unit tests for trustgraph.decoding.pdf.pdf_decoder
+"""
+
+import pytest
+import base64
+import tempfile
+from unittest.mock import AsyncMock, MagicMock, patch, call
+from unittest import IsolatedAsyncioTestCase
+
+from trustgraph.decoding.pdf.pdf_decoder import Processor
+from trustgraph.schema import Document, TextDocument, Metadata
+
+
+class TestPdfDecoderProcessor(IsolatedAsyncioTestCase):
+    """Test PDF decoder processor functionality"""
+
+    @patch('trustgraph.base.flow_processor.FlowProcessor.__init__')
+    async def test_processor_initialization(self, mock_flow_init):
+        """Test PDF decoder processor initialization"""
+        # Arrange
+        mock_flow_init.return_value = None
+        
+        config = {
+            'id': 'test-pdf-decoder',
+            'taskgroup': AsyncMock()
+        }
+
+        # Act
+        with patch.object(Processor, 'register_specification') as mock_register:
+            processor = Processor(**config)
+
+        # Assert
+        mock_flow_init.assert_called_once()
+        # Verify register_specification was called twice (consumer and producer)
+        assert mock_register.call_count == 2
+        
+        # Check consumer spec
+        consumer_call = mock_register.call_args_list[0]
+        consumer_spec = consumer_call[0][0]
+        assert consumer_spec.name == "input"
+        assert consumer_spec.schema == Document
+        assert consumer_spec.handler == processor.on_message
+        
+        # Check producer spec
+        producer_call = mock_register.call_args_list[1]
+        producer_spec = producer_call[0][0]
+        assert producer_spec.name == "output"
+        assert producer_spec.schema == TextDocument
+
+    @patch('trustgraph.decoding.pdf.pdf_decoder.PyPDFLoader')
+    @patch('trustgraph.base.flow_processor.FlowProcessor.__init__')
+    async def test_on_message_success(self, mock_flow_init, mock_pdf_loader_class):
+        """Test successful PDF processing"""
+        # Arrange
+        mock_flow_init.return_value = None
+        
+        # Mock PDF content
+        pdf_content = b"fake pdf content"
+        pdf_base64 = base64.b64encode(pdf_content).decode('utf-8')
+        
+        # Mock PyPDFLoader
+        mock_loader = MagicMock()
+        mock_page1 = MagicMock(page_content="Page 1 content")
+        mock_page2 = MagicMock(page_content="Page 2 content")
+        mock_loader.load.return_value = [mock_page1, mock_page2]
+        mock_pdf_loader_class.return_value = mock_loader
+        
+        # Mock message
+        mock_metadata = Metadata(id="test-doc")
+        mock_document = Document(metadata=mock_metadata, data=pdf_base64)
+        mock_msg = MagicMock()
+        mock_msg.value.return_value = mock_document
+        
+        # Mock flow - needs to be a callable that returns an object with send method
+        mock_output_flow = AsyncMock()
+        mock_flow = MagicMock(return_value=mock_output_flow)
+        
+        config = {
+            'id': 'test-pdf-decoder',
+            'taskgroup': AsyncMock()
+        }
+
+        with patch.object(Processor, 'register_specification'):
+            processor = Processor(**config)
+
+        # Act
+        await processor.on_message(mock_msg, None, mock_flow)
+
+        # Assert
+        # Verify PyPDFLoader was called
+        mock_pdf_loader_class.assert_called_once()
+        mock_loader.load.assert_called_once()
+        
+        # Verify output was sent for each page
+        assert mock_output_flow.send.call_count == 2
+        
+        # Check first page output
+        first_call = mock_output_flow.send.call_args_list[0]
+        first_output = first_call[0][0]
+        assert isinstance(first_output, TextDocument)
+        assert first_output.metadata == mock_metadata
+        assert first_output.text == b"Page 1 content"
+        
+        # Check second page output
+        second_call = mock_output_flow.send.call_args_list[1]
+        second_output = second_call[0][0]
+        assert isinstance(second_output, TextDocument)
+        assert second_output.metadata == mock_metadata
+        assert second_output.text == b"Page 2 content"
+
+    @patch('trustgraph.decoding.pdf.pdf_decoder.PyPDFLoader')
+    @patch('trustgraph.base.flow_processor.FlowProcessor.__init__')
+    async def test_on_message_empty_pdf(self, mock_flow_init, mock_pdf_loader_class):
+        """Test handling of empty PDF"""
+        # Arrange
+        mock_flow_init.return_value = None
+        
+        # Mock PDF content
+        pdf_content = b"fake pdf content"
+        pdf_base64 = base64.b64encode(pdf_content).decode('utf-8')
+        
+        # Mock PyPDFLoader with no pages
+        mock_loader = MagicMock()
+        mock_loader.load.return_value = []
+        mock_pdf_loader_class.return_value = mock_loader
+        
+        # Mock message
+        mock_metadata = Metadata(id="test-doc")
+        mock_document = Document(metadata=mock_metadata, data=pdf_base64)
+        mock_msg = MagicMock()
+        mock_msg.value.return_value = mock_document
+        
+        # Mock flow - needs to be a callable that returns an object with send method
+        mock_output_flow = AsyncMock()
+        mock_flow = MagicMock(return_value=mock_output_flow)
+        
+        config = {
+            'id': 'test-pdf-decoder',
+            'taskgroup': AsyncMock()
+        }
+
+        with patch.object(Processor, 'register_specification'):
+            processor = Processor(**config)
+
+        # Act
+        await processor.on_message(mock_msg, None, mock_flow)
+
+        # Assert
+        # Verify PyPDFLoader was called
+        mock_pdf_loader_class.assert_called_once()
+        mock_loader.load.assert_called_once()
+        
+        # Verify no output was sent
+        mock_output_flow.send.assert_not_called()
+
+    @patch('trustgraph.decoding.pdf.pdf_decoder.PyPDFLoader')
+    @patch('trustgraph.base.flow_processor.FlowProcessor.__init__')
+    async def test_on_message_unicode_content(self, mock_flow_init, mock_pdf_loader_class):
+        """Test handling of unicode content in PDF"""
+        # Arrange
+        mock_flow_init.return_value = None
+        
+        # Mock PDF content
+        pdf_content = b"fake pdf content"
+        pdf_base64 = base64.b64encode(pdf_content).decode('utf-8')
+        
+        # Mock PyPDFLoader with unicode content
+        mock_loader = MagicMock()
+        mock_page = MagicMock(page_content="Page with unicode: 你好世界 🌍")
+        mock_loader.load.return_value = [mock_page]
+        mock_pdf_loader_class.return_value = mock_loader
+        
+        # Mock message
+        mock_metadata = Metadata(id="test-doc")
+        mock_document = Document(metadata=mock_metadata, data=pdf_base64)
+        mock_msg = MagicMock()
+        mock_msg.value.return_value = mock_document
+        
+        # Mock flow - needs to be a callable that returns an object with send method
+        mock_output_flow = AsyncMock()
+        mock_flow = MagicMock(return_value=mock_output_flow)
+        
+        config = {
+            'id': 'test-pdf-decoder',
+            'taskgroup': AsyncMock()
+        }
+
+        with patch.object(Processor, 'register_specification'):
+            processor = Processor(**config)
+
+        # Act
+        await processor.on_message(mock_msg, None, mock_flow)
+
+        # Assert
+        # Verify output was sent
+        mock_output_flow.send.assert_called_once()
+        
+        # Check output
+        call_args = mock_output_flow.send.call_args[0][0]
+        assert isinstance(call_args, TextDocument)
+        assert call_args.text == "Page with unicode: 你好世界 🌍".encode('utf-8')
+
+    @patch('trustgraph.base.flow_processor.FlowProcessor.add_args')
+    def test_add_args(self, mock_parent_add_args):
+        """Test add_args calls parent method"""
+        # Arrange
+        mock_parser = MagicMock()
+        
+        # Act
+        Processor.add_args(mock_parser)
+        
+        # Assert
+        mock_parent_add_args.assert_called_once_with(mock_parser)
+
+    @patch('trustgraph.decoding.pdf.pdf_decoder.Processor.launch')
+    def test_run(self, mock_launch):
+        """Test run function"""
+        # Act
+        from trustgraph.decoding.pdf.pdf_decoder import run
+        run()
+        
+        # Assert
+        mock_launch.assert_called_once_with("pdf-decoder", 
+            "\nSimple decoder, accepts PDF documents on input, outputs pages from the\nPDF document as text as separate output objects.\n")
+
+
+if __name__ == '__main__':
+    pytest.main([__file__])

tests/unit/test_embeddings/__init__.py

@@ -0,0 +1,10 @@
+"""
+Unit tests for embeddings services
+
+Testing Strategy:
+- Mock external embedding libraries (FastEmbed, Ollama client)
+- Test core business logic for text embedding generation
+- Test error handling and edge cases
+- Test vector dimension consistency
+- Test batch processing logic
+"""

tests/unit/test_embeddings/conftest.py

@@ -0,0 +1,114 @@
+"""
+Shared fixtures for embeddings unit tests
+"""
+
+import pytest
+import numpy as np
+from unittest.mock import Mock, AsyncMock, MagicMock
+from trustgraph.schema import EmbeddingsRequest, EmbeddingsResponse, Error
+
+
+@pytest.fixture
+def sample_text():
+    """Sample text for embedding tests"""
+    return "This is a sample text for embedding generation."
+
+
+@pytest.fixture
+def sample_embedding_vector():
+    """Sample embedding vector for mocking"""
+    return [0.1, 0.2, -0.3, 0.4, -0.5, 0.6, 0.7, -0.8, 0.9, -1.0]
+
+
+@pytest.fixture
+def sample_batch_embeddings():
+    """Sample batch of embedding vectors"""
+    return [
+        [0.1, 0.2, -0.3, 0.4, -0.5],
+        [0.6, 0.7, -0.8, 0.9, -1.0],
+        [-0.1, -0.2, 0.3, -0.4, 0.5]
+    ]
+
+
+@pytest.fixture
+def sample_embeddings_request():
+    """Sample EmbeddingsRequest for testing"""
+    return EmbeddingsRequest(
+        text="Test text for embedding"
+    )
+
+
+@pytest.fixture
+def sample_embeddings_response(sample_embedding_vector):
+    """Sample successful EmbeddingsResponse"""
+    return EmbeddingsResponse(
+        error=None,
+        vectors=sample_embedding_vector
+    )
+
+
+@pytest.fixture
+def sample_error_response():
+    """Sample error EmbeddingsResponse"""
+    return EmbeddingsResponse(
+        error=Error(type="embedding-error", message="Model not found"),
+        vectors=None
+    )
+
+
+@pytest.fixture
+def mock_message():
+    """Mock Pulsar message for testing"""
+    message = Mock()
+    message.properties.return_value = {"id": "test-message-123"}
+    return message
+
+
+@pytest.fixture
+def mock_flow():
+    """Mock flow for producer/consumer testing"""
+    flow = Mock()
+    flow.return_value.send = AsyncMock()
+    flow.producer = {"response": Mock()}
+    flow.producer["response"].send = AsyncMock()
+    return flow
+
+
+@pytest.fixture
+def mock_consumer():
+    """Mock Pulsar consumer"""
+    return AsyncMock()
+
+
+@pytest.fixture
+def mock_producer():
+    """Mock Pulsar producer"""
+    return AsyncMock()
+
+
+@pytest.fixture
+def mock_fastembed_embedding():
+    """Mock FastEmbed TextEmbedding"""
+    mock = Mock()
+    mock.embed.return_value = [np.array([0.1, 0.2, -0.3, 0.4, -0.5])]
+    return mock
+
+
+@pytest.fixture
+def mock_ollama_client():
+    """Mock Ollama client"""
+    mock = Mock()
+    mock.embed.return_value = Mock(
+        embeddings=[0.1, 0.2, -0.3, 0.4, -0.5]
+    )
+    return mock
+
+
+@pytest.fixture
+def embedding_test_params():
+    """Common parameters for embedding processor testing"""
+    return {
+        "model": "test-model",
+        "concurrency": 1,
+        "id": "test-embeddings"
+    }

tests/unit/test_embeddings/test_embedding_logic.py

@@ -0,0 +1,278 @@
+"""
+Unit tests for embedding business logic
+
+Tests the core embedding functionality without external dependencies,
+focusing on data processing, validation, and business rules.
+"""
+
+import pytest
+import numpy as np
+from unittest.mock import Mock, patch
+
+
+class TestEmbeddingBusinessLogic:
+    """Test embedding business logic and data processing"""
+
+    def test_embedding_vector_validation(self):
+        """Test validation of embedding vectors"""
+        # Arrange
+        valid_vectors = [
+            [0.1, 0.2, 0.3],
+            [-0.5, 0.0, 0.8],
+            [],  # Empty vector
+            [1.0] * 1536  # Large vector
+        ]
+        
+        invalid_vectors = [
+            None,
+            "not a vector",
+            [1, 2, "string"],
+            [[1, 2], [3, 4]]  # Nested
+        ]
+        
+        # Act & Assert
+        def is_valid_vector(vec):
+            if not isinstance(vec, list):
+                return False
+            return all(isinstance(x, (int, float)) for x in vec)
+        
+        for vec in valid_vectors:
+            assert is_valid_vector(vec), f"Should be valid: {vec}"
+        
+        for vec in invalid_vectors:
+            assert not is_valid_vector(vec), f"Should be invalid: {vec}"
+
+    def test_dimension_consistency_check(self):
+        """Test dimension consistency validation"""
+        # Arrange
+        same_dimension_vectors = [
+            [0.1, 0.2, 0.3, 0.4, 0.5],
+            [0.6, 0.7, 0.8, 0.9, 1.0],
+            [-0.1, -0.2, -0.3, -0.4, -0.5]
+        ]
+        
+        mixed_dimension_vectors = [
+            [0.1, 0.2, 0.3],
+            [0.4, 0.5, 0.6, 0.7],
+            [0.8, 0.9]
+        ]
+        
+        # Act
+        def check_dimension_consistency(vectors):
+            if not vectors:
+                return True
+            expected_dim = len(vectors[0])
+            return all(len(vec) == expected_dim for vec in vectors)
+        
+        # Assert
+        assert check_dimension_consistency(same_dimension_vectors)
+        assert not check_dimension_consistency(mixed_dimension_vectors)
+
+    def test_text_preprocessing_logic(self):
+        """Test text preprocessing for embeddings"""
+        # Arrange
+        test_cases = [
+            ("Simple text", "Simple text"),
+            ("", ""),
+            ("Text with\nnewlines", "Text with\nnewlines"),
+            ("Unicode: 世界 🌍", "Unicode: 世界 🌍"),
+            ("  Whitespace  ", "  Whitespace  ")
+        ]
+        
+        # Act & Assert
+        for input_text, expected in test_cases:
+            # Simple preprocessing (identity in this case)
+            processed = str(input_text) if input_text is not None else ""
+            assert processed == expected
+
+    def test_batch_processing_logic(self):
+        """Test batch processing logic for multiple texts"""
+        # Arrange
+        texts = ["Text 1", "Text 2", "Text 3"]
+        
+        def mock_embed_single(text):
+            # Simulate embedding generation based on text length
+            return [len(text) / 10.0] * 5
+        
+        # Act
+        results = []
+        for text in texts:
+            embedding = mock_embed_single(text)
+            results.append((text, embedding))
+        
+        # Assert
+        assert len(results) == len(texts)
+        for i, (original_text, embedding) in enumerate(results):
+            assert original_text == texts[i]
+            assert len(embedding) == 5
+            expected_value = len(texts[i]) / 10.0
+            assert all(abs(val - expected_value) < 0.001 for val in embedding)
+
+    def test_numpy_array_conversion_logic(self):
+        """Test numpy array to list conversion"""
+        # Arrange
+        test_arrays = [
+            np.array([1, 2, 3], dtype=np.int32),
+            np.array([1.0, 2.0, 3.0], dtype=np.float64),
+            np.array([0.1, 0.2, 0.3], dtype=np.float32)
+        ]
+        
+        # Act
+        converted = []
+        for arr in test_arrays:
+            result = arr.tolist()
+            converted.append(result)
+        
+        # Assert
+        assert converted[0] == [1, 2, 3]
+        assert converted[1] == [1.0, 2.0, 3.0]
+        # Float32 might have precision differences, so check approximately
+        assert len(converted[2]) == 3
+        assert all(isinstance(x, float) for x in converted[2])
+
+    def test_error_response_generation(self):
+        """Test error response generation logic"""
+        # Arrange
+        error_scenarios = [
+            ("model_not_found", "Model 'xyz' not found"),
+            ("connection_error", "Failed to connect to service"),
+            ("rate_limit", "Rate limit exceeded"),
+            ("invalid_input", "Invalid input format")
+        ]
+        
+        # Act & Assert
+        for error_type, error_message in error_scenarios:
+            error_response = {
+                "error": {
+                    "type": error_type,
+                    "message": error_message
+                },
+                "vectors": None
+            }
+            
+            assert error_response["error"]["type"] == error_type
+            assert error_response["error"]["message"] == error_message
+            assert error_response["vectors"] is None
+
+    def test_success_response_generation(self):
+        """Test success response generation logic"""
+        # Arrange
+        test_vectors = [0.1, 0.2, 0.3, 0.4, 0.5]
+        
+        # Act
+        success_response = {
+            "error": None,
+            "vectors": test_vectors
+        }
+        
+        # Assert
+        assert success_response["error"] is None
+        assert success_response["vectors"] == test_vectors
+        assert len(success_response["vectors"]) == 5
+
+    def test_model_parameter_handling(self):
+        """Test model parameter validation and handling"""
+        # Arrange
+        valid_models = {
+            "ollama": ["mxbai-embed-large", "nomic-embed-text"],
+            "fastembed": ["sentence-transformers/all-MiniLM-L6-v2", "BAAI/bge-small-en-v1.5"]
+        }
+        
+        # Act & Assert
+        for provider, models in valid_models.items():
+            for model in models:
+                assert isinstance(model, str)
+                assert len(model) > 0
+                if provider == "fastembed":
+                    assert "/" in model or "-" in model
+
+    def test_concurrent_processing_simulation(self):
+        """Test concurrent processing simulation"""
+        # Arrange
+        import asyncio
+        
+        async def mock_async_embed(text, delay=0.001):
+            await asyncio.sleep(delay)
+            return [ord(text[0]) / 255.0] if text else [0.0]
+        
+        # Act
+        async def run_concurrent():
+            texts = ["A", "B", "C", "D", "E"]
+            tasks = [mock_async_embed(text) for text in texts]
+            results = await asyncio.gather(*tasks)
+            return list(zip(texts, results))
+        
+        # Run test
+        results = asyncio.run(run_concurrent())
+        
+        # Assert
+        assert len(results) == 5
+        for i, (text, embedding) in enumerate(results):
+            expected_char = chr(ord('A') + i)
+            assert text == expected_char
+            expected_value = ord(expected_char) / 255.0
+            assert abs(embedding[0] - expected_value) < 0.001
+
+    def test_empty_and_edge_cases(self):
+        """Test empty inputs and edge cases"""
+        # Arrange
+        edge_cases = [
+            ("", "empty string"),
+            (" ", "single space"),
+            ("a", "single character"),
+            ("A" * 10000, "very long string"),
+            ("\\n\\t\\r", "special characters"),
+            ("混合English中文", "mixed languages")
+        ]
+        
+        # Act & Assert
+        for text, description in edge_cases:
+            # Basic validation that text can be processed
+            assert isinstance(text, str), f"Failed for {description}"
+            assert len(text) >= 0, f"Failed for {description}"
+            
+            # Simulate embedding generation would work
+            mock_embedding = [len(text) % 10] * 3
+            assert len(mock_embedding) == 3, f"Failed for {description}"
+
+    def test_vector_normalization_logic(self):
+        """Test vector normalization calculations"""
+        # Arrange
+        test_vectors = [
+            [3.0, 4.0],  # Should normalize to [0.6, 0.8]
+            [1.0, 0.0],  # Should normalize to [1.0, 0.0]
+            [0.0, 0.0],  # Zero vector edge case
+        ]
+        
+        # Act & Assert
+        for vector in test_vectors:
+            magnitude = sum(x**2 for x in vector) ** 0.5
+            
+            if magnitude > 0:
+                normalized = [x / magnitude for x in vector]
+                # Check unit length (approximately)
+                norm_magnitude = sum(x**2 for x in normalized) ** 0.5
+                assert abs(norm_magnitude - 1.0) < 0.0001
+            else:
+                # Zero vector case
+                assert all(x == 0 for x in vector)
+
+    def test_cosine_similarity_calculation(self):
+        """Test cosine similarity computation"""
+        # Arrange
+        vector_pairs = [
+            ([1, 0], [0, 1], 0.0),  # Orthogonal
+            ([1, 0], [1, 0], 1.0),  # Identical
+            ([1, 1], [-1, -1], -1.0),  # Opposite
+        ]
+        
+        # Act & Assert
+        def cosine_similarity(v1, v2):
+            dot = sum(a * b for a, b in zip(v1, v2))
+            mag1 = sum(x**2 for x in v1) ** 0.5
+            mag2 = sum(x**2 for x in v2) ** 0.5
+            return dot / (mag1 * mag2) if mag1 * mag2 > 0 else 0
+        
+        for v1, v2, expected in vector_pairs:
+            similarity = cosine_similarity(v1, v2)
+            assert abs(similarity - expected) < 0.0001

tests/unit/test_embeddings/test_embedding_utils.py

@@ -0,0 +1,340 @@
+"""
+Unit tests for embedding utilities and common functionality
+
+Tests dimension consistency, batch processing, error handling patterns,
+and other utilities common across embedding services.
+"""
+
+import pytest
+from unittest.mock import patch, Mock, AsyncMock
+import numpy as np
+
+from trustgraph.schema import EmbeddingsRequest, EmbeddingsResponse, Error
+from trustgraph.exceptions import TooManyRequests
+
+
+class MockEmbeddingProcessor:
+    """Simple mock embedding processor for testing functionality"""
+    
+    def __init__(self, embedding_function=None, **params):
+        # Store embedding function for mocking
+        self.embedding_function = embedding_function
+        self.model = params.get('model', 'test-model')
+    
+    async def on_embeddings(self, text):
+        if self.embedding_function:
+            return self.embedding_function(text)
+        return [0.1, 0.2, 0.3, 0.4, 0.5]  # Default test embedding
+
+
+class TestEmbeddingDimensionConsistency:
+    """Test cases for embedding dimension consistency"""
+
+    async def test_consistent_dimensions_single_processor(self):
+        """Test that a single processor returns consistent dimensions"""
+        # Arrange
+        dimension = 128
+        def mock_embedding(text):
+            return [0.1] * dimension
+        
+        processor = MockEmbeddingProcessor(embedding_function=mock_embedding)
+        
+        # Act
+        results = []
+        test_texts = ["Text 1", "Text 2", "Text 3", "Text 4", "Text 5"]
+        
+        for text in test_texts:
+            result = await processor.on_embeddings(text)
+            results.append(result)
+        
+        # Assert
+        for result in results:
+            assert len(result) == dimension, f"Expected dimension {dimension}, got {len(result)}"
+        
+        # All results should have same dimensions
+        first_dim = len(results[0])
+        for i, result in enumerate(results[1:], 1):
+            assert len(result) == first_dim, f"Dimension mismatch at index {i}"
+
+    async def test_dimension_consistency_across_text_lengths(self):
+        """Test dimension consistency across varying text lengths"""
+        # Arrange
+        dimension = 384
+        def mock_embedding(text):
+            # Dimension should not depend on text length
+            return [0.1] * dimension
+        
+        processor = MockEmbeddingProcessor(embedding_function=mock_embedding)
+        
+        # Act - Test various text lengths
+        test_texts = [
+            "",  # Empty text
+            "Hi",  # Very short
+            "This is a medium length sentence for testing.",  # Medium
+            "This is a very long text that should still produce embeddings of consistent dimension regardless of the input text length and content." * 10  # Very long
+        ]
+        
+        results = []
+        for text in test_texts:
+            result = await processor.on_embeddings(text)
+            results.append(result)
+        
+        # Assert
+        for i, result in enumerate(results):
+            assert len(result) == dimension, f"Text length {len(test_texts[i])} produced wrong dimension"
+
+    def test_dimension_validation_different_models(self):
+        """Test dimension validation for different model configurations"""
+        # Arrange
+        models_and_dims = [
+            ("small-model", 128),
+            ("medium-model", 384),
+            ("large-model", 1536)
+        ]
+        
+        # Act & Assert
+        for model_name, expected_dim in models_and_dims:
+            # Test dimension validation logic
+            test_vector = [0.1] * expected_dim
+            assert len(test_vector) == expected_dim, f"Model {model_name} dimension mismatch"
+
+
+class TestEmbeddingBatchProcessing:
+    """Test cases for batch processing logic"""
+
+    async def test_sequential_processing_maintains_order(self):
+        """Test that sequential processing maintains text order"""
+        # Arrange
+        def mock_embedding(text):
+            # Return embedding that encodes the text for verification
+            return [ord(text[0]) / 255.0] if text else [0.0]  # Normalize to [0,1]
+        
+        processor = MockEmbeddingProcessor(embedding_function=mock_embedding)
+        
+        # Act
+        test_texts = ["A", "B", "C", "D", "E"]
+        results = []
+        
+        for text in test_texts:
+            result = await processor.on_embeddings(text)
+            results.append((text, result))
+        
+        # Assert
+        for i, (original_text, embedding) in enumerate(results):
+            assert original_text == test_texts[i]
+            expected_value = ord(test_texts[i][0]) / 255.0
+            assert abs(embedding[0] - expected_value) < 0.001
+
+    async def test_batch_processing_throughput(self):
+        """Test batch processing capabilities"""
+        # Arrange
+        call_count = 0
+        def mock_embedding(text):
+            nonlocal call_count
+            call_count += 1
+            return [0.1, 0.2, 0.3]
+        
+        processor = MockEmbeddingProcessor(embedding_function=mock_embedding)
+        
+        # Act - Process multiple texts
+        batch_size = 10
+        test_texts = [f"Text {i}" for i in range(batch_size)]
+        
+        results = []
+        for text in test_texts:
+            result = await processor.on_embeddings(text)
+            results.append(result)
+        
+        # Assert
+        assert call_count == batch_size
+        assert len(results) == batch_size
+        for result in results:
+            assert result == [0.1, 0.2, 0.3]
+
+    async def test_concurrent_processing_simulation(self):
+        """Test concurrent processing behavior simulation"""
+        # Arrange
+        import asyncio
+        
+        processing_times = []
+        def mock_embedding(text):
+            import time
+            processing_times.append(time.time())
+            return [len(text) / 100.0]  # Encoding text length
+        
+        processor = MockEmbeddingProcessor(embedding_function=mock_embedding)
+        
+        # Act - Simulate concurrent processing
+        test_texts = [f"Text {i}" for i in range(5)]
+        
+        tasks = [processor.on_embeddings(text) for text in test_texts]
+        results = await asyncio.gather(*tasks)
+        
+        # Assert
+        assert len(results) == 5
+        assert len(processing_times) == 5
+        
+        # Results should correspond to text lengths
+        for i, result in enumerate(results):
+            expected_value = len(test_texts[i]) / 100.0
+            assert abs(result[0] - expected_value) < 0.001
+
+
+class TestEmbeddingErrorHandling:
+    """Test cases for error handling in embedding services"""
+
+    async def test_embedding_function_error_handling(self):
+        """Test error handling in embedding function"""
+        # Arrange
+        def failing_embedding(text):
+            raise Exception("Embedding model failed")
+        
+        processor = MockEmbeddingProcessor(embedding_function=failing_embedding)
+        
+        # Act & Assert
+        with pytest.raises(Exception, match="Embedding model failed"):
+            await processor.on_embeddings("Test text")
+
+    async def test_rate_limit_exception_propagation(self):
+        """Test that rate limit exceptions are properly propagated"""
+        # Arrange
+        def rate_limited_embedding(text):
+            raise TooManyRequests("Rate limit exceeded")
+        
+        processor = MockEmbeddingProcessor(embedding_function=rate_limited_embedding)
+        
+        # Act & Assert
+        with pytest.raises(TooManyRequests, match="Rate limit exceeded"):
+            await processor.on_embeddings("Test text")
+
+    async def test_none_result_handling(self):
+        """Test handling when embedding function returns None"""
+        # Arrange
+        def none_embedding(text):
+            return None
+        
+        processor = MockEmbeddingProcessor(embedding_function=none_embedding)
+        
+        # Act
+        result = await processor.on_embeddings("Test text")
+        
+        # Assert
+        assert result is None
+
+    async def test_invalid_embedding_format_handling(self):
+        """Test handling of invalid embedding formats"""
+        # Arrange
+        def invalid_embedding(text):
+            return "not a list"  # Invalid format
+        
+        processor = MockEmbeddingProcessor(embedding_function=invalid_embedding)
+        
+        # Act
+        result = await processor.on_embeddings("Test text")
+        
+        # Assert
+        assert result == "not a list"  # Returns what the function provides
+
+
+class TestEmbeddingUtilities:
+    """Test cases for embedding utility functions and helpers"""
+
+    def test_vector_normalization_simulation(self):
+        """Test vector normalization logic simulation"""
+        # Arrange
+        test_vectors = [
+            [1.0, 2.0, 3.0],
+            [0.5, -0.5, 1.0],
+            [10.0, 20.0, 30.0]
+        ]
+        
+        # Act - Simulate L2 normalization
+        normalized_vectors = []
+        for vector in test_vectors:
+            magnitude = sum(x**2 for x in vector) ** 0.5
+            if magnitude > 0:
+                normalized = [x / magnitude for x in vector]
+            else:
+                normalized = vector
+            normalized_vectors.append(normalized)
+        
+        # Assert
+        for normalized in normalized_vectors:
+            magnitude = sum(x**2 for x in normalized) ** 0.5
+            assert abs(magnitude - 1.0) < 0.0001, "Vector should be unit length"
+
+    def test_cosine_similarity_calculation(self):
+        """Test cosine similarity calculation between embeddings"""
+        # Arrange
+        vector1 = [1.0, 0.0, 0.0]
+        vector2 = [0.0, 1.0, 0.0]
+        vector3 = [1.0, 0.0, 0.0]  # Same as vector1
+        
+        # Act - Calculate cosine similarities
+        def cosine_similarity(v1, v2):
+            dot_product = sum(a * b for a, b in zip(v1, v2))
+            mag1 = sum(x**2 for x in v1) ** 0.5
+            mag2 = sum(x**2 for x in v2) ** 0.5
+            return dot_product / (mag1 * mag2) if mag1 * mag2 > 0 else 0
+        
+        sim_12 = cosine_similarity(vector1, vector2)
+        sim_13 = cosine_similarity(vector1, vector3)
+        
+        # Assert
+        assert abs(sim_12 - 0.0) < 0.0001, "Orthogonal vectors should have 0 similarity"
+        assert abs(sim_13 - 1.0) < 0.0001, "Identical vectors should have 1.0 similarity"
+
+    def test_embedding_validation_helpers(self):
+        """Test embedding validation helper functions"""
+        # Arrange
+        valid_embeddings = [
+            [0.1, 0.2, 0.3],
+            [1.0, -1.0, 0.0],
+            []  # Empty embedding
+        ]
+        
+        invalid_embeddings = [
+            None,
+            "not a list",
+            [1, 2, "three"],  # Mixed types
+            [[1, 2], [3, 4]]  # Nested lists
+        ]
+        
+        # Act & Assert
+        def is_valid_embedding(embedding):
+            if not isinstance(embedding, list):
+                return False
+            return all(isinstance(x, (int, float)) for x in embedding)
+        
+        for embedding in valid_embeddings:
+            assert is_valid_embedding(embedding), f"Should be valid: {embedding}"
+        
+        for embedding in invalid_embeddings:
+            assert not is_valid_embedding(embedding), f"Should be invalid: {embedding}"
+
+    async def test_embedding_metadata_handling(self):
+        """Test handling of embedding metadata and properties"""
+        # Arrange
+        def metadata_embedding(text):
+            return {
+                "vectors": [0.1, 0.2, 0.3],
+                "model": "test-model",
+                "dimension": 3,
+                "text_length": len(text)
+            }
+        
+        # Mock processor that returns metadata
+        class MetadataProcessor(MockEmbeddingProcessor):
+            async def on_embeddings(self, text):
+                result = metadata_embedding(text)
+                return result["vectors"]  # Return only vectors for compatibility
+        
+        processor = MetadataProcessor()
+        
+        # Act
+        result = await processor.on_embeddings("Test text with metadata")
+        
+        # Assert
+        assert isinstance(result, list)
+        assert len(result) == 3
+        assert result == [0.1, 0.2, 0.3]

tests/unit/test_extract/__init__.py

@@ -0,0 +1 @@
+# Extraction processor tests

tests/unit/test_extract/test_object_extraction_logic.py

@@ -0,0 +1,533 @@
+"""
+Standalone unit tests for Object Extraction Logic
+
+Tests core object extraction logic without requiring full package imports.
+This focuses on testing the business logic that would be used by the
+object extraction processor components.
+"""
+
+import pytest
+import json
+from unittest.mock import Mock, AsyncMock
+from typing import Dict, Any, List
+
+
+class MockRowSchema:
+    """Mock implementation of RowSchema for testing"""
+    
+    def __init__(self, name: str, description: str, fields: List['MockField']):
+        self.name = name
+        self.description = description
+        self.fields = fields
+
+
+class MockField:
+    """Mock implementation of Field for testing"""
+    
+    def __init__(self, name: str, type: str, primary: bool = False, 
+                 required: bool = False, indexed: bool = False, 
+                 enum_values: List[str] = None, size: int = 0, 
+                 description: str = ""):
+        self.name = name
+        self.type = type
+        self.primary = primary
+        self.required = required
+        self.indexed = indexed
+        self.enum_values = enum_values or []
+        self.size = size
+        self.description = description
+
+
+class MockObjectExtractionLogic:
+    """Mock implementation of object extraction logic for testing"""
+    
+    def __init__(self):
+        self.schemas: Dict[str, MockRowSchema] = {}
+    
+    def convert_values_to_strings(self, obj: Dict[str, Any]) -> Dict[str, str]:
+        """Convert all values in a dictionary to strings for Pulsar Map(String()) compatibility"""
+        result = {}
+        for key, value in obj.items():
+            if value is None:
+                result[key] = ""
+            elif isinstance(value, str):
+                result[key] = value
+            elif isinstance(value, (int, float, bool)):
+                result[key] = str(value)
+            elif isinstance(value, (list, dict)):
+                # For complex types, serialize as JSON
+                result[key] = json.dumps(value)
+            else:
+                # For any other type, convert to string
+                result[key] = str(value)
+        return result
+    
+    def parse_schema_config(self, config: Dict[str, Dict[str, str]]) -> Dict[str, MockRowSchema]:
+        """Parse schema configuration and create RowSchema objects"""
+        schemas = {}
+        
+        if "schema" not in config:
+            return schemas
+        
+        for schema_name, schema_json in config["schema"].items():
+            try:
+                schema_def = json.loads(schema_json)
+                
+                fields = []
+                for field_def in schema_def.get("fields", []):
+                    field = MockField(
+                        name=field_def["name"],
+                        type=field_def["type"],
+                        size=field_def.get("size", 0),
+                        primary=field_def.get("primary_key", False),
+                        description=field_def.get("description", ""),
+                        required=field_def.get("required", False),
+                        enum_values=field_def.get("enum", []),
+                        indexed=field_def.get("indexed", False)
+                    )
+                    fields.append(field)
+                
+                row_schema = MockRowSchema(
+                    name=schema_def.get("name", schema_name),
+                    description=schema_def.get("description", ""),
+                    fields=fields
+                )
+                
+                schemas[schema_name] = row_schema
+                
+            except Exception as e:
+                # Skip invalid schemas
+                continue
+        
+        return schemas
+    
+    def validate_extracted_object(self, obj_data: Dict[str, Any], schema: MockRowSchema) -> bool:
+        """Validate extracted object against schema"""
+        for field in schema.fields:
+            # Check if required field is missing
+            if field.required and field.name not in obj_data:
+                return False
+            
+            if field.name in obj_data:
+                value = obj_data[field.name]
+                
+                # Check required fields are not empty/None
+                if field.required and (value is None or str(value).strip() == ""):
+                    return False
+                
+                # Check enum constraints (only if value is not empty)
+                if field.enum_values and value and value not in field.enum_values:
+                    return False
+                
+                # Check primary key fields are not None/empty
+                if field.primary and (value is None or str(value).strip() == ""):
+                    return False
+        
+        return True
+    
+    def calculate_confidence(self, obj_data: Dict[str, Any], schema: MockRowSchema) -> float:
+        """Calculate confidence score for extracted object"""
+        total_fields = len(schema.fields)
+        filled_fields = len([k for k, v in obj_data.items() if v and str(v).strip()])
+        
+        # Base confidence from field completeness
+        completeness_score = filled_fields / total_fields if total_fields > 0 else 0
+        
+        # Bonus for primary key presence
+        primary_key_bonus = 0.0
+        for field in schema.fields:
+            if field.primary and field.name in obj_data and obj_data[field.name]:
+                primary_key_bonus = 0.1
+                break
+        
+        # Penalty for enum violations
+        enum_penalty = 0.0
+        for field in schema.fields:
+            if field.enum_values and field.name in obj_data:
+                if obj_data[field.name] and obj_data[field.name] not in field.enum_values:
+                    enum_penalty = 0.2
+                    break
+        
+        confidence = min(1.0, completeness_score + primary_key_bonus - enum_penalty)
+        return max(0.0, confidence)
+    
+    def generate_extracted_object_id(self, chunk_id: str, schema_name: str, obj_data: Dict[str, Any]) -> str:
+        """Generate unique ID for extracted object"""
+        return f"{chunk_id}:{schema_name}:{hash(str(obj_data))}"
+    
+    def create_source_span(self, text: str, max_length: int = 100) -> str:
+        """Create source span reference from text"""
+        return text[:max_length] if len(text) > max_length else text
+
+
+class TestObjectExtractionLogic:
+    """Test cases for object extraction business logic"""
+    
+    @pytest.fixture
+    def extraction_logic(self):
+        return MockObjectExtractionLogic()
+    
+    @pytest.fixture
+    def sample_config(self):
+        customer_schema = {
+            "name": "customer_records",
+            "description": "Customer information",
+            "fields": [
+                {
+                    "name": "customer_id",
+                    "type": "string",
+                    "primary_key": True,
+                    "required": True,
+                    "indexed": True,
+                    "description": "Customer ID"
+                },
+                {
+                    "name": "name",
+                    "type": "string",
+                    "required": True,
+                    "description": "Customer name"
+                },
+                {
+                    "name": "email",
+                    "type": "string",
+                    "required": True,
+                    "indexed": True,
+                    "description": "Email address"
+                },
+                {
+                    "name": "status",
+                    "type": "string",
+                    "required": False,
+                    "indexed": True,
+                    "enum": ["active", "inactive", "suspended"],
+                    "description": "Account status"
+                }
+            ]
+        }
+        
+        product_schema = {
+            "name": "product_catalog",
+            "description": "Product information",
+            "fields": [
+                {
+                    "name": "sku",
+                    "type": "string",
+                    "primary_key": True,
+                    "required": True,
+                    "description": "Product SKU"
+                },
+                {
+                    "name": "price",
+                    "type": "float",
+                    "size": 8,
+                    "required": True,
+                    "description": "Product price"
+                }
+            ]
+        }
+        
+        return {
+            "schema": {
+                "customer_records": json.dumps(customer_schema),
+                "product_catalog": json.dumps(product_schema)
+            }
+        }
+    
+    def test_convert_values_to_strings(self, extraction_logic):
+        """Test value conversion for Pulsar compatibility"""
+        # Arrange
+        test_data = {
+            "string_val": "hello",
+            "int_val": 123,
+            "float_val": 45.67,
+            "bool_val": True,
+            "none_val": None,
+            "list_val": ["a", "b", "c"],
+            "dict_val": {"nested": "value"}
+        }
+        
+        # Act
+        result = extraction_logic.convert_values_to_strings(test_data)
+        
+        # Assert
+        assert result["string_val"] == "hello"
+        assert result["int_val"] == "123"
+        assert result["float_val"] == "45.67"
+        assert result["bool_val"] == "True"
+        assert result["none_val"] == ""
+        assert result["list_val"] == '["a", "b", "c"]'
+        assert result["dict_val"] == '{"nested": "value"}'
+    
+    def test_parse_schema_config_success(self, extraction_logic, sample_config):
+        """Test successful schema configuration parsing"""
+        # Act
+        schemas = extraction_logic.parse_schema_config(sample_config)
+        
+        # Assert
+        assert len(schemas) == 2
+        assert "customer_records" in schemas
+        assert "product_catalog" in schemas
+        
+        # Check customer schema details
+        customer_schema = schemas["customer_records"]
+        assert customer_schema.name == "customer_records"
+        assert len(customer_schema.fields) == 4
+        
+        # Check primary key field
+        primary_field = next((f for f in customer_schema.fields if f.primary), None)
+        assert primary_field is not None
+        assert primary_field.name == "customer_id"
+        
+        # Check enum field
+        status_field = next((f for f in customer_schema.fields if f.name == "status"), None)
+        assert status_field is not None
+        assert len(status_field.enum_values) == 3
+        assert "active" in status_field.enum_values
+    
+    def test_parse_schema_config_with_invalid_json(self, extraction_logic):
+        """Test schema config parsing with invalid JSON"""
+        # Arrange
+        config = {
+            "schema": {
+                "valid_schema": json.dumps({"name": "valid", "fields": []}),
+                "invalid_schema": "not valid json {"
+            }
+        }
+        
+        # Act
+        schemas = extraction_logic.parse_schema_config(config)
+        
+        # Assert - only valid schema should be parsed
+        assert len(schemas) == 1
+        assert "valid_schema" in schemas
+        assert "invalid_schema" not in schemas
+    
+    def test_validate_extracted_object_success(self, extraction_logic, sample_config):
+        """Test successful object validation"""
+        # Arrange
+        schemas = extraction_logic.parse_schema_config(sample_config)
+        customer_schema = schemas["customer_records"]
+        
+        valid_object = {
+            "customer_id": "CUST001",
+            "name": "John Doe",
+            "email": "john@example.com",
+            "status": "active"
+        }
+        
+        # Act
+        is_valid = extraction_logic.validate_extracted_object(valid_object, customer_schema)
+        
+        # Assert
+        assert is_valid is True
+    
+    def test_validate_extracted_object_missing_required(self, extraction_logic, sample_config):
+        """Test object validation with missing required fields"""
+        # Arrange
+        schemas = extraction_logic.parse_schema_config(sample_config)
+        customer_schema = schemas["customer_records"]
+        
+        invalid_object = {
+            "customer_id": "CUST001",
+            # Missing required 'name' and 'email' fields
+            "status": "active"
+        }
+        
+        # Act
+        is_valid = extraction_logic.validate_extracted_object(invalid_object, customer_schema)
+        
+        # Assert
+        assert is_valid is False
+    
+    def test_validate_extracted_object_invalid_enum(self, extraction_logic, sample_config):
+        """Test object validation with invalid enum value"""
+        # Arrange
+        schemas = extraction_logic.parse_schema_config(sample_config)
+        customer_schema = schemas["customer_records"]
+        
+        invalid_object = {
+            "customer_id": "CUST001",
+            "name": "John Doe",
+            "email": "john@example.com",
+            "status": "invalid_status"  # Not in enum
+        }
+        
+        # Act
+        is_valid = extraction_logic.validate_extracted_object(invalid_object, customer_schema)
+        
+        # Assert
+        assert is_valid is False
+    
+    def test_validate_extracted_object_empty_primary_key(self, extraction_logic, sample_config):
+        """Test object validation with empty primary key"""
+        # Arrange
+        schemas = extraction_logic.parse_schema_config(sample_config)
+        customer_schema = schemas["customer_records"]
+        
+        invalid_object = {
+            "customer_id": "",  # Empty primary key
+            "name": "John Doe",
+            "email": "john@example.com",
+            "status": "active"
+        }
+        
+        # Act
+        is_valid = extraction_logic.validate_extracted_object(invalid_object, customer_schema)
+        
+        # Assert
+        assert is_valid is False
+    
+    def test_calculate_confidence_complete_object(self, extraction_logic, sample_config):
+        """Test confidence calculation for complete object"""
+        # Arrange
+        schemas = extraction_logic.parse_schema_config(sample_config)
+        customer_schema = schemas["customer_records"]
+        
+        complete_object = {
+            "customer_id": "CUST001",
+            "name": "John Doe",
+            "email": "john@example.com",
+            "status": "active"
+        }
+        
+        # Act
+        confidence = extraction_logic.calculate_confidence(complete_object, customer_schema)
+        
+        # Assert
+        assert confidence > 0.9  # Should be high (1.0 completeness + 0.1 primary key bonus)
+    
+    def test_calculate_confidence_incomplete_object(self, extraction_logic, sample_config):
+        """Test confidence calculation for incomplete object"""
+        # Arrange
+        schemas = extraction_logic.parse_schema_config(sample_config)
+        customer_schema = schemas["customer_records"]
+        
+        incomplete_object = {
+            "customer_id": "CUST001",
+            "name": "John Doe"
+            # Missing email and status
+        }
+        
+        # Act
+        confidence = extraction_logic.calculate_confidence(incomplete_object, customer_schema)
+        
+        # Assert
+        assert confidence < 0.9  # Should be lower due to missing fields
+        assert confidence > 0.0   # But not zero due to primary key bonus
+    
+    def test_calculate_confidence_invalid_enum(self, extraction_logic, sample_config):
+        """Test confidence calculation with invalid enum value"""
+        # Arrange
+        schemas = extraction_logic.parse_schema_config(sample_config)
+        customer_schema = schemas["customer_records"]
+        
+        invalid_enum_object = {
+            "customer_id": "CUST001",
+            "name": "John Doe",
+            "email": "john@example.com",
+            "status": "invalid_status"  # Invalid enum
+        }
+        
+        # Act
+        confidence = extraction_logic.calculate_confidence(invalid_enum_object, customer_schema)
+        
+        # Assert
+        # Should be penalized for enum violation
+        complete_confidence = extraction_logic.calculate_confidence({
+            "customer_id": "CUST001",
+            "name": "John Doe", 
+            "email": "john@example.com",
+            "status": "active"
+        }, customer_schema)
+        
+        assert confidence < complete_confidence
+    
+    def test_generate_extracted_object_id(self, extraction_logic):
+        """Test extracted object ID generation"""
+        # Arrange
+        chunk_id = "chunk-001"
+        schema_name = "customer_records"
+        obj_data = {"customer_id": "CUST001", "name": "John Doe"}
+        
+        # Act
+        obj_id = extraction_logic.generate_extracted_object_id(chunk_id, schema_name, obj_data)
+        
+        # Assert
+        assert chunk_id in obj_id
+        assert schema_name in obj_id
+        assert isinstance(obj_id, str)
+        assert len(obj_id) > 20  # Should be reasonably long
+        
+        # Test consistency - same input should produce same ID
+        obj_id2 = extraction_logic.generate_extracted_object_id(chunk_id, schema_name, obj_data)
+        assert obj_id == obj_id2
+    
+    def test_create_source_span(self, extraction_logic):
+        """Test source span creation"""
+        # Test normal text
+        short_text = "This is a short text"
+        span = extraction_logic.create_source_span(short_text)
+        assert span == short_text
+        
+        # Test long text truncation
+        long_text = "x" * 200
+        span = extraction_logic.create_source_span(long_text, max_length=100)
+        assert len(span) == 100
+        assert span == "x" * 100
+        
+        # Test custom max length
+        span_custom = extraction_logic.create_source_span(long_text, max_length=50)
+        assert len(span_custom) == 50
+    
+    def test_multi_schema_processing(self, extraction_logic, sample_config):
+        """Test processing multiple schemas"""
+        # Act
+        schemas = extraction_logic.parse_schema_config(sample_config)
+        
+        # Test customer object
+        customer_obj = {
+            "customer_id": "CUST001",
+            "name": "John Doe",
+            "email": "john@example.com",
+            "status": "active"
+        }
+        
+        # Test product object  
+        product_obj = {
+            "sku": "PROD-001",
+            "price": 29.99
+        }
+        
+        # Assert both schemas work
+        customer_valid = extraction_logic.validate_extracted_object(customer_obj, schemas["customer_records"])
+        product_valid = extraction_logic.validate_extracted_object(product_obj, schemas["product_catalog"])
+        
+        assert customer_valid is True
+        assert product_valid is True
+        
+        # Test confidence for both
+        customer_confidence = extraction_logic.calculate_confidence(customer_obj, schemas["customer_records"])
+        product_confidence = extraction_logic.calculate_confidence(product_obj, schemas["product_catalog"])
+        
+        assert customer_confidence > 0.9
+        assert product_confidence > 0.9
+    
+    def test_edge_cases(self, extraction_logic):
+        """Test edge cases in extraction logic"""
+        # Empty schema config
+        empty_schemas = extraction_logic.parse_schema_config({"other": {}})
+        assert len(empty_schemas) == 0
+        
+        # Schema with no fields
+        no_fields_config = {
+            "schema": {
+                "empty_schema": json.dumps({"name": "empty", "fields": []})
+            }
+        }
+        schemas = extraction_logic.parse_schema_config(no_fields_config)
+        assert len(schemas) == 1
+        assert len(schemas["empty_schema"].fields) == 0
+        
+        # Confidence calculation with no fields
+        confidence = extraction_logic.calculate_confidence({}, schemas["empty_schema"])
+        assert confidence >= 0.0

tests/unit/test_gateway/test_auth.py

@@ -0,0 +1,69 @@
+"""
+Tests for Gateway Authentication
+"""
+
+import pytest
+
+from trustgraph.gateway.auth import Authenticator
+
+
+class TestAuthenticator:
+    """Test cases for Authenticator class"""
+
+    def test_authenticator_initialization_with_token(self):
+        """Test Authenticator initialization with valid token"""
+        auth = Authenticator(token="test-token-123")
+        
+        assert auth.token == "test-token-123"
+        assert auth.allow_all is False
+
+    def test_authenticator_initialization_with_allow_all(self):
+        """Test Authenticator initialization with allow_all=True"""
+        auth = Authenticator(allow_all=True)
+        
+        assert auth.token is None
+        assert auth.allow_all is True
+
+    def test_authenticator_initialization_without_token_raises_error(self):
+        """Test Authenticator initialization without token raises RuntimeError"""
+        with pytest.raises(RuntimeError, match="Need a token"):
+            Authenticator()
+
+    def test_authenticator_initialization_with_empty_token_raises_error(self):
+        """Test Authenticator initialization with empty token raises RuntimeError"""
+        with pytest.raises(RuntimeError, match="Need a token"):
+            Authenticator(token="")
+
+    def test_permitted_with_allow_all_returns_true(self):
+        """Test permitted method returns True when allow_all is enabled"""
+        auth = Authenticator(allow_all=True)
+        
+        # Should return True regardless of token or roles
+        assert auth.permitted("any-token", []) is True
+        assert auth.permitted("different-token", ["admin"]) is True
+        assert auth.permitted(None, ["user"]) is True
+
+    def test_permitted_with_matching_token_returns_true(self):
+        """Test permitted method returns True with matching token"""
+        auth = Authenticator(token="secret-token")
+        
+        # Should return True when tokens match
+        assert auth.permitted("secret-token", []) is True
+        assert auth.permitted("secret-token", ["admin", "user"]) is True
+
+    def test_permitted_with_non_matching_token_returns_false(self):
+        """Test permitted method returns False with non-matching token"""
+        auth = Authenticator(token="secret-token")
+        
+        # Should return False when tokens don't match
+        assert auth.permitted("wrong-token", []) is False
+        assert auth.permitted("different-token", ["admin"]) is False
+        assert auth.permitted(None, ["user"]) is False
+
+    def test_permitted_with_token_and_allow_all_returns_true(self):
+        """Test permitted method with both token and allow_all set"""
+        auth = Authenticator(token="test-token", allow_all=True)
+        
+        # allow_all should take precedence
+        assert auth.permitted("any-token", []) is True
+        assert auth.permitted("wrong-token", ["admin"]) is True

tests/unit/test_gateway/test_config_receiver.py

@@ -0,0 +1,408 @@
+"""
+Tests for Gateway Config Receiver
+"""
+
+import pytest
+import asyncio
+import json
+from unittest.mock import Mock, patch, Mock, MagicMock
+import uuid
+
+from trustgraph.gateway.config.receiver import ConfigReceiver
+
+# Save the real method before patching
+_real_config_loader = ConfigReceiver.config_loader
+
+# Patch async methods at module level to prevent coroutine warnings
+ConfigReceiver.config_loader = Mock()
+
+
+class TestConfigReceiver:
+    """Test cases for ConfigReceiver class"""
+
+    def test_config_receiver_initialization(self):
+        """Test ConfigReceiver initialization"""
+        mock_pulsar_client = Mock()
+        
+        config_receiver = ConfigReceiver(mock_pulsar_client)
+        
+        assert config_receiver.pulsar_client == mock_pulsar_client
+        assert config_receiver.flow_handlers == []
+        assert config_receiver.flows == {}
+
+    def test_add_handler(self):
+        """Test adding flow handlers"""
+        mock_pulsar_client = Mock()
+        config_receiver = ConfigReceiver(mock_pulsar_client)
+        
+        handler1 = Mock()
+        handler2 = Mock()
+        
+        config_receiver.add_handler(handler1)
+        config_receiver.add_handler(handler2)
+        
+        assert len(config_receiver.flow_handlers) == 2
+        assert handler1 in config_receiver.flow_handlers
+        assert handler2 in config_receiver.flow_handlers
+
+    @pytest.mark.asyncio
+    async def test_on_config_with_new_flows(self):
+        """Test on_config method with new flows"""
+        mock_pulsar_client = Mock()
+        config_receiver = ConfigReceiver(mock_pulsar_client)
+        
+        # Track calls manually instead of using AsyncMock
+        start_flow_calls = []
+        
+        async def mock_start_flow(*args):
+            start_flow_calls.append(args)
+        
+        config_receiver.start_flow = mock_start_flow
+        
+        # Create mock message with flows
+        mock_msg = Mock()
+        mock_msg.value.return_value = Mock(
+            version="1.0",
+            config={
+                "flows": {
+                    "flow1": '{"name": "test_flow_1", "steps": []}',
+                    "flow2": '{"name": "test_flow_2", "steps": []}'
+                }
+            }
+        )
+        
+        await config_receiver.on_config(mock_msg, None, None)
+        
+        # Verify flows were added
+        assert "flow1" in config_receiver.flows
+        assert "flow2" in config_receiver.flows
+        assert config_receiver.flows["flow1"] == {"name": "test_flow_1", "steps": []}
+        assert config_receiver.flows["flow2"] == {"name": "test_flow_2", "steps": []}
+        
+        # Verify start_flow was called for each new flow
+        assert len(start_flow_calls) == 2
+        assert ("flow1", {"name": "test_flow_1", "steps": []}) in start_flow_calls
+        assert ("flow2", {"name": "test_flow_2", "steps": []}) in start_flow_calls
+
+    @pytest.mark.asyncio
+    async def test_on_config_with_removed_flows(self):
+        """Test on_config method with removed flows"""
+        mock_pulsar_client = Mock()
+        config_receiver = ConfigReceiver(mock_pulsar_client)
+        
+        # Pre-populate with existing flows
+        config_receiver.flows = {
+            "flow1": {"name": "test_flow_1", "steps": []},
+            "flow2": {"name": "test_flow_2", "steps": []}
+        }
+        
+        # Track calls manually instead of using AsyncMock
+        stop_flow_calls = []
+        
+        async def mock_stop_flow(*args):
+            stop_flow_calls.append(args)
+        
+        config_receiver.stop_flow = mock_stop_flow
+        
+        # Create mock message with only flow1 (flow2 removed)
+        mock_msg = Mock()
+        mock_msg.value.return_value = Mock(
+            version="1.0",
+            config={
+                "flows": {
+                    "flow1": '{"name": "test_flow_1", "steps": []}'
+                }
+            }
+        )
+        
+        await config_receiver.on_config(mock_msg, None, None)
+        
+        # Verify flow2 was removed
+        assert "flow1" in config_receiver.flows
+        assert "flow2" not in config_receiver.flows
+        
+        # Verify stop_flow was called for removed flow
+        assert len(stop_flow_calls) == 1
+        assert stop_flow_calls[0] == ("flow2", {"name": "test_flow_2", "steps": []})
+
+    @pytest.mark.asyncio
+    async def test_on_config_with_no_flows(self):
+        """Test on_config method with no flows in config"""
+        mock_pulsar_client = Mock()
+        config_receiver = ConfigReceiver(mock_pulsar_client)
+        
+        # Mock the start_flow and stop_flow methods with async functions
+        async def mock_start_flow(*args):
+            pass
+        async def mock_stop_flow(*args):
+            pass
+        config_receiver.start_flow = mock_start_flow
+        config_receiver.stop_flow = mock_stop_flow
+        
+        # Create mock message without flows
+        mock_msg = Mock()
+        mock_msg.value.return_value = Mock(
+            version="1.0",
+            config={}
+        )
+        
+        await config_receiver.on_config(mock_msg, None, None)
+        
+        # Verify no flows were added
+        assert config_receiver.flows == {}
+        
+        # Since no flows were in the config, the flow methods shouldn't be called
+        # (We can't easily assert this with simple async functions, but the test
+        # passes if no exceptions are thrown)
+
+    @pytest.mark.asyncio
+    async def test_on_config_exception_handling(self):
+        """Test on_config method handles exceptions gracefully"""
+        mock_pulsar_client = Mock()
+        config_receiver = ConfigReceiver(mock_pulsar_client)
+        
+        # Create mock message that will cause an exception
+        mock_msg = Mock()
+        mock_msg.value.side_effect = Exception("Test exception")
+        
+        # This should not raise an exception
+        await config_receiver.on_config(mock_msg, None, None)
+        
+        # Verify flows remain empty
+        assert config_receiver.flows == {}
+
+    @pytest.mark.asyncio
+    async def test_start_flow_with_handlers(self):
+        """Test start_flow method with multiple handlers"""
+        mock_pulsar_client = Mock()
+        config_receiver = ConfigReceiver(mock_pulsar_client)
+        
+        # Add mock handlers
+        handler1 = Mock()
+        handler1.start_flow = Mock()
+        handler2 = Mock()
+        handler2.start_flow = Mock()
+        
+        config_receiver.add_handler(handler1)
+        config_receiver.add_handler(handler2)
+        
+        flow_data = {"name": "test_flow", "steps": []}
+        
+        await config_receiver.start_flow("flow1", flow_data)
+        
+        # Verify all handlers were called
+        handler1.start_flow.assert_called_once_with("flow1", flow_data)
+        handler2.start_flow.assert_called_once_with("flow1", flow_data)
+
+    @pytest.mark.asyncio
+    async def test_start_flow_with_handler_exception(self):
+        """Test start_flow method handles handler exceptions"""
+        mock_pulsar_client = Mock()
+        config_receiver = ConfigReceiver(mock_pulsar_client)
+        
+        # Add mock handler that raises exception
+        handler = Mock()
+        handler.start_flow = Mock(side_effect=Exception("Handler error"))
+        
+        config_receiver.add_handler(handler)
+        
+        flow_data = {"name": "test_flow", "steps": []}
+        
+        # This should not raise an exception
+        await config_receiver.start_flow("flow1", flow_data)
+        
+        # Verify handler was called
+        handler.start_flow.assert_called_once_with("flow1", flow_data)
+
+    @pytest.mark.asyncio
+    async def test_stop_flow_with_handlers(self):
+        """Test stop_flow method with multiple handlers"""
+        mock_pulsar_client = Mock()
+        config_receiver = ConfigReceiver(mock_pulsar_client)
+        
+        # Add mock handlers
+        handler1 = Mock()
+        handler1.stop_flow = Mock()
+        handler2 = Mock()
+        handler2.stop_flow = Mock()
+        
+        config_receiver.add_handler(handler1)
+        config_receiver.add_handler(handler2)
+        
+        flow_data = {"name": "test_flow", "steps": []}
+        
+        await config_receiver.stop_flow("flow1", flow_data)
+        
+        # Verify all handlers were called
+        handler1.stop_flow.assert_called_once_with("flow1", flow_data)
+        handler2.stop_flow.assert_called_once_with("flow1", flow_data)
+
+    @pytest.mark.asyncio
+    async def test_stop_flow_with_handler_exception(self):
+        """Test stop_flow method handles handler exceptions"""
+        mock_pulsar_client = Mock()
+        config_receiver = ConfigReceiver(mock_pulsar_client)
+        
+        # Add mock handler that raises exception
+        handler = Mock()
+        handler.stop_flow = Mock(side_effect=Exception("Handler error"))
+        
+        config_receiver.add_handler(handler)
+        
+        flow_data = {"name": "test_flow", "steps": []}
+        
+        # This should not raise an exception
+        await config_receiver.stop_flow("flow1", flow_data)
+        
+        # Verify handler was called
+        handler.stop_flow.assert_called_once_with("flow1", flow_data)
+
+    @pytest.mark.asyncio
+    async def test_config_loader_creates_consumer(self):
+        """Test config_loader method creates Pulsar consumer"""
+        mock_pulsar_client = Mock()
+        
+        config_receiver = ConfigReceiver(mock_pulsar_client)
+        # Temporarily restore the real config_loader for this test
+        config_receiver.config_loader = _real_config_loader.__get__(config_receiver)
+        
+        # Mock Consumer class
+        with patch('trustgraph.gateway.config.receiver.Consumer') as mock_consumer_class, \
+             patch('uuid.uuid4') as mock_uuid:
+            
+            mock_uuid.return_value = "test-uuid"
+            mock_consumer = Mock()
+            async def mock_start():
+                pass
+            mock_consumer.start = mock_start
+            mock_consumer_class.return_value = mock_consumer
+            
+            # Create a task that will complete quickly
+            async def quick_task():
+                await config_receiver.config_loader()
+            
+            # Run the task with a timeout to prevent hanging
+            try:
+                await asyncio.wait_for(quick_task(), timeout=0.1)
+            except asyncio.TimeoutError:
+                # This is expected since the method runs indefinitely
+                pass
+            
+            # Verify Consumer was created with correct parameters
+            mock_consumer_class.assert_called_once()
+            call_args = mock_consumer_class.call_args
+            
+            assert call_args[1]['client'] == mock_pulsar_client
+            assert call_args[1]['subscriber'] == "gateway-test-uuid"
+            assert call_args[1]['handler'] == config_receiver.on_config
+            assert call_args[1]['start_of_messages'] is True
+
+    @patch('asyncio.create_task')
+    @pytest.mark.asyncio
+    async def test_start_creates_config_loader_task(self, mock_create_task):
+        """Test start method creates config loader task"""
+        mock_pulsar_client = Mock()
+        config_receiver = ConfigReceiver(mock_pulsar_client)
+        
+        # Mock create_task to avoid actually creating tasks with real coroutines
+        mock_task = Mock()
+        mock_create_task.return_value = mock_task
+        
+        await config_receiver.start()
+        
+        # Verify task was created
+        mock_create_task.assert_called_once()
+        
+        # Verify the argument passed to create_task is a coroutine
+        call_args = mock_create_task.call_args[0]
+        assert len(call_args) == 1  # Should have one argument (the coroutine)
+
+    @pytest.mark.asyncio
+    async def test_on_config_mixed_flow_operations(self):
+        """Test on_config with mixed add/remove operations"""
+        mock_pulsar_client = Mock()
+        config_receiver = ConfigReceiver(mock_pulsar_client)
+        
+        # Pre-populate with existing flows
+        config_receiver.flows = {
+            "flow1": {"name": "test_flow_1", "steps": []},
+            "flow2": {"name": "test_flow_2", "steps": []}
+        }
+        
+        # Track calls manually instead of using Mock
+        start_flow_calls = []
+        stop_flow_calls = []
+        
+        async def mock_start_flow(*args):
+            start_flow_calls.append(args)
+        
+        async def mock_stop_flow(*args):
+            stop_flow_calls.append(args)
+        
+        # Directly assign to avoid patch.object detecting async methods  
+        original_start_flow = config_receiver.start_flow
+        original_stop_flow = config_receiver.stop_flow
+        config_receiver.start_flow = mock_start_flow
+        config_receiver.stop_flow = mock_stop_flow
+        
+        try:
+            
+            # Create mock message with flow1 removed and flow3 added
+            mock_msg = Mock()
+            mock_msg.value.return_value = Mock(
+                version="1.0",
+                config={
+                    "flows": {
+                        "flow2": '{"name": "test_flow_2", "steps": []}',
+                        "flow3": '{"name": "test_flow_3", "steps": []}'
+                    }
+                }
+            )
+            
+            await config_receiver.on_config(mock_msg, None, None)
+            
+            # Verify final state
+            assert "flow1" not in config_receiver.flows
+            assert "flow2" in config_receiver.flows
+            assert "flow3" in config_receiver.flows
+            
+            # Verify operations
+            assert len(start_flow_calls) == 1
+            assert start_flow_calls[0] == ("flow3", {"name": "test_flow_3", "steps": []})
+            assert len(stop_flow_calls) == 1
+            assert stop_flow_calls[0] == ("flow1", {"name": "test_flow_1", "steps": []})
+        
+        finally:
+            # Restore original methods
+            config_receiver.start_flow = original_start_flow
+            config_receiver.stop_flow = original_stop_flow
+
+    @pytest.mark.asyncio
+    async def test_on_config_invalid_json_flow_data(self):
+        """Test on_config handles invalid JSON in flow data"""
+        mock_pulsar_client = Mock()
+        config_receiver = ConfigReceiver(mock_pulsar_client)
+        
+        # Mock the start_flow method with an async function
+        async def mock_start_flow(*args):
+            pass
+        config_receiver.start_flow = mock_start_flow
+        
+        # Create mock message with invalid JSON
+        mock_msg = Mock()
+        mock_msg.value.return_value = Mock(
+            version="1.0",
+            config={
+                "flows": {
+                    "flow1": '{"invalid": json}',  # Invalid JSON
+                    "flow2": '{"name": "valid_flow", "steps": []}'  # Valid JSON
+                }
+            }
+        )
+        
+        # This should handle the exception gracefully
+        await config_receiver.on_config(mock_msg, None, None)
+        
+        # The entire operation should fail due to JSON parsing error
+        # So no flows should be added
+        assert config_receiver.flows == {}

tests/unit/test_gateway/test_dispatch_config.py

@@ -0,0 +1,93 @@
+"""
+Tests for Gateway Config Dispatch
+"""
+
+import pytest
+from unittest.mock import MagicMock, patch, AsyncMock, Mock
+
+from trustgraph.gateway.dispatch.config import ConfigRequestor
+
+# Import parent class for local patching
+from trustgraph.gateway.dispatch.requestor import ServiceRequestor
+
+
+class TestConfigRequestor:
+    """Test cases for ConfigRequestor class"""
+
+    @patch('trustgraph.gateway.dispatch.config.TranslatorRegistry')
+    def test_config_requestor_initialization(self, mock_translator_registry):
+        """Test ConfigRequestor initialization"""
+        # Mock translators
+        mock_request_translator = Mock()
+        mock_response_translator = Mock()
+        mock_translator_registry.get_request_translator.return_value = mock_request_translator
+        mock_translator_registry.get_response_translator.return_value = mock_response_translator
+        
+        # Mock dependencies
+        mock_pulsar_client = Mock()
+        
+        requestor = ConfigRequestor(
+            pulsar_client=mock_pulsar_client,
+            consumer="test-consumer",
+            subscriber="test-subscriber",
+            timeout=60
+        )
+        
+        # Verify translator setup
+        mock_translator_registry.get_request_translator.assert_called_once_with("config")
+        mock_translator_registry.get_response_translator.assert_called_once_with("config")
+        
+        assert requestor.request_translator == mock_request_translator
+        assert requestor.response_translator == mock_response_translator
+
+    @patch('trustgraph.gateway.dispatch.config.TranslatorRegistry')
+    def test_config_requestor_to_request(self, mock_translator_registry):
+        """Test ConfigRequestor to_request method"""
+        # Mock translators
+        mock_request_translator = Mock()
+        mock_translator_registry.get_request_translator.return_value = mock_request_translator
+        mock_translator_registry.get_response_translator.return_value = Mock()
+        
+        # Setup translator response
+        mock_request_translator.to_pulsar.return_value = "translated_request"
+        
+        # Patch ServiceRequestor async methods with regular mocks (not AsyncMock)
+        with patch.object(ServiceRequestor, 'start', return_value=None), \
+             patch.object(ServiceRequestor, 'process', return_value=None):
+            requestor = ConfigRequestor(
+                pulsar_client=Mock(),
+                consumer="test-consumer", 
+                subscriber="test-subscriber"
+            )
+        
+        # Call to_request
+        result = requestor.to_request({"test": "body"})
+        
+        # Verify translator was called correctly
+        mock_request_translator.to_pulsar.assert_called_once_with({"test": "body"})
+        assert result == "translated_request"
+
+    @patch('trustgraph.gateway.dispatch.config.TranslatorRegistry')
+    def test_config_requestor_from_response(self, mock_translator_registry):
+        """Test ConfigRequestor from_response method"""
+        # Mock translators
+        mock_response_translator = Mock()
+        mock_translator_registry.get_request_translator.return_value = Mock()
+        mock_translator_registry.get_response_translator.return_value = mock_response_translator
+        
+        # Setup translator response
+        mock_response_translator.from_response_with_completion.return_value = "translated_response"
+        
+        requestor = ConfigRequestor(
+            pulsar_client=Mock(),
+            consumer="test-consumer",
+            subscriber="test-subscriber"
+        )
+        
+        # Call from_response
+        mock_message = Mock()
+        result = requestor.from_response(mock_message)
+        
+        # Verify translator was called correctly
+        mock_response_translator.from_response_with_completion.assert_called_once_with(mock_message)
+        assert result == "translated_response"

tests/unit/test_gateway/test_dispatch_manager.py

@@ -0,0 +1,558 @@
+"""
+Tests for Gateway Dispatcher Manager
+"""
+
+import pytest
+import asyncio
+from unittest.mock import Mock, patch, AsyncMock, MagicMock
+import uuid
+
+from trustgraph.gateway.dispatch.manager import DispatcherManager, DispatcherWrapper
+
+# Keep the real methods intact for proper testing
+
+
+class TestDispatcherWrapper:
+    """Test cases for DispatcherWrapper class"""
+
+    def test_dispatcher_wrapper_initialization(self):
+        """Test DispatcherWrapper initialization"""
+        mock_handler = Mock()
+        wrapper = DispatcherWrapper(mock_handler)
+        
+        assert wrapper.handler == mock_handler
+
+    @pytest.mark.asyncio
+    async def test_dispatcher_wrapper_process(self):
+        """Test DispatcherWrapper process method"""
+        mock_handler = AsyncMock()
+        wrapper = DispatcherWrapper(mock_handler)
+        
+        result = await wrapper.process("arg1", "arg2")
+        
+        mock_handler.assert_called_once_with("arg1", "arg2")
+        assert result == mock_handler.return_value
+
+
+class TestDispatcherManager:
+    """Test cases for DispatcherManager class"""
+
+    def test_dispatcher_manager_initialization(self):
+        """Test DispatcherManager initialization"""
+        mock_pulsar_client = Mock()
+        mock_config_receiver = Mock()
+        
+        manager = DispatcherManager(mock_pulsar_client, mock_config_receiver)
+        
+        assert manager.pulsar_client == mock_pulsar_client
+        assert manager.config_receiver == mock_config_receiver
+        assert manager.prefix == "api-gateway"  # default prefix
+        assert manager.flows == {}
+        assert manager.dispatchers == {}
+        
+        # Verify manager was added as handler to config receiver
+        mock_config_receiver.add_handler.assert_called_once_with(manager)
+
+    def test_dispatcher_manager_initialization_with_custom_prefix(self):
+        """Test DispatcherManager initialization with custom prefix"""
+        mock_pulsar_client = Mock()
+        mock_config_receiver = Mock()
+        
+        manager = DispatcherManager(mock_pulsar_client, mock_config_receiver, prefix="custom-prefix")
+        
+        assert manager.prefix == "custom-prefix"
+
+    @pytest.mark.asyncio
+    async def test_start_flow(self):
+        """Test start_flow method"""
+        mock_pulsar_client = Mock()
+        mock_config_receiver = Mock()
+        manager = DispatcherManager(mock_pulsar_client, mock_config_receiver)
+        
+        flow_data = {"name": "test_flow", "steps": []}
+        
+        await manager.start_flow("flow1", flow_data)
+        
+        assert "flow1" in manager.flows
+        assert manager.flows["flow1"] == flow_data
+
+    @pytest.mark.asyncio
+    async def test_stop_flow(self):
+        """Test stop_flow method"""
+        mock_pulsar_client = Mock()
+        mock_config_receiver = Mock()
+        manager = DispatcherManager(mock_pulsar_client, mock_config_receiver)
+        
+        # Pre-populate with a flow
+        flow_data = {"name": "test_flow", "steps": []}
+        manager.flows["flow1"] = flow_data
+        
+        await manager.stop_flow("flow1", flow_data)
+        
+        assert "flow1" not in manager.flows
+
+    def test_dispatch_global_service_returns_wrapper(self):
+        """Test dispatch_global_service returns DispatcherWrapper"""
+        mock_pulsar_client = Mock()
+        mock_config_receiver = Mock()
+        manager = DispatcherManager(mock_pulsar_client, mock_config_receiver)
+        
+        wrapper = manager.dispatch_global_service()
+        
+        assert isinstance(wrapper, DispatcherWrapper)
+        assert wrapper.handler == manager.process_global_service
+
+    def test_dispatch_core_export_returns_wrapper(self):
+        """Test dispatch_core_export returns DispatcherWrapper"""
+        mock_pulsar_client = Mock()
+        mock_config_receiver = Mock()
+        manager = DispatcherManager(mock_pulsar_client, mock_config_receiver)
+        
+        wrapper = manager.dispatch_core_export()
+        
+        assert isinstance(wrapper, DispatcherWrapper)
+        assert wrapper.handler == manager.process_core_export
+
+    def test_dispatch_core_import_returns_wrapper(self):
+        """Test dispatch_core_import returns DispatcherWrapper"""
+        mock_pulsar_client = Mock()
+        mock_config_receiver = Mock()
+        manager = DispatcherManager(mock_pulsar_client, mock_config_receiver)
+        
+        wrapper = manager.dispatch_core_import()
+        
+        assert isinstance(wrapper, DispatcherWrapper)
+        assert wrapper.handler == manager.process_core_import
+
+    @pytest.mark.asyncio
+    async def test_process_core_import(self):
+        """Test process_core_import method"""
+        mock_pulsar_client = Mock()
+        mock_config_receiver = Mock()
+        manager = DispatcherManager(mock_pulsar_client, mock_config_receiver)
+        
+        with patch('trustgraph.gateway.dispatch.manager.CoreImport') as mock_core_import:
+            mock_importer = Mock()
+            mock_importer.process = AsyncMock(return_value="import_result")
+            mock_core_import.return_value = mock_importer
+            
+            result = await manager.process_core_import("data", "error", "ok", "request")
+            
+            mock_core_import.assert_called_once_with(mock_pulsar_client)
+            mock_importer.process.assert_called_once_with("data", "error", "ok", "request")
+            assert result == "import_result"
+
+    @pytest.mark.asyncio
+    async def test_process_core_export(self):
+        """Test process_core_export method"""
+        mock_pulsar_client = Mock()
+        mock_config_receiver = Mock()
+        manager = DispatcherManager(mock_pulsar_client, mock_config_receiver)
+        
+        with patch('trustgraph.gateway.dispatch.manager.CoreExport') as mock_core_export:
+            mock_exporter = Mock()
+            mock_exporter.process = AsyncMock(return_value="export_result")
+            mock_core_export.return_value = mock_exporter
+            
+            result = await manager.process_core_export("data", "error", "ok", "request")
+            
+            mock_core_export.assert_called_once_with(mock_pulsar_client)
+            mock_exporter.process.assert_called_once_with("data", "error", "ok", "request")
+            assert result == "export_result"
+
+    @pytest.mark.asyncio
+    async def test_process_global_service(self):
+        """Test process_global_service method"""
+        mock_pulsar_client = Mock()
+        mock_config_receiver = Mock()
+        manager = DispatcherManager(mock_pulsar_client, mock_config_receiver)
+        
+        manager.invoke_global_service = AsyncMock(return_value="global_result")
+        
+        params = {"kind": "test_kind"}
+        result = await manager.process_global_service("data", "responder", params)
+        
+        manager.invoke_global_service.assert_called_once_with("data", "responder", "test_kind")
+        assert result == "global_result"
+
+    @pytest.mark.asyncio
+    async def test_invoke_global_service_with_existing_dispatcher(self):
+        """Test invoke_global_service with existing dispatcher"""
+        mock_pulsar_client = Mock()
+        mock_config_receiver = Mock()
+        manager = DispatcherManager(mock_pulsar_client, mock_config_receiver)
+        
+        # Pre-populate with existing dispatcher
+        mock_dispatcher = Mock()
+        mock_dispatcher.process = AsyncMock(return_value="cached_result")
+        manager.dispatchers[(None, "config")] = mock_dispatcher
+        
+        result = await manager.invoke_global_service("data", "responder", "config")
+        
+        mock_dispatcher.process.assert_called_once_with("data", "responder")
+        assert result == "cached_result"
+
+    @pytest.mark.asyncio
+    async def test_invoke_global_service_creates_new_dispatcher(self):
+        """Test invoke_global_service creates new dispatcher"""
+        mock_pulsar_client = Mock()
+        mock_config_receiver = Mock()
+        manager = DispatcherManager(mock_pulsar_client, mock_config_receiver)
+        
+        with patch('trustgraph.gateway.dispatch.manager.global_dispatchers') as mock_dispatchers:
+            mock_dispatcher_class = Mock()
+            mock_dispatcher = Mock()
+            mock_dispatcher.start = AsyncMock()
+            mock_dispatcher.process = AsyncMock(return_value="new_result")
+            mock_dispatcher_class.return_value = mock_dispatcher
+            mock_dispatchers.__getitem__.return_value = mock_dispatcher_class
+            
+            result = await manager.invoke_global_service("data", "responder", "config")
+            
+            # Verify dispatcher was created with correct parameters
+            mock_dispatcher_class.assert_called_once_with(
+                pulsar_client=mock_pulsar_client,
+                timeout=120,
+                consumer="api-gateway-config-request",
+                subscriber="api-gateway-config-request"
+            )
+            mock_dispatcher.start.assert_called_once()
+            mock_dispatcher.process.assert_called_once_with("data", "responder")
+            
+            # Verify dispatcher was cached
+            assert manager.dispatchers[(None, "config")] == mock_dispatcher
+            assert result == "new_result"
+
+    def test_dispatch_flow_import_returns_method(self):
+        """Test dispatch_flow_import returns correct method"""
+        mock_pulsar_client = Mock()
+        mock_config_receiver = Mock()
+        manager = DispatcherManager(mock_pulsar_client, mock_config_receiver)
+        
+        result = manager.dispatch_flow_import()
+        
+        assert result == manager.process_flow_import
+
+    def test_dispatch_flow_export_returns_method(self):
+        """Test dispatch_flow_export returns correct method"""
+        mock_pulsar_client = Mock()
+        mock_config_receiver = Mock()
+        manager = DispatcherManager(mock_pulsar_client, mock_config_receiver)
+        
+        result = manager.dispatch_flow_export()
+        
+        assert result == manager.process_flow_export
+
+    def test_dispatch_socket_returns_method(self):
+        """Test dispatch_socket returns correct method"""
+        mock_pulsar_client = Mock()
+        mock_config_receiver = Mock()
+        manager = DispatcherManager(mock_pulsar_client, mock_config_receiver)
+        
+        result = manager.dispatch_socket()
+        
+        assert result == manager.process_socket
+
+    def test_dispatch_flow_service_returns_wrapper(self):
+        """Test dispatch_flow_service returns DispatcherWrapper"""
+        mock_pulsar_client = Mock()
+        mock_config_receiver = Mock()
+        manager = DispatcherManager(mock_pulsar_client, mock_config_receiver)
+        
+        wrapper = manager.dispatch_flow_service()
+        
+        assert isinstance(wrapper, DispatcherWrapper)
+        assert wrapper.handler == manager.process_flow_service
+
+    @pytest.mark.asyncio
+    async def test_process_flow_import_with_valid_flow_and_kind(self):
+        """Test process_flow_import with valid flow and kind"""
+        mock_pulsar_client = Mock()
+        mock_config_receiver = Mock()
+        manager = DispatcherManager(mock_pulsar_client, mock_config_receiver)
+        
+        # Setup test flow
+        manager.flows["test_flow"] = {
+            "interfaces": {
+                "triples-store": {"queue": "test_queue"}
+            }
+        }
+        
+        with patch('trustgraph.gateway.dispatch.manager.import_dispatchers') as mock_dispatchers, \
+             patch('uuid.uuid4') as mock_uuid:
+            mock_uuid.return_value = "test-uuid"
+            mock_dispatcher_class = Mock()
+            mock_dispatcher = Mock()
+            mock_dispatcher.start = AsyncMock()
+            mock_dispatcher_class.return_value = mock_dispatcher
+            mock_dispatchers.__getitem__.return_value = mock_dispatcher_class
+            mock_dispatchers.__contains__.return_value = True
+            
+            params = {"flow": "test_flow", "kind": "triples"}
+            result = await manager.process_flow_import("ws", "running", params)
+            
+            mock_dispatcher_class.assert_called_once_with(
+                pulsar_client=mock_pulsar_client,
+                ws="ws",
+                running="running",
+                queue={"queue": "test_queue"}
+            )
+            mock_dispatcher.start.assert_called_once()
+            assert result == mock_dispatcher
+
+    @pytest.mark.asyncio
+    async def test_process_flow_import_with_invalid_flow(self):
+        """Test process_flow_import with invalid flow"""
+        mock_pulsar_client = Mock()
+        mock_config_receiver = Mock()
+        manager = DispatcherManager(mock_pulsar_client, mock_config_receiver)
+        
+        params = {"flow": "invalid_flow", "kind": "triples"}
+        
+        with pytest.raises(RuntimeError, match="Invalid flow"):
+            await manager.process_flow_import("ws", "running", params)
+
+    @pytest.mark.asyncio
+    async def test_process_flow_import_with_invalid_kind(self):
+        """Test process_flow_import with invalid kind"""
+        import warnings
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore", RuntimeWarning)
+            mock_pulsar_client = Mock()
+            mock_config_receiver = Mock()
+            manager = DispatcherManager(mock_pulsar_client, mock_config_receiver)
+        
+        # Setup test flow
+        manager.flows["test_flow"] = {
+            "interfaces": {
+                "triples-store": {"queue": "test_queue"}
+            }
+        }
+        
+        with patch('trustgraph.gateway.dispatch.manager.import_dispatchers') as mock_dispatchers:
+            mock_dispatchers.__contains__.return_value = False
+            
+            params = {"flow": "test_flow", "kind": "invalid_kind"}
+            
+            with pytest.raises(RuntimeError, match="Invalid kind"):
+                await manager.process_flow_import("ws", "running", params)
+
+    @pytest.mark.asyncio
+    async def test_process_flow_export_with_valid_flow_and_kind(self):
+        """Test process_flow_export with valid flow and kind"""
+        mock_pulsar_client = Mock()
+        mock_config_receiver = Mock()
+        manager = DispatcherManager(mock_pulsar_client, mock_config_receiver)
+        
+        # Setup test flow
+        manager.flows["test_flow"] = {
+            "interfaces": {
+                "triples-store": {"queue": "test_queue"}
+            }
+        }
+        
+        with patch('trustgraph.gateway.dispatch.manager.export_dispatchers') as mock_dispatchers, \
+             patch('uuid.uuid4') as mock_uuid:
+            mock_uuid.return_value = "test-uuid"
+            mock_dispatcher_class = Mock()
+            mock_dispatcher = Mock()
+            mock_dispatcher_class.return_value = mock_dispatcher
+            mock_dispatchers.__getitem__.return_value = mock_dispatcher_class
+            mock_dispatchers.__contains__.return_value = True
+            
+            params = {"flow": "test_flow", "kind": "triples"}
+            result = await manager.process_flow_export("ws", "running", params)
+            
+            mock_dispatcher_class.assert_called_once_with(
+                pulsar_client=mock_pulsar_client,
+                ws="ws",
+                running="running",
+                queue={"queue": "test_queue"},
+                consumer="api-gateway-test-uuid",
+                subscriber="api-gateway-test-uuid"
+            )
+            assert result == mock_dispatcher
+
+    @pytest.mark.asyncio
+    async def test_process_socket(self):
+        """Test process_socket method"""
+        mock_pulsar_client = Mock()
+        mock_config_receiver = Mock()
+        manager = DispatcherManager(mock_pulsar_client, mock_config_receiver)
+        
+        with patch('trustgraph.gateway.dispatch.manager.Mux') as mock_mux:
+            mock_mux_instance = Mock()
+            mock_mux.return_value = mock_mux_instance
+            
+            result = await manager.process_socket("ws", "running", {})
+            
+            mock_mux.assert_called_once_with(manager, "ws", "running")
+            assert result == mock_mux_instance
+
+    @pytest.mark.asyncio
+    async def test_process_flow_service(self):
+        """Test process_flow_service method"""
+        mock_pulsar_client = Mock()
+        mock_config_receiver = Mock()
+        manager = DispatcherManager(mock_pulsar_client, mock_config_receiver)
+        
+        manager.invoke_flow_service = AsyncMock(return_value="flow_result")
+        
+        params = {"flow": "test_flow", "kind": "agent"}
+        result = await manager.process_flow_service("data", "responder", params)
+        
+        manager.invoke_flow_service.assert_called_once_with("data", "responder", "test_flow", "agent")
+        assert result == "flow_result"
+
+    @pytest.mark.asyncio
+    async def test_invoke_flow_service_with_existing_dispatcher(self):
+        """Test invoke_flow_service with existing dispatcher"""
+        mock_pulsar_client = Mock()
+        mock_config_receiver = Mock()
+        manager = DispatcherManager(mock_pulsar_client, mock_config_receiver)
+        
+        # Add flow to the flows dictionary
+        manager.flows["test_flow"] = {"services": {"agent": {}}}
+        
+        # Pre-populate with existing dispatcher
+        mock_dispatcher = Mock()
+        mock_dispatcher.process = AsyncMock(return_value="cached_result")
+        manager.dispatchers[("test_flow", "agent")] = mock_dispatcher
+        
+        result = await manager.invoke_flow_service("data", "responder", "test_flow", "agent")
+        
+        mock_dispatcher.process.assert_called_once_with("data", "responder")
+        assert result == "cached_result"
+
+    @pytest.mark.asyncio
+    async def test_invoke_flow_service_creates_request_response_dispatcher(self):
+        """Test invoke_flow_service creates request-response dispatcher"""
+        mock_pulsar_client = Mock()
+        mock_config_receiver = Mock()
+        manager = DispatcherManager(mock_pulsar_client, mock_config_receiver)
+        
+        # Setup test flow
+        manager.flows["test_flow"] = {
+            "interfaces": {
+                "agent": {
+                    "request": "agent_request_queue",
+                    "response": "agent_response_queue"
+                }
+            }
+        }
+        
+        with patch('trustgraph.gateway.dispatch.manager.request_response_dispatchers') as mock_dispatchers:
+            mock_dispatcher_class = Mock()
+            mock_dispatcher = Mock()
+            mock_dispatcher.start = AsyncMock()
+            mock_dispatcher.process = AsyncMock(return_value="new_result")
+            mock_dispatcher_class.return_value = mock_dispatcher
+            mock_dispatchers.__getitem__.return_value = mock_dispatcher_class
+            mock_dispatchers.__contains__.return_value = True
+            
+            result = await manager.invoke_flow_service("data", "responder", "test_flow", "agent")
+            
+            # Verify dispatcher was created with correct parameters
+            mock_dispatcher_class.assert_called_once_with(
+                pulsar_client=mock_pulsar_client,
+                request_queue="agent_request_queue",
+                response_queue="agent_response_queue",
+                timeout=120,
+                consumer="api-gateway-test_flow-agent-request",
+                subscriber="api-gateway-test_flow-agent-request"
+            )
+            mock_dispatcher.start.assert_called_once()
+            mock_dispatcher.process.assert_called_once_with("data", "responder")
+            
+            # Verify dispatcher was cached
+            assert manager.dispatchers[("test_flow", "agent")] == mock_dispatcher
+            assert result == "new_result"
+
+    @pytest.mark.asyncio
+    async def test_invoke_flow_service_creates_sender_dispatcher(self):
+        """Test invoke_flow_service creates sender dispatcher"""
+        mock_pulsar_client = Mock()
+        mock_config_receiver = Mock()
+        manager = DispatcherManager(mock_pulsar_client, mock_config_receiver)
+        
+        # Setup test flow
+        manager.flows["test_flow"] = {
+            "interfaces": {
+                "text-load": {"queue": "text_load_queue"}
+            }
+        }
+        
+        with patch('trustgraph.gateway.dispatch.manager.request_response_dispatchers') as mock_rr_dispatchers, \
+             patch('trustgraph.gateway.dispatch.manager.sender_dispatchers') as mock_sender_dispatchers:
+            mock_rr_dispatchers.__contains__.return_value = False
+            mock_sender_dispatchers.__contains__.return_value = True
+            
+            mock_dispatcher_class = Mock()
+            mock_dispatcher = Mock()
+            mock_dispatcher.start = AsyncMock()
+            mock_dispatcher.process = AsyncMock(return_value="sender_result")
+            mock_dispatcher_class.return_value = mock_dispatcher
+            mock_sender_dispatchers.__getitem__.return_value = mock_dispatcher_class
+            
+            result = await manager.invoke_flow_service("data", "responder", "test_flow", "text-load")
+            
+            # Verify dispatcher was created with correct parameters
+            mock_dispatcher_class.assert_called_once_with(
+                pulsar_client=mock_pulsar_client,
+                queue={"queue": "text_load_queue"}
+            )
+            mock_dispatcher.start.assert_called_once()
+            mock_dispatcher.process.assert_called_once_with("data", "responder")
+            
+            # Verify dispatcher was cached
+            assert manager.dispatchers[("test_flow", "text-load")] == mock_dispatcher
+            assert result == "sender_result"
+
+    @pytest.mark.asyncio
+    async def test_invoke_flow_service_invalid_flow(self):
+        """Test invoke_flow_service with invalid flow"""
+        mock_pulsar_client = Mock()
+        mock_config_receiver = Mock()
+        manager = DispatcherManager(mock_pulsar_client, mock_config_receiver)
+        
+        with pytest.raises(RuntimeError, match="Invalid flow"):
+            await manager.invoke_flow_service("data", "responder", "invalid_flow", "agent")
+
+    @pytest.mark.asyncio
+    async def test_invoke_flow_service_unsupported_kind_by_flow(self):
+        """Test invoke_flow_service with kind not supported by flow"""
+        mock_pulsar_client = Mock()
+        mock_config_receiver = Mock()
+        manager = DispatcherManager(mock_pulsar_client, mock_config_receiver)
+        
+        # Setup test flow without agent interface
+        manager.flows["test_flow"] = {
+            "interfaces": {
+                "text-completion": {"request": "req", "response": "resp"}
+            }
+        }
+        
+        with pytest.raises(RuntimeError, match="This kind not supported by flow"):
+            await manager.invoke_flow_service("data", "responder", "test_flow", "agent")
+
+    @pytest.mark.asyncio
+    async def test_invoke_flow_service_invalid_kind(self):
+        """Test invoke_flow_service with invalid kind"""
+        mock_pulsar_client = Mock()
+        mock_config_receiver = Mock()
+        manager = DispatcherManager(mock_pulsar_client, mock_config_receiver)
+        
+        # Setup test flow with interface but unsupported kind
+        manager.flows["test_flow"] = {
+            "interfaces": {
+                "invalid-kind": {"request": "req", "response": "resp"}
+            }
+        }
+        
+        with patch('trustgraph.gateway.dispatch.manager.request_response_dispatchers') as mock_rr_dispatchers, \
+             patch('trustgraph.gateway.dispatch.manager.sender_dispatchers') as mock_sender_dispatchers:
+            mock_rr_dispatchers.__contains__.return_value = False
+            mock_sender_dispatchers.__contains__.return_value = False
+            
+            with pytest.raises(RuntimeError, match="Invalid kind"):
+                await manager.invoke_flow_service("data", "responder", "test_flow", "invalid-kind")

tests/unit/test_gateway/test_dispatch_mux.py

@@ -0,0 +1,171 @@
+"""
+Tests for Gateway Dispatch Mux
+"""
+
+import pytest
+import asyncio
+from unittest.mock import MagicMock, AsyncMock
+
+from trustgraph.gateway.dispatch.mux import Mux, MAX_QUEUE_SIZE
+
+
+class TestMux:
+    """Test cases for Mux class"""
+
+    def test_mux_initialization(self):
+        """Test Mux initialization"""
+        mock_dispatcher_manager = MagicMock()
+        mock_ws = MagicMock()
+        mock_running = MagicMock()
+        
+        mux = Mux(
+            dispatcher_manager=mock_dispatcher_manager,
+            ws=mock_ws,
+            running=mock_running
+        )
+        
+        assert mux.dispatcher_manager == mock_dispatcher_manager
+        assert mux.ws == mock_ws
+        assert mux.running == mock_running
+        assert isinstance(mux.q, asyncio.Queue)
+        assert mux.q.maxsize == MAX_QUEUE_SIZE
+
+    @pytest.mark.asyncio
+    async def test_mux_destroy_with_websocket(self):
+        """Test Mux destroy method with websocket"""
+        mock_dispatcher_manager = MagicMock()
+        mock_ws = AsyncMock()
+        mock_running = MagicMock()
+        
+        mux = Mux(
+            dispatcher_manager=mock_dispatcher_manager,
+            ws=mock_ws,
+            running=mock_running
+        )
+        
+        # Call destroy
+        await mux.destroy()
+        
+        # Verify running.stop was called
+        mock_running.stop.assert_called_once()
+        
+        # Verify websocket close was called
+        mock_ws.close.assert_called_once()
+
+    @pytest.mark.asyncio
+    async def test_mux_destroy_without_websocket(self):
+        """Test Mux destroy method without websocket"""
+        mock_dispatcher_manager = MagicMock()
+        mock_running = MagicMock()
+        
+        mux = Mux(
+            dispatcher_manager=mock_dispatcher_manager,
+            ws=None,
+            running=mock_running
+        )
+        
+        # Call destroy
+        await mux.destroy()
+        
+        # Verify running.stop was called
+        mock_running.stop.assert_called_once()
+        # No websocket to close
+
+    @pytest.mark.asyncio
+    async def test_mux_receive_valid_message(self):
+        """Test Mux receive method with valid message"""
+        mock_dispatcher_manager = MagicMock()
+        mock_ws = AsyncMock()
+        mock_running = MagicMock()
+        
+        mux = Mux(
+            dispatcher_manager=mock_dispatcher_manager,
+            ws=mock_ws,
+            running=mock_running
+        )
+        
+        # Mock message with valid JSON
+        mock_msg = MagicMock()
+        mock_msg.json.return_value = {
+            "request": {"type": "test"},
+            "id": "test-id-123",
+            "service": "test-service"
+        }
+        
+        # Call receive
+        await mux.receive(mock_msg)
+        
+        # Verify json was called
+        mock_msg.json.assert_called_once()
+
+    @pytest.mark.asyncio
+    async def test_mux_receive_message_without_request(self):
+        """Test Mux receive method with message missing request field"""
+        mock_dispatcher_manager = MagicMock()
+        mock_ws = AsyncMock()
+        mock_running = MagicMock()
+        
+        mux = Mux(
+            dispatcher_manager=mock_dispatcher_manager,
+            ws=mock_ws,
+            running=mock_running
+        )
+        
+        # Mock message without request field
+        mock_msg = MagicMock()
+        mock_msg.json.return_value = {
+            "id": "test-id-123"
+        }
+        
+        # receive method should handle the RuntimeError internally
+        # Based on the code, it seems to catch exceptions
+        await mux.receive(mock_msg)
+        
+        mock_ws.send_json.assert_called_once_with({"error": "Bad message"})
+
+    @pytest.mark.asyncio
+    async def test_mux_receive_message_without_id(self):
+        """Test Mux receive method with message missing id field"""
+        mock_dispatcher_manager = MagicMock()
+        mock_ws = AsyncMock()
+        mock_running = MagicMock()
+        
+        mux = Mux(
+            dispatcher_manager=mock_dispatcher_manager,
+            ws=mock_ws,
+            running=mock_running
+        )
+        
+        # Mock message without id field
+        mock_msg = MagicMock()
+        mock_msg.json.return_value = {
+            "request": {"type": "test"}
+        }
+        
+        # receive method should handle the RuntimeError internally
+        await mux.receive(mock_msg)
+        
+        mock_ws.send_json.assert_called_once_with({"error": "Bad message"})
+
+    @pytest.mark.asyncio
+    async def test_mux_receive_invalid_json(self):
+        """Test Mux receive method with invalid JSON"""
+        mock_dispatcher_manager = MagicMock()
+        mock_ws = AsyncMock()
+        mock_running = MagicMock()
+        
+        mux = Mux(
+            dispatcher_manager=mock_dispatcher_manager,
+            ws=mock_ws,
+            running=mock_running
+        )
+        
+        # Mock message with invalid JSON
+        mock_msg = MagicMock()
+        mock_msg.json.side_effect = ValueError("Invalid JSON")
+        
+        # receive method should handle the ValueError internally
+        await mux.receive(mock_msg)
+        
+        mock_msg.json.assert_called_once()
+        mock_ws.send_json.assert_called_once_with({"error": "Invalid JSON"})

tests/unit/test_gateway/test_dispatch_requestor.py

@@ -0,0 +1,118 @@
+"""
+Tests for Gateway Service Requestor
+"""
+
+import pytest
+from unittest.mock import MagicMock, AsyncMock, patch
+
+from trustgraph.gateway.dispatch.requestor import ServiceRequestor
+
+
+class TestServiceRequestor:
+    """Test cases for ServiceRequestor class"""
+
+    @patch('trustgraph.gateway.dispatch.requestor.Publisher')
+    @patch('trustgraph.gateway.dispatch.requestor.Subscriber')
+    def test_service_requestor_initialization(self, mock_subscriber, mock_publisher):
+        """Test ServiceRequestor initialization"""
+        mock_pulsar_client = MagicMock()
+        mock_request_schema = MagicMock()
+        mock_response_schema = MagicMock()
+        
+        requestor = ServiceRequestor(
+            pulsar_client=mock_pulsar_client,
+            request_queue="test-request-queue",
+            request_schema=mock_request_schema,
+            response_queue="test-response-queue",
+            response_schema=mock_response_schema,
+            subscription="test-subscription",
+            consumer_name="test-consumer",
+            timeout=300
+        )
+        
+        # Verify Publisher was created correctly
+        mock_publisher.assert_called_once_with(
+            mock_pulsar_client, "test-request-queue", schema=mock_request_schema
+        )
+        
+        # Verify Subscriber was created correctly
+        mock_subscriber.assert_called_once_with(
+            mock_pulsar_client, "test-response-queue",
+            "test-subscription", "test-consumer", mock_response_schema
+        )
+        
+        assert requestor.timeout == 300
+        assert requestor.running is True
+
+    @patch('trustgraph.gateway.dispatch.requestor.Publisher')
+    @patch('trustgraph.gateway.dispatch.requestor.Subscriber')
+    def test_service_requestor_with_defaults(self, mock_subscriber, mock_publisher):
+        """Test ServiceRequestor initialization with default parameters"""
+        mock_pulsar_client = MagicMock()
+        mock_request_schema = MagicMock()
+        mock_response_schema = MagicMock()
+        
+        requestor = ServiceRequestor(
+            pulsar_client=mock_pulsar_client,
+            request_queue="test-queue",
+            request_schema=mock_request_schema,
+            response_queue="response-queue",
+            response_schema=mock_response_schema
+        )
+        
+        # Verify default values
+        mock_subscriber.assert_called_once_with(
+            mock_pulsar_client, "response-queue",
+            "api-gateway", "api-gateway", mock_response_schema
+        )
+        assert requestor.timeout == 600  # Default timeout
+
+    @patch('trustgraph.gateway.dispatch.requestor.Publisher')
+    @patch('trustgraph.gateway.dispatch.requestor.Subscriber')
+    @pytest.mark.asyncio
+    async def test_service_requestor_start(self, mock_subscriber, mock_publisher):
+        """Test ServiceRequestor start method"""
+        mock_pulsar_client = MagicMock()
+        mock_sub_instance = AsyncMock()
+        mock_pub_instance = AsyncMock()
+        mock_subscriber.return_value = mock_sub_instance
+        mock_publisher.return_value = mock_pub_instance
+        
+        requestor = ServiceRequestor(
+            pulsar_client=mock_pulsar_client,
+            request_queue="test-queue",
+            request_schema=MagicMock(),
+            response_queue="response-queue",
+            response_schema=MagicMock()
+        )
+        
+        # Call start
+        await requestor.start()
+        
+        # Verify both subscriber and publisher start were called
+        mock_sub_instance.start.assert_called_once()
+        mock_pub_instance.start.assert_called_once()
+        assert requestor.running is True
+
+    @patch('trustgraph.gateway.dispatch.requestor.Publisher')
+    @patch('trustgraph.gateway.dispatch.requestor.Subscriber')
+    def test_service_requestor_attributes(self, mock_subscriber, mock_publisher):
+        """Test ServiceRequestor has correct attributes"""
+        mock_pulsar_client = MagicMock()
+        mock_pub_instance = AsyncMock()
+        mock_sub_instance = AsyncMock()
+        mock_publisher.return_value = mock_pub_instance
+        mock_subscriber.return_value = mock_sub_instance
+        
+        requestor = ServiceRequestor(
+            pulsar_client=mock_pulsar_client,
+            request_queue="test-queue",
+            request_schema=MagicMock(),
+            response_queue="response-queue",
+            response_schema=MagicMock()
+        )
+        
+        # Verify attributes are set correctly
+        assert requestor.pub == mock_pub_instance
+        assert requestor.sub == mock_sub_instance
+        assert requestor.running is True

tests/unit/test_gateway/test_dispatch_sender.py

@@ -0,0 +1,120 @@
+"""
+Tests for Gateway Service Sender
+"""
+
+import pytest
+from unittest.mock import MagicMock, AsyncMock, patch
+
+from trustgraph.gateway.dispatch.sender import ServiceSender
+
+
+class TestServiceSender:
+    """Test cases for ServiceSender class"""
+
+    @patch('trustgraph.gateway.dispatch.sender.Publisher')
+    def test_service_sender_initialization(self, mock_publisher):
+        """Test ServiceSender initialization"""
+        mock_pulsar_client = MagicMock()
+        mock_schema = MagicMock()
+        
+        sender = ServiceSender(
+            pulsar_client=mock_pulsar_client,
+            queue="test-queue",
+            schema=mock_schema
+        )
+        
+        # Verify Publisher was created correctly
+        mock_publisher.assert_called_once_with(
+            mock_pulsar_client, "test-queue", schema=mock_schema
+        )
+
+    @patch('trustgraph.gateway.dispatch.sender.Publisher')
+    @pytest.mark.asyncio
+    async def test_service_sender_start(self, mock_publisher):
+        """Test ServiceSender start method"""
+        mock_pub_instance = AsyncMock()
+        mock_publisher.return_value = mock_pub_instance
+        
+        sender = ServiceSender(
+            pulsar_client=MagicMock(),
+            queue="test-queue",
+            schema=MagicMock()
+        )
+        
+        # Call start
+        await sender.start()
+        
+        # Verify publisher start was called
+        mock_pub_instance.start.assert_called_once()
+
+    @patch('trustgraph.gateway.dispatch.sender.Publisher')
+    @pytest.mark.asyncio
+    async def test_service_sender_stop(self, mock_publisher):
+        """Test ServiceSender stop method"""
+        mock_pub_instance = AsyncMock()
+        mock_publisher.return_value = mock_pub_instance
+        
+        sender = ServiceSender(
+            pulsar_client=MagicMock(),
+            queue="test-queue",
+            schema=MagicMock()
+        )
+        
+        # Call stop
+        await sender.stop()
+        
+        # Verify publisher stop was called
+        mock_pub_instance.stop.assert_called_once()
+
+    @patch('trustgraph.gateway.dispatch.sender.Publisher')
+    def test_service_sender_to_request_not_implemented(self, mock_publisher):
+        """Test ServiceSender to_request method raises RuntimeError"""
+        sender = ServiceSender(
+            pulsar_client=MagicMock(),
+            queue="test-queue",
+            schema=MagicMock()
+        )
+        
+        with pytest.raises(RuntimeError, match="Not defined"):
+            sender.to_request({"test": "request"})
+
+    @patch('trustgraph.gateway.dispatch.sender.Publisher')
+    @pytest.mark.asyncio
+    async def test_service_sender_process(self, mock_publisher):
+        """Test ServiceSender process method"""
+        mock_pub_instance = AsyncMock()
+        mock_publisher.return_value = mock_pub_instance
+        
+        # Create a concrete sender that implements to_request
+        class ConcreteSender(ServiceSender):
+            def to_request(self, request):
+                return {"processed": request}
+        
+        sender = ConcreteSender(
+            pulsar_client=MagicMock(),
+            queue="test-queue",
+            schema=MagicMock()
+        )
+        
+        test_request = {"test": "data"}
+        
+        # Call process
+        await sender.process(test_request)
+        
+        # Verify publisher send was called with processed request
+        mock_pub_instance.send.assert_called_once_with(None, {"processed": test_request})
+
+    @patch('trustgraph.gateway.dispatch.sender.Publisher')
+    def test_service_sender_attributes(self, mock_publisher):
+        """Test ServiceSender has correct attributes"""
+        mock_pub_instance = MagicMock()
+        mock_publisher.return_value = mock_pub_instance
+        
+        sender = ServiceSender(
+            pulsar_client=MagicMock(),
+            queue="test-queue",
+            schema=MagicMock()
+        )
+        
+        # Verify attributes are set correctly
+        assert sender.pub == mock_pub_instance

tests/unit/test_gateway/test_dispatch_serialize.py

@@ -0,0 +1,89 @@
+"""
+Tests for Gateway Dispatch Serialization
+"""
+
+import pytest
+from unittest.mock import MagicMock
+
+from trustgraph.gateway.dispatch.serialize import to_value, to_subgraph, serialize_value
+from trustgraph.schema import Value, Triple
+
+
+class TestDispatchSerialize:
+    """Test cases for dispatch serialization functions"""
+
+    def test_to_value_with_uri(self):
+        """Test to_value function with URI"""
+        input_data = {"v": "http://example.com/resource", "e": True}
+        
+        result = to_value(input_data)
+        
+        assert isinstance(result, Value)
+        assert result.value == "http://example.com/resource"
+        assert result.is_uri is True
+
+    def test_to_value_with_literal(self):
+        """Test to_value function with literal value"""
+        input_data = {"v": "literal string", "e": False}
+        
+        result = to_value(input_data)
+        
+        assert isinstance(result, Value)
+        assert result.value == "literal string"
+        assert result.is_uri is False
+
+    def test_to_subgraph_with_multiple_triples(self):
+        """Test to_subgraph function with multiple triples"""
+        input_data = [
+            {
+                "s": {"v": "subject1", "e": True},
+                "p": {"v": "predicate1", "e": True},
+                "o": {"v": "object1", "e": False}
+            },
+            {
+                "s": {"v": "subject2", "e": False},
+                "p": {"v": "predicate2", "e": True},
+                "o": {"v": "object2", "e": True}
+            }
+        ]
+        
+        result = to_subgraph(input_data)
+        
+        assert len(result) == 2
+        assert all(isinstance(triple, Triple) for triple in result)
+        
+        # Check first triple
+        assert result[0].s.value == "subject1"
+        assert result[0].s.is_uri is True
+        assert result[0].p.value == "predicate1"
+        assert result[0].p.is_uri is True
+        assert result[0].o.value == "object1"
+        assert result[0].o.is_uri is False
+        
+        # Check second triple
+        assert result[1].s.value == "subject2"
+        assert result[1].s.is_uri is False
+
+    def test_to_subgraph_with_empty_list(self):
+        """Test to_subgraph function with empty input"""
+        input_data = []
+        
+        result = to_subgraph(input_data)
+        
+        assert result == []
+
+    def test_serialize_value_with_uri(self):
+        """Test serialize_value function with URI value"""
+        value = Value(value="http://example.com/test", is_uri=True)
+        
+        result = serialize_value(value)
+        
+        assert result == {"v": "http://example.com/test", "e": True}
+
+    def test_serialize_value_with_literal(self):
+        """Test serialize_value function with literal value"""
+        value = Value(value="test literal", is_uri=False)
+        
+        result = serialize_value(value)
+        
+        assert result == {"v": "test literal", "e": False}

tests/unit/test_gateway/test_endpoint_constant.py

@@ -0,0 +1,55 @@
+"""
+Tests for Gateway Constant Endpoint
+"""
+
+import pytest
+from unittest.mock import MagicMock, AsyncMock
+from aiohttp import web
+
+from trustgraph.gateway.endpoint.constant_endpoint import ConstantEndpoint
+
+
+class TestConstantEndpoint:
+    """Test cases for ConstantEndpoint class"""
+
+    def test_constant_endpoint_initialization(self):
+        """Test ConstantEndpoint initialization"""
+        mock_auth = MagicMock()
+        mock_dispatcher = MagicMock()
+        
+        endpoint = ConstantEndpoint(
+            endpoint_path="/api/test",
+            auth=mock_auth,
+            dispatcher=mock_dispatcher
+        )
+        
+        assert endpoint.path == "/api/test"
+        assert endpoint.auth == mock_auth
+        assert endpoint.dispatcher == mock_dispatcher
+        assert endpoint.operation == "service"
+
+    @pytest.mark.asyncio
+    async def test_constant_endpoint_start_method(self):
+        """Test ConstantEndpoint start method (should be no-op)"""
+        mock_auth = MagicMock()
+        mock_dispatcher = MagicMock()
+        
+        endpoint = ConstantEndpoint("/api/test", mock_auth, mock_dispatcher)
+        
+        # start() should complete without error
+        await endpoint.start()
+
+    def test_add_routes_registers_post_handler(self):
+        """Test add_routes method registers POST route"""
+        mock_auth = MagicMock()
+        mock_dispatcher = MagicMock()
+        mock_app = MagicMock()
+        
+        endpoint = ConstantEndpoint("/api/test", mock_auth, mock_dispatcher)
+        endpoint.add_routes(mock_app)
+        
+        # Verify add_routes was called with POST route
+        mock_app.add_routes.assert_called_once()
+        # The call should include web.post with the path and handler
+        call_args = mock_app.add_routes.call_args[0][0]
+        assert len(call_args) == 1  # One route added

tests/unit/test_gateway/test_endpoint_manager.py

@@ -0,0 +1,89 @@
+"""
+Tests for Gateway Endpoint Manager
+"""
+
+import pytest
+from unittest.mock import MagicMock
+
+from trustgraph.gateway.endpoint.manager import EndpointManager
+
+
+class TestEndpointManager:
+    """Test cases for EndpointManager class"""
+
+    def test_endpoint_manager_initialization(self):
+        """Test EndpointManager initialization creates all endpoints"""
+        mock_dispatcher_manager = MagicMock()
+        mock_auth = MagicMock()
+        
+        # Mock dispatcher methods
+        mock_dispatcher_manager.dispatch_global_service.return_value = MagicMock()
+        mock_dispatcher_manager.dispatch_socket.return_value = MagicMock()
+        mock_dispatcher_manager.dispatch_flow_service.return_value = MagicMock()
+        mock_dispatcher_manager.dispatch_flow_import.return_value = MagicMock()
+        mock_dispatcher_manager.dispatch_flow_export.return_value = MagicMock()
+        mock_dispatcher_manager.dispatch_core_import.return_value = MagicMock()
+        mock_dispatcher_manager.dispatch_core_export.return_value = MagicMock()
+        
+        manager = EndpointManager(
+            dispatcher_manager=mock_dispatcher_manager,
+            auth=mock_auth,
+            prometheus_url="http://prometheus:9090",
+            timeout=300
+        )
+        
+        assert manager.dispatcher_manager == mock_dispatcher_manager
+        assert manager.timeout == 300
+        assert manager.services == {}
+        assert len(manager.endpoints) > 0  # Should have multiple endpoints
+
+    def test_endpoint_manager_with_default_timeout(self):
+        """Test EndpointManager with default timeout value"""
+        mock_dispatcher_manager = MagicMock()
+        mock_auth = MagicMock()
+        
+        # Mock dispatcher methods
+        mock_dispatcher_manager.dispatch_global_service.return_value = MagicMock()
+        mock_dispatcher_manager.dispatch_socket.return_value = MagicMock()
+        mock_dispatcher_manager.dispatch_flow_service.return_value = MagicMock()
+        mock_dispatcher_manager.dispatch_flow_import.return_value = MagicMock()
+        mock_dispatcher_manager.dispatch_flow_export.return_value = MagicMock()
+        mock_dispatcher_manager.dispatch_core_import.return_value = MagicMock()
+        mock_dispatcher_manager.dispatch_core_export.return_value = MagicMock()
+        
+        manager = EndpointManager(
+            dispatcher_manager=mock_dispatcher_manager,
+            auth=mock_auth,
+            prometheus_url="http://prometheus:9090"
+        )
+        
+        assert manager.timeout == 600  # Default value
+
+    def test_endpoint_manager_dispatcher_calls(self):
+        """Test EndpointManager calls all required dispatcher methods"""
+        mock_dispatcher_manager = MagicMock()
+        mock_auth = MagicMock()
+        
+        # Mock dispatcher methods that are actually called
+        mock_dispatcher_manager.dispatch_global_service.return_value = MagicMock()
+        mock_dispatcher_manager.dispatch_socket.return_value = MagicMock()
+        mock_dispatcher_manager.dispatch_flow_service.return_value = MagicMock()
+        mock_dispatcher_manager.dispatch_flow_import.return_value = MagicMock()
+        mock_dispatcher_manager.dispatch_flow_export.return_value = MagicMock()
+        mock_dispatcher_manager.dispatch_core_import.return_value = MagicMock()
+        mock_dispatcher_manager.dispatch_core_export.return_value = MagicMock()
+        
+        EndpointManager(
+            dispatcher_manager=mock_dispatcher_manager,
+            auth=mock_auth,
+            prometheus_url="http://test:9090"
+        )
+        
+        # Verify all dispatcher methods were called during initialization
+        mock_dispatcher_manager.dispatch_global_service.assert_called_once()
+        mock_dispatcher_manager.dispatch_socket.assert_called()  # Called twice
+        mock_dispatcher_manager.dispatch_flow_service.assert_called_once()
+        mock_dispatcher_manager.dispatch_flow_import.assert_called_once()
+        mock_dispatcher_manager.dispatch_flow_export.assert_called_once()
+        mock_dispatcher_manager.dispatch_core_import.assert_called_once()
+        mock_dispatcher_manager.dispatch_core_export.assert_called_once()

tests/unit/test_gateway/test_endpoint_metrics.py

@@ -0,0 +1,60 @@
+"""
+Tests for Gateway Metrics Endpoint
+"""
+
+import pytest
+from unittest.mock import MagicMock
+
+from trustgraph.gateway.endpoint.metrics import MetricsEndpoint
+
+
+class TestMetricsEndpoint:
+    """Test cases for MetricsEndpoint class"""
+
+    def test_metrics_endpoint_initialization(self):
+        """Test MetricsEndpoint initialization"""
+        mock_auth = MagicMock()
+        
+        endpoint = MetricsEndpoint(
+            prometheus_url="http://prometheus:9090",
+            endpoint_path="/metrics",
+            auth=mock_auth
+        )
+        
+        assert endpoint.prometheus_url == "http://prometheus:9090"
+        assert endpoint.path == "/metrics"
+        assert endpoint.auth == mock_auth
+        assert endpoint.operation == "service"
+
+    @pytest.mark.asyncio
+    async def test_metrics_endpoint_start_method(self):
+        """Test MetricsEndpoint start method (should be no-op)"""
+        mock_auth = MagicMock()
+        
+        endpoint = MetricsEndpoint(
+            prometheus_url="http://localhost:9090",
+            endpoint_path="/metrics",
+            auth=mock_auth
+        )
+        
+        # start() should complete without error
+        await endpoint.start()
+
+    def test_add_routes_registers_get_handler(self):
+        """Test add_routes method registers GET route with wildcard path"""
+        mock_auth = MagicMock()
+        mock_app = MagicMock()
+        
+        endpoint = MetricsEndpoint(
+            prometheus_url="http://prometheus:9090",
+            endpoint_path="/metrics",
+            auth=mock_auth
+        )
+        
+        endpoint.add_routes(mock_app)
+        
+        # Verify add_routes was called with GET route
+        mock_app.add_routes.assert_called_once()
+        # The call should include web.get with wildcard path pattern
+        call_args = mock_app.add_routes.call_args[0][0]
+        assert len(call_args) == 1  # One route added

tests/unit/test_gateway/test_endpoint_socket.py

@@ -0,0 +1,133 @@
+"""
+Tests for Gateway Socket Endpoint
+"""
+
+import pytest
+from unittest.mock import MagicMock, AsyncMock
+from aiohttp import WSMsgType
+
+from trustgraph.gateway.endpoint.socket import SocketEndpoint
+
+
+class TestSocketEndpoint:
+    """Test cases for SocketEndpoint class"""
+
+    def test_socket_endpoint_initialization(self):
+        """Test SocketEndpoint initialization"""
+        mock_auth = MagicMock()
+        mock_dispatcher = MagicMock()
+        
+        endpoint = SocketEndpoint(
+            endpoint_path="/api/socket",
+            auth=mock_auth,
+            dispatcher=mock_dispatcher
+        )
+        
+        assert endpoint.path == "/api/socket"
+        assert endpoint.auth == mock_auth
+        assert endpoint.dispatcher == mock_dispatcher
+        assert endpoint.operation == "socket"
+
+    @pytest.mark.asyncio
+    async def test_worker_method(self):
+        """Test SocketEndpoint worker method"""
+        mock_auth = MagicMock()
+        mock_dispatcher = AsyncMock()
+        
+        endpoint = SocketEndpoint("/api/socket", mock_auth, mock_dispatcher)
+        
+        mock_ws = MagicMock()
+        mock_running = MagicMock()
+        
+        # Call worker method
+        await endpoint.worker(mock_ws, mock_dispatcher, mock_running)
+        
+        # Verify dispatcher.run was called
+        mock_dispatcher.run.assert_called_once()
+
+    @pytest.mark.asyncio
+    async def test_listener_method_with_text_message(self):
+        """Test SocketEndpoint listener method with text message"""
+        mock_auth = MagicMock()
+        mock_dispatcher = AsyncMock()
+        
+        endpoint = SocketEndpoint("/api/socket", mock_auth, mock_dispatcher)
+        
+        # Mock websocket with text message
+        mock_msg = MagicMock()
+        mock_msg.type = WSMsgType.TEXT
+        
+        # Create async iterator for websocket
+        async def async_iter():
+            yield mock_msg
+        
+        mock_ws = AsyncMock()
+        mock_ws.__aiter__ = lambda self: async_iter()
+        mock_running = MagicMock()
+        
+        # Call listener method
+        await endpoint.listener(mock_ws, mock_dispatcher, mock_running)
+        
+        # Verify dispatcher.receive was called with the message
+        mock_dispatcher.receive.assert_called_once_with(mock_msg)
+        # Verify cleanup methods were called
+        mock_running.stop.assert_called_once()
+        mock_ws.close.assert_called_once()
+
+    @pytest.mark.asyncio
+    async def test_listener_method_with_binary_message(self):
+        """Test SocketEndpoint listener method with binary message"""
+        mock_auth = MagicMock()
+        mock_dispatcher = AsyncMock()
+        
+        endpoint = SocketEndpoint("/api/socket", mock_auth, mock_dispatcher)
+        
+        # Mock websocket with binary message
+        mock_msg = MagicMock()
+        mock_msg.type = WSMsgType.BINARY
+        
+        # Create async iterator for websocket
+        async def async_iter():
+            yield mock_msg
+        
+        mock_ws = AsyncMock()
+        mock_ws.__aiter__ = lambda self: async_iter()
+        mock_running = MagicMock()
+        
+        # Call listener method
+        await endpoint.listener(mock_ws, mock_dispatcher, mock_running)
+        
+        # Verify dispatcher.receive was called with the message
+        mock_dispatcher.receive.assert_called_once_with(mock_msg)
+        # Verify cleanup methods were called
+        mock_running.stop.assert_called_once()
+        mock_ws.close.assert_called_once()
+
+    @pytest.mark.asyncio
+    async def test_listener_method_with_close_message(self):
+        """Test SocketEndpoint listener method with close message"""
+        mock_auth = MagicMock()
+        mock_dispatcher = AsyncMock()
+        
+        endpoint = SocketEndpoint("/api/socket", mock_auth, mock_dispatcher)
+        
+        # Mock websocket with close message
+        mock_msg = MagicMock()
+        mock_msg.type = WSMsgType.CLOSE
+        
+        # Create async iterator for websocket
+        async def async_iter():
+            yield mock_msg
+        
+        mock_ws = AsyncMock()
+        mock_ws.__aiter__ = lambda self: async_iter()
+        mock_running = MagicMock()
+        
+        # Call listener method
+        await endpoint.listener(mock_ws, mock_dispatcher, mock_running)
+        
+        # Verify dispatcher.receive was NOT called for close message
+        mock_dispatcher.receive.assert_not_called()
+        # Verify cleanup methods were called after break
+        mock_running.stop.assert_called_once()
+        mock_ws.close.assert_called_once()

tests/unit/test_gateway/test_endpoint_stream.py

@@ -0,0 +1,124 @@
+"""
+Tests for Gateway Stream Endpoint
+"""
+
+import pytest
+from unittest.mock import MagicMock
+
+from trustgraph.gateway.endpoint.stream_endpoint import StreamEndpoint
+
+
+class TestStreamEndpoint:
+    """Test cases for StreamEndpoint class"""
+
+    def test_stream_endpoint_initialization_with_post(self):
+        """Test StreamEndpoint initialization with POST method"""
+        mock_auth = MagicMock()
+        mock_dispatcher = MagicMock()
+        
+        endpoint = StreamEndpoint(
+            endpoint_path="/api/stream",
+            auth=mock_auth,
+            dispatcher=mock_dispatcher,
+            method="POST"
+        )
+        
+        assert endpoint.path == "/api/stream"
+        assert endpoint.auth == mock_auth
+        assert endpoint.dispatcher == mock_dispatcher
+        assert endpoint.operation == "service"
+        assert endpoint.method == "POST"
+
+    def test_stream_endpoint_initialization_with_get(self):
+        """Test StreamEndpoint initialization with GET method"""
+        mock_auth = MagicMock()
+        mock_dispatcher = MagicMock()
+        
+        endpoint = StreamEndpoint(
+            endpoint_path="/api/stream",
+            auth=mock_auth,
+            dispatcher=mock_dispatcher,
+            method="GET"
+        )
+        
+        assert endpoint.method == "GET"
+
+    def test_stream_endpoint_initialization_default_method(self):
+        """Test StreamEndpoint initialization with default POST method"""
+        mock_auth = MagicMock()
+        mock_dispatcher = MagicMock()
+        
+        endpoint = StreamEndpoint(
+            endpoint_path="/api/stream",
+            auth=mock_auth,
+            dispatcher=mock_dispatcher
+        )
+        
+        assert endpoint.method == "POST"  # Default value
+
+    @pytest.mark.asyncio
+    async def test_stream_endpoint_start_method(self):
+        """Test StreamEndpoint start method (should be no-op)"""
+        mock_auth = MagicMock()
+        mock_dispatcher = MagicMock()
+        
+        endpoint = StreamEndpoint("/api/stream", mock_auth, mock_dispatcher)
+        
+        # start() should complete without error
+        await endpoint.start()
+
+    def test_add_routes_with_post_method(self):
+        """Test add_routes method with POST method"""
+        mock_auth = MagicMock()
+        mock_dispatcher = MagicMock()
+        mock_app = MagicMock()
+        
+        endpoint = StreamEndpoint(
+            endpoint_path="/api/stream",
+            auth=mock_auth,
+            dispatcher=mock_dispatcher,
+            method="POST"
+        )
+        
+        endpoint.add_routes(mock_app)
+        
+        # Verify add_routes was called with POST route
+        mock_app.add_routes.assert_called_once()
+        call_args = mock_app.add_routes.call_args[0][0]
+        assert len(call_args) == 1  # One route added
+
+    def test_add_routes_with_get_method(self):
+        """Test add_routes method with GET method"""
+        mock_auth = MagicMock()
+        mock_dispatcher = MagicMock()
+        mock_app = MagicMock()
+        
+        endpoint = StreamEndpoint(
+            endpoint_path="/api/stream",
+            auth=mock_auth,
+            dispatcher=mock_dispatcher,
+            method="GET"
+        )
+        
+        endpoint.add_routes(mock_app)
+        
+        # Verify add_routes was called with GET route
+        mock_app.add_routes.assert_called_once()
+        call_args = mock_app.add_routes.call_args[0][0]
+        assert len(call_args) == 1  # One route added
+
+    def test_add_routes_with_invalid_method_raises_error(self):
+        """Test add_routes method with invalid method raises RuntimeError"""
+        mock_auth = MagicMock()
+        mock_dispatcher = MagicMock()
+        mock_app = MagicMock()
+        
+        endpoint = StreamEndpoint(
+            endpoint_path="/api/stream",
+            auth=mock_auth,
+            dispatcher=mock_dispatcher,
+            method="INVALID"
+        )
+        
+        with pytest.raises(RuntimeError, match="Bad method"):
+            endpoint.add_routes(mock_app)

tests/unit/test_gateway/test_endpoint_variable.py

@@ -0,0 +1,53 @@
+"""
+Tests for Gateway Variable Endpoint
+"""
+
+import pytest
+from unittest.mock import MagicMock
+
+from trustgraph.gateway.endpoint.variable_endpoint import VariableEndpoint
+
+
+class TestVariableEndpoint:
+    """Test cases for VariableEndpoint class"""
+
+    def test_variable_endpoint_initialization(self):
+        """Test VariableEndpoint initialization"""
+        mock_auth = MagicMock()
+        mock_dispatcher = MagicMock()
+        
+        endpoint = VariableEndpoint(
+            endpoint_path="/api/variable",
+            auth=mock_auth,
+            dispatcher=mock_dispatcher
+        )
+        
+        assert endpoint.path == "/api/variable"
+        assert endpoint.auth == mock_auth
+        assert endpoint.dispatcher == mock_dispatcher
+        assert endpoint.operation == "service"
+
+    @pytest.mark.asyncio
+    async def test_variable_endpoint_start_method(self):
+        """Test VariableEndpoint start method (should be no-op)"""
+        mock_auth = MagicMock()
+        mock_dispatcher = MagicMock()
+        
+        endpoint = VariableEndpoint("/api/var", mock_auth, mock_dispatcher)
+        
+        # start() should complete without error
+        await endpoint.start()
+
+    def test_add_routes_registers_post_handler(self):
+        """Test add_routes method registers POST route"""
+        mock_auth = MagicMock()
+        mock_dispatcher = MagicMock()
+        mock_app = MagicMock()
+        
+        endpoint = VariableEndpoint("/api/variable", mock_auth, mock_dispatcher)
+        endpoint.add_routes(mock_app)
+        
+        # Verify add_routes was called with POST route
+        mock_app.add_routes.assert_called_once()
+        call_args = mock_app.add_routes.call_args[0][0]
+        assert len(call_args) == 1  # One route added