aixtools 0.6.5__tar.gz → 0.9.3__tar.gz

{aixtools-0.6.5 → aixtools-0.9.3}/PKG-INFO

@@ -1,10 +1,10 @@
 Metadata-Version: 2.4
 Name: aixtools
-Version: 0.6.5
+Version: 0.9.3
 Summary: Tools for AI exploration and debugging
 Requires-Python: >=3.11.2
 Description-Content-Type: text/markdown
-Requires-Dist: a2a-sdk>=0.3.1
+Requires-Dist: a2a-sdk[postgresql]>=0.3.3
 Requires-Dist: alembic>=1.17.1
 Requires-Dist: cachebox>=5.0.1
 Requires-Dist: chainlit>=2.5.5
@@ -13,12 +13,16 @@ Requires-Dist: fasta2a>=0.5.0
 Requires-Dist: fastmcp>=2.13.0
 Requires-Dist: hvac>=2.3.0
 Requires-Dist: ipykernel>=6.29.5
+Requires-Dist: jupyterlab>=4.4.3
 Requires-Dist: langchain-chroma>=0.2.3
 Requires-Dist: langchain-ollama>=0.3.2
 Requires-Dist: langchain-openai>=0.3.14
 Requires-Dist: markitdown[docx,pdf,pptx,xls,xlsx]>=0.1.3
 Requires-Dist: mcp>=1.20.0
+Requires-Dist: msal>=1.29.0
+Requires-Dist: msal-extensions>=1.1.0
 Requires-Dist: mypy>=1.18.2
+Requires-Dist: nest_asyncio>=1.6.0
 Requires-Dist: pandas>=2.2.3
 Requires-Dist: psycopg2-binary>=2.9.11
 Requires-Dist: pydantic-evals>=0.4.10
@@ -30,7 +34,12 @@ Requires-Dist: ruff>=0.11.6
 Requires-Dist: sqlalchemy>=2.0.44
 Requires-Dist: streamlit>=1.44.1
 Requires-Dist: tiktoken>=0.9.0
+Requires-Dist: openpyxl>=3.1.5
+Requires-Dist: xlrd>=2.0.2
+Requires-Dist: odfpy>=1.4.1
 Requires-Dist: watchdog>=6.0.0
+Requires-Dist: python-frontmatter>=1.1.0
+Requires-Dist: podkit>=0.4.0
 Provides-Extra: test
 Requires-Dist: pyyaml; extra == "test"
 Provides-Extra: feature
@@ -42,50 +51,48 @@ AIXtools is a comprehensive Python library for AI agent development, debugging,
 
 ## Capabilities
 
-Agents
-- Agent Development & Management - `aixtools/agents/`
-- Agent Batch Processing - `aixtools/agents/agent_batch.py`
-- Agent Prompting System - `aixtools/agents/prompt.py`
-
-A2A
-- Agent-to-Agent Communication (A2A) - `aixtools/a2a/`
-- Google SDK Integration for A2A - `aixtools/a2a/google_sdk/`
-- PydanticAI Adapter for Google SDK - `aixtools/a2a/google_sdk/pydantic_ai_adapter/`
-
-Logging & Debugging
-- Log Viewing Web Application - `log_view`
-- Object Logging System - `aixtools/logging/`
-- Model Patch Logging - `aixtools/logging/model_patch_logging.py`
-- Log Filtering System - `aixtools/logfilters/`
-- FastMCP Logging - `aixtools/mcp/fast_mcp_log.py`
-- MCP (Model Context Protocol) Support - `aixtools/logging/mcp_log_models.py`, `aixtools/logging/mcp_logger.py`
-
-Testing Tools & Evals
-- Evaluations - `aixtools/evals/` - Entry point: `evals`
-- Testing Utilities - `aixtools/testing/`
-- Mock Tool System - `aixtools/testing/mock_tool.py`
-- Model Patch Caching - `aixtools/testing/model_patch_cache.py`
-- Tool Doctor System - `aixtools/tools/doctor/`
-- Tool Recommendation Engine - `aixtools/tools/doctor/tool_recommendation.py`
-- FaultyMCP - `aixtools/mcp/faulty_mcp.py`
-- Agent Mock - `aixtools/testing/agent_mock.py`
-
-Databases
-- Database Integration - `aixtools/db/`
-- Vector Database Support - `aixtools/db/vector_db.py`
-
-Chainlit & HTTP Server
-- Chainlit Integration - `aixtools/app.py`, `aixtools/chainlit.md`
-- Chainlit Utilities - `aixtools/utils/chainlit/`
-- HTTP Server Framework - `aixtools/server/`
-- App Mounting System - `aixtools/server/app_mounter.py`
-
-Programming utils
-- Persisted Dictionary - `aixtools/utils/persisted_dict.py`
-- Enum with Description - `aixtools/utils/enum_with_description.py`
-- Context Management - `aixtools/context.py`
-- Configuration Management - `aixtools/utils/config.py`, `aixtools/utils/config_util.py`
-- File Utilities - `aixtools/utils/files.py`
+- **[Installation](#installation)**
+- **[Environment Configuration](#environment-configuration)**
+- **[Agents](#agents)** - Core agent functionality
+  - Basic Agent Usage
+  - Agent Development & Management
+  - Agent Batch Processing
+  - Node Debugging and Visualization
+- **[Context Engineering](#context-engineering)** - Transform files into agent-readable content
+  - File Type Processors
+  - Configuration
+  - Processing Examples
+- **[Agent-to-Agent Communication](#a2a-agent-to-agent-communication)** - Inter-agent communication framework
+  - Core Features
+  - Google SDK Integration
+  - Remote Agent Connections
+- **[Testing & Tools](#testing--tools)** - Comprehensive testing utilities
+  - Running Tests
+  - Testing Utilities
+  - Mock Tool System
+  - Model Patch Caching
+  - Agent Mock
+  - FaultyMCP Testing Server
+  - MCP Tool Doctor
+  - Tool Doctor
+  - Evaluations
+- **[Logging & Debugging](#logging--debugging)** - Advanced logging and debugging
+  - Basic Logging
+  - Log Viewing Application
+  - Object Logging
+  - MCP Logging
+- **[Databases](#databases)** - Traditional and vector database support
+- **[Chainlit & HTTP Server](#chainlit--http-server)** - Web interfaces and server framework
+  - Chainlit Integration
+  - HTTP Server Framework
+- **[Programming Utilities](#programming-utilities)** - Essential utilities
+  - Persisted Dictionary
+  - Enum with Description
+  - Context Management
+  - Configuration Management
+  - File Utilities
+  - Chainlit Utilities
+  - Truncation Utilities
 
 ## Installation
 
@@ -101,11 +108,12 @@ uv add --upgrade aixtools
 
 ## Environment Configuration
 
-AIXtools requires environment variables for model providers. 
+AIXtools requires environment variables for model providers.
 
-**IMPORTANT:** Create a `.env` file based on [`.env_template`](./.env_template):
+**IMPORTANT:** Create a `.env` file based on `.env_template`:
 
 Here is an example configuration:
+
 ```bash
 # Model family (azure, openai, or ollama)
 MODEL_FAMILY=azure
@@ -155,7 +163,7 @@ result, nodes = await run_agent(agent, "Tell me about AI")
 
 ### Node Debugging and Visualization
 
-The [`print_nodes`](aixtools/agents/print_nodes.py) module provides a clean, indented output for easy reading of the node from agent execution.
+The `print_nodes` module provides a clean, indented output for easy reading of the node from agent execution.
 
 ```python
 from aixtools.agents.print_nodes import print_nodes, print_node
@@ -168,11 +176,11 @@ print_nodes(nodes)
 ```
 
 **Features:**
-- **Node Type Detection**: Automatically handles different node types (`UserPromptNode`, `CallToolsNode`, `ModelRequestNode`, `End`)
-- **Formatted Output**: Provides clean, indented output for easy reading
-- **Tool Call Visualization**: Shows tool names and arguments for tool calls
-- **Text Content Display**: Formats text parts with proper indentation
-- **Model Request Summary**: Shows character count for model requests to avoid verbose output
+- Node Type Detection: Automatically handles different node types (`UserPromptNode`, `CallToolsNode`, `ModelRequestNode`, `End`)
+- Formatted Output: Provides clean, indented output for easy reading
+- Tool Call Visualization: Shows tool names and arguments for tool calls
+- Text Content Display: Formats text parts with proper indentation
+- Model Request Summary: Shows character count for model requests to avoid verbose output
 
 **Node Types Supported:**
 - `UserPromptNode` - Displays user prompts with indentation
@@ -198,14 +206,190 @@ async for result in agent_batch(query_parameters):
     print(result)
 ```
 
+## Context Engineering
+
+Transform file formats into agent-readable content with enforced size limits to prevent context overflow. The main entry point is the `read_file()` function in `aixtools/agents/context/reader.py`, which provides automatic file type detection and delegates to specialized processors for each file type.
+
+### Basic Usage
+
+The `read_file()` function in `reader.py` is the main interface for processing files. It automatically detects file types and applies appropriate truncation strategies.
+
+```python
+from aixtools.agents.context.reader import read_file
+from pathlib import Path
+
+# Read a file with automatic type detection and truncation
+result = read_file(Path("data.csv"))
+
+if result.success:
+    print(f"File type: {result.file_type}")
+    print(f"Content length: {len(result.content)}")
+    print(f"Truncation info: {result.truncation_info}")
+    print(result.content)
+
+# Optionally specify custom tokenizer and limits
+result = read_file(
+    Path("large_file.json"),
+    max_tokens_per_file=10000,
+    max_total_output=100000
+)
+```
+
+### Architecture
+
+The context engineering system is organized with `reader.py` as the main interface:
+- `reader.py` - Main `read_file()` function with file type detection and processing coordination
+- `config.py` - Configurable size limits and thresholds
+- `processors/` - Specialized processors for each file type (text, code, JSON, CSV, PDF, etc.)
+- `data_models.py` - Data classes for results and metadata
+
+### Supported File Types
+
+- Text files (`.txt`, `.log`, `.md`)
+- Code files (Python, JavaScript, etc.)
+- Structured data (`JSON`, `YAML`, `XML`)
+- Tabular data (`CSV`, `TSV`)
+- Documents (`PDF`, `DOCX`)
+- Spreadsheets (`.xlsx`, `.xls`, `.ods`)
+- Images (`PNG`, `JPEG`, `GIF`, `WEBP`)
+- Audio files
+
+### Key Features
+
+- Automatic file type detection based on MIME types and extensions
+- Token-based truncation with configurable limits per file
+- Intelligent content sampling (head + tail rows for tabular data)
+- Structure-aware truncation for `JSON`, `YAML`, and `XML`
+- Markdown conversion for documents using `markitdown`
+- Binary content support for images with metadata extraction
+- Comprehensive error handling with partial results when possible
+
+### Configuration
+
+All limits are configurable via environment variables:
+
+```bash
+# Output limits
+MAX_TOKENS_PER_FILE=5000
+MAX_TOTAL_OUTPUT=50000
+
+# Text truncation
+MAX_LINES=200
+MAX_LINE_LENGTH=1000
+
+# Tabular truncation
+MAX_COLUMNS=50
+DEFAULT_ROWS_HEAD=20
+DEFAULT_ROWS_MIDDLE=10
+DEFAULT_ROWS_TAIL=10
+MAX_CELL_LENGTH=500
+
+# Images
+MAX_IMAGE_ATTACHMENT_SIZE=2097152  # 2MB
+```
+
+### Processing Examples
+
+The recommended approach is to use the `read_file()` function which automatically handles file type detection and processing. However, you can also use individual processors directly for specific file types.
+
+#### Using read_file() (Recommended)
+
+```python
+from aixtools.agents.context.reader import read_file
+from pathlib import Path
+
+# Process any file type automatically
+result = read_file(Path("data.csv"))
+if result.success:
+    print(result.content)
+
+# Works with all supported types
+pdf_result = read_file(Path("report.pdf"))
+excel_result = read_file(Path("workbook.xlsx"))
+json_result = read_file(Path("config.json"))
+```
+
+#### Processing Tabular Data Directly
+
+```python
+from aixtools.agents.context.processors.tabular import process_tabular
+from pathlib import Path
+
+# Process specific row range from large CSV
+result = process_tabular(
+    file_path=Path("large_data.csv"),
+    start_row=100,
+    end_row=200,
+    max_columns=20,
+    max_cell_length=500
+)
+
+print(f"Rows shown: {result.truncation_info.rows_shown}")
+print(f"Columns shown: {result.truncation_info.columns_shown}")
+```
+
+#### Processing Spreadsheets Directly
+
+```python
+from aixtools.agents.context.processors.spreadsheet import process_spreadsheet
+from pathlib import Path
+
+# Process Excel file with multiple sheets
+result = process_spreadsheet(
+    file_path=Path("workbook.xlsx"),
+    max_sheets=3,
+    max_rows_per_sheet_head=20,
+    max_rows_per_sheet_tail=10
+)
+
+# Content includes all processed sheets with truncation info
+print(result.content)
+```
+
+#### Processing Documents Directly
+
+```python
+from aixtools.agents.context.processors.document import process_document
+from pathlib import Path
+
+# Convert PDF to markdown and truncate
+result = process_document(
+    file_path=Path("report.pdf"),
+    max_lines=200,
+    max_line_length=1000
+)
+
+if result.was_extracted:
+    print("Document successfully converted to markdown")
+    print(result.content)
+```
+
+### Output Format
+
+All processors return consistent output with metadata:
+
+```
+File: data.csv
+Columns: 8 (of 20000 total)
+Rows: 20 (of 1000000 total)
+
+col1,col2,...,col8
+value1,value2,...
+...
+
+Truncated: columns: 8 of 20000, rows: 20 of 1000000, 45 cells
+```
+
+The context engineering system ensures agents receive properly formatted, size-limited content that fits within token budgets while preserving the most relevant information from each file type.
+
 ## A2A (Agent-to-Agent Communication)
 
-The A2A module provides a comprehensive framework for enabling sophisticated communication between AI agents across different environments and platforms. It includes Google SDK integration, PydanticAI adapters, and FastA2A application conversion capabilities.
+The `A2A` module provides a comprehensive framework for enabling sophisticated communication between AI agents across different environments and platforms. It includes Google SDK integration, `PydanticAI` adapters, and `FastA2A` application conversion capabilities.
 
 ### Core Features
 
 **Agent Application Conversion**
-- Convert PydanticAI agents into FastA2A applications (deprecated)
+- Convert `PydanticAI` agents into `FastA2A` applications (deprecated)
 - Support for session metadata extraction and context management
 - Custom worker classes with enhanced data part support
 - Automatic handling of user and session identification
@@ -219,12 +403,12 @@ The A2A module provides a comprehensive framework for enabling sophisticated com
 **Google SDK Integration**
 - Native integration with Google's A2A SDK
 - Card-based agent representation and discovery
-- PydanticAI adapter for seamless Google SDK compatibility
+- `PydanticAI` adapter for seamless Google SDK compatibility
 - Storage and execution management for agent interactions
 
-### Agent-to-Agent Communication (A2A)
+### Basic Usage
 
-Enable sophisticated agent interactions with Google SDK integration and PydanticAI adapters.
+Enable sophisticated agent interactions with Google SDK integration and `PydanticAI` adapters.
 
 ```python
 from aixtools.a2a.google_sdk.remote_agent_connection import RemoteAgentConnection
@@ -344,7 +528,7 @@ from aixtools.agents.agent import get_agent, run_agent
 async def main():
     # Create an agent
     agent = get_agent(system_prompt="You are a helpful assistant.")
-    
+
     # Run agent - logging is automatic via ObjectLogger
     result, nodes = await run_agent(
         agent,
@@ -352,19 +536,19 @@ async def main():
         debug=True,  # Enable debug logging
         log_model_requests=True  # Log model requests/responses
     )
-    
+
     print(f"Result: {result}")
     print(f"Logged {len(nodes)} nodes")
 ```
 
 ### Log Viewing Application
 
-Interactive Streamlit application for analyzing logged objects and debugging agent behavior.
+Interactive `Streamlit` application for analyzing logged objects and debugging agent behavior.
 
 **Features:**
 - Log file selection and filtering
 - Node visualization with expand/collapse
-- Export capabilities to JSON
+- Export capabilities to `JSON`
 - Regex pattern matching
 - Real-time log monitoring
 
@@ -389,15 +573,15 @@ with ObjectLogger() as logger:
     logger.log(agent_response)
 ```
 
-### MCP logging
+### MCP Logging
 
-AIXtools provides  MCP support for both client and server implementations with easier logging for debugging pourposes.
+AIXtools provides MCP support for both client and server implementations with easier logging for debugging purposes.
 
-**Example:** 
+**Example:**
 
 Let's assume we have an MCP server that runs an agent tool.
 
-Note that the `ctx: Context` parameter is passed to `run_agent`, this will enable logging to the MCP client.
+Note that the `ctx: Context` parameter is passed to `run_agent()`, this will enable logging to the MCP client.
 
 ```python
 @mcp.tool
@@ -409,7 +593,7 @@ async def my_tool_with_agent(query: str, ctx: Context) -> str:
         return str(ret)
 ```
 
-On the client side, you can create an agent connected to the MCP server, the "nodes" from the MCP server will show on the STDOUT so you can see what's going on the MCP server's agent loop
+On the client side, you can create an agent connected to the MCP server, the nodes from the MCP server will show on the `STDOUT` so you can see what's going on the MCP server's agent loop.
 
 ```python
 mcp = get_mcp_client("http://localhost:8000")   # Get an MCP client with a default log handler that prints to STDOUT
@@ -430,6 +614,84 @@ from aixtools.mcp.fast_mcp_log import FastMcpLog
 mcp = FastMcpLog("Demo")
 ```
 
+## Testing & Tools
+
+AIXtools provides comprehensive testing utilities and diagnostic tools for AI agent development and debugging.
+
+### Running Tests
+
+Execute the test suite using the provided scripts:
+
+```bash
+# Run all tests
+./scripts/test.sh
+
+# Run unit tests only
+./scripts/test_unit.sh
+
+# Run integration tests only
+./scripts/test_integration.sh
+```
+
+### Testing Utilities
+
+The testing module provides mock tools, model patching, and test utilities for comprehensive agent testing.
+
+```python
+from aixtools.testing.mock_tool import MockTool
+from aixtools.testing.model_patch_cache import ModelPatchCache
+from aixtools.testing.aix_test_model import AixTestModel
+
+# Create mock tools for testing
+mock_tool = MockTool(name="test_tool", response="mock response")
+
+# Use model patch caching for consistent test results
+cache = ModelPatchCache()
+cached_response = cache.get_cached_response("test_prompt")
+
+# Test model for controlled testing scenarios
+test_model = AixTestModel()
+```
+
+### Mock Tool System
+
+Create and manage mock tools for testing agent behavior without external dependencies.
+
+```python
+from aixtools.testing.mock_tool import MockTool
+
+# Create a mock tool with predefined responses
+mock_calculator = MockTool(
+    name="calculator",
+    description="Performs mathematical calculations",
+    response_map={
+        "2+2": "4",
+        "10*5": "50"
+    }
+)
+
+# Use in agent testing
+agent = get_agent(tools=[mock_calculator])
+result = await run_agent(agent, "What is 2+2?")
+```
+
+### Model Patch Caching
+
+Cache model responses for consistent testing and development workflows.
+
+```python
+from aixtools.testing.model_patch_cache import ModelPatchCache
+
+# Initialize cache
+cache = ModelPatchCache(cache_dir="./test_cache")
+
+# Cache responses for specific prompts
+cache.cache_response("test prompt", "cached response")
+
+# Retrieve cached responses
+response = cache.get_cached_response("test prompt")
+```
+
 ### Model Patching System
 
 Dynamic model behavior modification for testing and debugging.
@@ -443,16 +705,39 @@ with ModelPatch() as patch:
     result = await agent.run("test prompt")
 ```
 
-### FaultyMCP
+### Agent Mock
+
+Replay previously recorded agent runs without executing the actual agent. Useful for testing, debugging, and creating reproducible test cases.
+
+```python
+from aixtools.testing.agent_mock import AgentMock
+from aixtools.agents.agent import get_agent, run_agent
+
+# Run an agent and capture its execution
+agent = get_agent(system_prompt="You are a helpful assistant.")
+result, nodes = await run_agent(agent, "Explain quantum computing")
+
+# Create a mock agent from the recorded nodes
+agent_mock = AgentMock(nodes=nodes, result_output=result)
+
+# Save the mock for later use
+agent_mock.save(Path("test_data/quantum_mock.pkl"))
+
+# Load and replay the mock agent
+loaded_mock = AgentMock.load(Path("test_data/quantum_mock.pkl"))
+result, nodes = await run_agent(loaded_mock, "any prompt")  # Returns recorded nodes
+```
+
+### FaultyMCP Testing Server
 
-A specialized MCP server designed for testing error handling and resilience in MCP client implementations. FaultyMCP simulates various failure scenarios including network errors, server crashes, and random exceptions.
+A specialized MCP server designed for testing error handling and resilience in MCP client implementations. `FaultyMCP` simulates various failure scenarios including network errors, server crashes, and random exceptions.
 
 **Features:**
 - Configurable error probabilities for different request types
-- HTTP 404 error injection for POST/DELETE requests
-- Server crash simulation on GET requests
+- HTTP 404 error injection for `POST`/`DELETE` requests
+- Server crash simulation on `GET` requests
 - Random exception throwing in tool operations
-- MCP-specific error simulation (ValidationError, ResourceError, etc.)
+- MCP-specific error simulation (`ValidationError`, `ResourceError`, etc.)
 - Safe mode for controlled testing
 
 ```python
@@ -468,6 +753,7 @@ run_server_on_port()
 ```
 
 **Command Line Usage:**
+
 ```bash
 # Run with default error probabilities
 python -m aixtools.mcp.faulty_mcp
@@ -483,17 +769,72 @@ python -m aixtools.mcp.faulty_mcp \
     --prob-in-list-tools-throw 0.3
 ```
 
-By default, the "FaultyMCP" includes several tools you can use in your tests:
-- `add(a, b)` - Basic addition (reliable)
-- `multiply(a, b)` - Basic multiplication (reliable)
+**Available Test Tools:**
+- `add(a, b)` - Reliable addition operation
+- `multiply(a, b)` - Reliable multiplication operation
 - `always_error()` - Always throws an exception
 - `random_throw_exception(a, b, prob)` - Randomly throws exceptions
 - `freeze_server(seconds)` - Simulates server freeze
 - `throw_404_exception()` - Throws HTTP 404 error
 
-### Evals
+### MCP Tool Doctor
 
-Run comprehensive Agent/LLM evaluations using the built-in evaluation discovery based on Pydantic-AI framework with AIXtools enhancements.
+Analyze tools from MCP (Model Context Protocol) servers and receive AI-powered recommendations for improvement.
+
+```python
+from aixtools.tools.doctor.mcp_tool_doctor import tool_doctor_mcp
+from pydantic_ai.mcp import MCPServerStreamableHTTP, MCPServerStdio
+
+# Analyze HTTP MCP server
+recommendations = await tool_doctor_mcp(mcp_url='http://127.0.0.1:8000/mcp')
+for rec in recommendations:
+    print(rec)
+
+# Analyze STDIO MCP server
+server = MCPServerStdio(command='fastmcp', args=['run', 'my_server.py'])
+recommendations = await tool_doctor_mcp(mcp_server=server, verbose=True)
+```
+
+**Command Line Usage:**
+
+```bash
+# Analyze HTTP MCP server (default)
+tool_doctor_mcp
+
+# Analyze specific HTTP MCP server
+tool_doctor_mcp --mcp-url http://localhost:9000/mcp --verbose
+
+# Analyze STDIO MCP server
+tool_doctor_mcp --stdio-command fastmcp --stdio-args run my_server.py --debug
+```
+
+**Available options:**
+- `--mcp-url URL` - URL of HTTP MCP server (default: `http://127.0.0.1:8000/mcp`)
+- `--stdio-command CMD` - Command to run STDIO MCP server
+- `--stdio-args ARGS` - Arguments for STDIO MCP server command
+- `--verbose` - Enable verbose output
+- `--debug` - Enable debug output
+
+### Tool Doctor
+
+Analyze tool usage patterns from agent logs and get optimization recommendations.
+
+```python
+from aixtools.tools.doctor.tool_doctor import ToolDoctor
+from aixtools.tools.doctor.tool_recommendation import ToolRecommendation
+
+# Analyze tool usage patterns
+doctor = ToolDoctor()
+analysis = doctor.analyze_tools(agent_logs)
+
+# Get tool recommendations
+recommendation = ToolRecommendation()
+suggestions = recommendation.recommend_tools(agent_context)
+```
+
+### Evaluations
+
+Run comprehensive Agent/LLM evaluations using the built-in evaluation discovery based on `Pydantic-AI` framework with AIXtools enhancements.
 
 ```bash
 # Run all evaluations
@@ -513,16 +854,16 @@ python -m aixtools.evals --min-assertions 0.8
 ```
 
 **Command Line Options:**
-- `--evals-dir` - Directory containing eval_*.py files (default: evals)
+- `--evals-dir` - Directory containing `eval_*.py` files (default: `evals`)
 - `--filter` - Filter to run only matching evaluations
-- `--include-input` - Include input in report output (default: True)
-- `--include-output` - Include output in report output (default: True)
+- `--include-input` - Include input in report output (default: `True`)
+- `--include-output` - Include output in report output (default: `True`)
 - `--include-evaluator-failures` - Include evaluator failures in report
 - `--include-reasons` - Include reasons in report output
-- `--min-assertions` - Minimum assertions average required for success (default: 1.0)
+- `--min-assertions` - Minimum assertions average required for success (default: `1.0`)
 - `--verbose` - Print detailed information about discovery and processing
 
-The evaluation system discovers and runs all Dataset objects from eval_*.py files in the specified directory, similar to test runners but specifically designed for LLM evaluations using pydantic_evals.
+The evaluation system discovers and runs all `Dataset` objects from `eval_*.py` files in the specified directory, similar to test runners but specifically designed for LLM evaluations using `pydantic_evals`.
 
 **Discovery Mechanism**
 
@@ -536,6 +877,7 @@ The evaluation framework uses an automatic discovery system:
 5. **Filtering**: Supports filtering by module name, file name, dataset name, or fully qualified name
 
 **Example Evaluation File Structure:**
+
 ```python
 # eval_math_operations.py
 from pydantic_evals import Dataset, Case
@@ -564,7 +906,7 @@ def evaluator_check_output(ctx: EvaluatorContext) -> bool:
 ```
 
 The discovery system will:
-- Find `eval_math_operations.py` in the evals directory
+- Find `eval_math_operations.py` in the `evals` directory
 - Discover `dataset_addition` as an evaluation dataset
 - Use `evaluate_math_agent` as the target function for evaluation
 - Run each case through the target function and evaluate results
@@ -574,237 +916,67 @@ The discovery system will:
 The evaluation system uses name-based discovery for all components:
 
 **Target Functions** (exactly one required per eval file):
-- **Purpose**: The main function being evaluated - processes inputs and returns outputs
-- **Naming**: Functions named `target_*` (e.g., `target_my_function`)
-- **Signature**: `def target_name(inputs: InputType) -> OutputType` or `async def target_name(inputs: InputType) -> OutputType`
-- **Example**: `async def target_math_agent(input_text: str) -> str`
+- Purpose: The main function being evaluated - processes inputs and returns outputs
+- Naming: Functions named `target_*` (e.g., `target_my_function`)
+- Signature: `def target_name(inputs: InputType) -> OutputType` or `async def target_name(inputs: InputType) -> OutputType`
+- Example: `async def target_math_agent(input_text: str) -> str`
 
 **Scoring Functions** (optional):
-- **Purpose**: Determine if evaluation results meet success criteria
-- **Naming**: Functions named `scorer_*` (e.g., `scorer_custom`)
-- **Signature**: `def scorer_name(report: EvaluationReport, dataset: AixDataset, min_score: float = 1.0, verbose: bool = False) -> bool`
-- **Example**: `def scorer_accuracy_threshold(report, dataset, min_score=0.8, verbose=False) -> bool`
+- Purpose: Determine if evaluation results meet success criteria
+- Naming: Functions named `scorer_*` (e.g., `scorer_custom`)
+- Signature: `def scorer_name(report: EvaluationReport, dataset: AixDataset, min_score: float = 1.0, verbose: bool = False) -> bool`
+- Example: `def scorer_accuracy_threshold(report, dataset, min_score=0.8, verbose=False) -> bool`
 
 **Evaluator Functions** (optional):
-- **Purpose**: Custom evaluation logic for comparing outputs with expected results
-- **Naming**: Functions named `evaluator_*` (e.g., `evaluator_check_output`)
-- **Signature**: `def evaluator_name(ctx: EvaluatorContext) -> EvaluatorOutput` or `async def evaluator_name(ctx: EvaluatorContext) -> EvaluatorOutput`
-- **Example**: `def evaluator_exact_match(ctx) -> EvaluatorOutput`
+- Purpose: Custom evaluation logic for comparing outputs with expected results
+- Naming: Functions named `evaluator_*` (e.g., `evaluator_check_output`)
+- Signature: `def evaluator_name(ctx: EvaluatorContext) -> EvaluatorOutput` or `async def evaluator_name(ctx: EvaluatorContext) -> EvaluatorOutput`
+- Example: `def evaluator_exact_match(ctx) -> EvaluatorOutput`
 
 This name-based approach works seamlessly with both synchronous and asynchronous functions.
 
 #### Scoring System
 
-The framework includes a custom scoring system with [`average_assertions`](aixtools/evals/dataset.py:67) as the default scorer. This scorer checks if the average assertion score meets a minimum threshold and provides detailed pass/fail reporting.
-
-## Testing & Tools
-
-AIXtools provides comprehensive testing utilities and diagnostic tools for AI agent development and debugging.
-
-### Running Tests
-
-Execute the test suite using the provided scripts:
-
-```bash
-# Run all tests
-./scripts/test.sh
-
-# Run unit tests only
-./scripts/test_unit.sh
-
-# Run integration tests only
-./scripts/test_integration.sh
-```
-
-### Testing Utilities
-
-The testing module provides mock tools, model patching, and test utilities for comprehensive agent testing.
-
-```python
-from aixtools.testing.mock_tool import MockTool
-from aixtools.testing.model_patch_cache import ModelPatchCache
-from aixtools.testing.aix_test_model import AixTestModel
-
-# Create mock tools for testing
-mock_tool = MockTool(name="test_tool", response="mock response")
-
-# Use model patch caching for consistent test results
-cache = ModelPatchCache()
-cached_response = cache.get_cached_response("test_prompt")
-
-# Test model for controlled testing scenarios
-test_model = AixTestModel()
-```
-
-#### MCP Tool Doctor
-
-Analyze tools from MCP (Model Context Protocol) servers and receive AI-powered recommendations for improvement.
-
-```python
-from aixtools.tools.doctor.mcp_tool_doctor import tool_doctor_mcp
-from pydantic_ai.mcp import MCPServerStreamableHTTP, MCPServerStdio
-
-# Analyze HTTP MCP server
-recommendations = await tool_doctor_mcp(mcp_url='http://127.0.0.1:8000/mcp')
-for rec in recommendations:
-    print(rec)
-
-# Analyze STDIO MCP server
-server = MCPServerStdio(command='fastmcp', args=['run', 'my_server.py'])
-recommendations = await tool_doctor_mcp(mcp_server=server, verbose=True)
-```
-
-**Command Line Usage:**
-
-```bash
-# Analyze HTTP MCP server (default)
-tool_doctor_mcp
-
-# Analyze specific HTTP MCP server
-tool_doctor_mcp --mcp-url http://localhost:9000/mcp --verbose
-
-# Analyze STDIO MCP server
-tool_doctor_mcp --stdio-command fastmcp --stdio-args run my_server.py --debug
-
-# Available options:
-# --mcp-url URL          URL of HTTP MCP server (default: http://127.0.0.1:8000/mcp)
-# --stdio-command CMD    Command to run STDIO MCP server
-# --stdio-args ARGS      Arguments for STDIO MCP server command
-# --verbose              Enable verbose output
-# --debug                Enable debug output
-```
-
-#### Tool Doctor
-
-Analyze tool usage patterns from agent logs and get optimization recommendations.
-
-```python
-from aixtools.tools.doctor.tool_doctor import ToolDoctor
-from aixtools.tools.doctor.tool_recommendation import ToolRecommendation
-
-# Analyze tool usage patterns
-doctor = ToolDoctor()
-analysis = doctor.analyze_tools(agent_logs)
-
-# Get tool recommendations
-recommendation = ToolRecommendation()
-suggestions = recommendation.recommend_tools(agent_context)
-```
-
-### Mock Tool System
-
-Create and manage mock tools for testing agent behavior without external dependencies.
-
-```python
-from aixtools.testing.mock_tool import MockTool
-
-# Create a mock tool with predefined responses
-mock_calculator = MockTool(
-    name="calculator",
-    description="Performs mathematical calculations",
-    response_map={
-        "2+2": "4",
-        "10*5": "50"
-    }
-)
-
-# Use in agent testing
-agent = get_agent(tools=[mock_calculator])
-result = await run_agent(agent, "What is 2+2?")
-```
+The framework includes a custom scoring system with `average_assertions` as the default scorer. This scorer checks if the average assertion score meets a minimum threshold and provides detailed pass/fail reporting.
 
-### Model Patch Caching
-
-Cache model responses for consistent testing and development workflows.
-
-```python
-from aixtools.testing.model_patch_cache import ModelPatchCache
-
-# Initialize cache
-cache = ModelPatchCache(cache_dir="./test_cache")
-
-# Cache responses for specific prompts
-cache.cache_response("test prompt", "cached response")
-
-# Retrieve cached responses
-response = cache.get_cached_response("test prompt")
-```
+## Chainlit & HTTP Server
 
-### FaultyMCP Testing Server
+### Chainlit Integration
 
-Specialized MCP server for testing error handling and resilience in MCP implementations.
+Ready-to-use `Chainlit` application for interactive agent interfaces.
 
 ```python
-from aixtools.mcp.faulty_mcp import run_server_on_port, config
-
-# Configure error probabilities for testing
-config.prob_on_post_404 = 0.3      # 30% chance of 404 on POST
-config.prob_on_get_crash = 0.1     # 10% chance of crash on GET
-config.prob_in_list_tools_throw = 0.2  # 20% chance of exception
-
-# Run the faulty server for testing
-run_server_on_port(port=8888)
-```
-
-**Available Test Tools:**
-- `add(a, b)` - Reliable addition operation
-- `multiply(a, b)` - Reliable multiplication operation
-- `always_error()` - Always throws an exception
-- `random_throw_exception(a, b, prob)` - Randomly throws exceptions
-- `freeze_server(seconds)` - Simulates server freeze
-- `throw_404_exception()` - Throws HTTP 404 error
-
-**Command Line Usage:**
-```bash
-# Run with default error probabilities
-python -m aixtools.mcp.faulty_mcp
-
-# Run in safe mode (no errors)
-python -m aixtools.mcp.faulty_mcp --safe-mode
-
-# Custom configuration
-python -m aixtools.mcp.faulty_mcp \
-    --port 8888 \
-    --prob-on-post-404 0.2 \
-    --prob-on-get-crash 0.1
+# Run the Chainlit app
+# Configuration in aixtools/chainlit.md
+# Main app in aixtools/app.py
 ```
 
-### Agent Mock
+### HTTP Server Framework
 
-Replay previously recorded agent runs without executing the actual agent. Useful for testing, debugging, and creating reproducible test cases.
+AIXtools provides an HTTP server framework for deploying agents and tools as web services.
 
 ```python
-from aixtools.testing.agent_mock import AgentMock
-from aixtools.agents.agent import get_agent, run_agent
+from aixtools.server.app_mounter import mount_app
+from aixtools.server import create_server
 
-# Run an agent and capture its execution
-agent = get_agent(system_prompt="You are a helpful assistant.")
-result, nodes = await run_agent(agent, "Explain quantum computing")
+# Create and configure server
+server = create_server()
 
-# Create a mock agent from the recorded nodes
-agent_mock = AgentMock(nodes=nodes, result_output=result)
-
-# Save the mock for later use
-agent_mock.save(Path("test_data/quantum_mock.pkl"))
+# Mount applications and endpoints
+mount_app(server, "/agent", agent_app)
+mount_app(server, "/tools", tools_app)
 
-# Load and replay the mock agent
-loaded_mock = AgentMock.load(Path("test_data/quantum_mock.pkl"))
-result, nodes = await run_agent(loaded_mock, "any prompt")  # Returns recorded nodes
+# Run server
+server.run(host="0.0.0.0", port=8000)
 ```
 
-## Chainlit & HTTP Server
-
-### Chainlit Integration
-
-Ready-to-use Chainlit application for interactive agent interfaces.
-
-```python
-# Run the Chainlit app
-# Configuration in aixtools/chainlit.md
-# Main app in aixtools/app.py
-```
+**Features:**
+- Application mounting system for modular service composition
+- Integration with `Chainlit` for agent interfaces
+- RESTful API support
+- Middleware support for authentication and logging
 
-## Programming Utils
+## Programming Utilities
 
 AIXtools provides essential programming utilities for configuration management, data persistence, file operations, and context handling.
 
@@ -828,7 +1000,7 @@ print(cache["user_preferences"])  # Persists across program restarts
 
 ### Enum with Description
 
-Enhanced enum classes with built-in descriptions for better documentation and user interfaces.
+Enhanced `Enum` classes with built-in descriptions for better documentation and user interfaces.
 
 ```python
 from aixtools.utils.enum_with_description import EnumWithDescription
@@ -896,7 +1068,7 @@ app_config = AppConfig()
 
 ### File Utilities
 
-Enhanced file operations with Path support and utility functions.
+Enhanced file operations with `Path` support and utility functions.
 
 ```python
 from aixtools.utils.files import read_file, write_file, ensure_directory
@@ -918,7 +1090,7 @@ if config_path.exists():
 
 ### Chainlit Utilities
 
-Specialized utilities for Chainlit integration and agent display.
+Specialized utilities for `Chainlit` integration and agent display.
 
 ```python
 from aixtools.utils.chainlit.cl_agent_show import show_agent_response
@@ -937,6 +1109,83 @@ formatted_msg = format_message(
 )
 ```
 
+### Truncation Utilities
+
+Smart truncation utilities for handling large data structures and preventing context overflow in LLM applications.
+
+```python
+from aixtools.utils import (
+    truncate_recursive_obj,
+    truncate_df_to_csv,
+    truncate_text_head_tail,
+    truncate_text_middle,
+    format_truncation_message,
+    TruncationMetadata
+)
+
+# Truncate nested JSON/dict structures while preserving structure
+data = {"items": [f"item_{i}" for i in range(1000)], "description": "A" * 10000}
+truncated = truncate_recursive_obj(data, max_string_len=100, max_list_len=10)
+
+# Get truncation metadata
+result, metadata = truncate_recursive_obj(
+    data,
+    target_size=1000,
+    ensure_size=True,
+    return_metadata=True
+)
+print(f"Truncated: {metadata.was_truncated}")
+print(f"Size: {metadata.original_size} → {metadata.truncated_size}")
+
+# Truncate DataFrames to CSV with head+tail preview
+import pandas as pd
+df = pd.DataFrame({"col1": range(10000), "col2": ["x" * 200] * 10000})
+csv_output = truncate_df_to_csv(
+    df,
+    max_rows=20,              # Show first 10 and last 10 rows
+    max_columns=10,           # Show first 5 and last 5 columns
+    max_cell_chars=80,        # Truncate cell contents
+    max_row_chars=2000        # Truncate CSV lines
+)
+
+# Truncate text preserving head and tail
+text = "A" * 10000
+truncated, chars_removed = truncate_text_head_tail(text, head_chars=100, tail_chars=100)
+
+# Truncate text in the middle
+truncated, chars_removed = truncate_text_middle(text, max_chars=500)
+
+# Format truncation messages
+message = format_truncation_message(
+    original_size=10000,
+    truncated_size=500,
+    unit="chars",
+    recommendation="Consider processing in smaller chunks"
+)
+```
+
+**Key Features:**
+- **Structure-preserving truncation** - `truncate_recursive_obj()` maintains dict/list structure while truncating
+- **DataFrame to CSV truncation** - `truncate_df_to_csv()` shows head+tail rows and left+right columns
+- **Text truncation strategies** - Head+tail or middle truncation for different use cases
+- **Type-safe metadata** - `TruncationMetadata` Pydantic model with full type hints
+- **Size enforcement** - `ensure_size=True` guarantees output fits within target size
+- **Informative messages** - Automatic generation of user-friendly truncation messages
+
+**Truncation Metadata:**
+
+All truncation functions support `return_metadata=True` to get detailed information:
+
+```python
+result, meta = truncate_recursive_obj(data, target_size=1000, return_metadata=True)
+
+# TruncationMetadata attributes
+meta.original_size    # Original size in characters
+meta.truncated_size   # Final size after truncation
+meta.was_truncated    # Whether truncation occurred
+meta.strategy         # Strategy used: "none", "smart", "middle", "str"
+```
+
 ### General Utilities
 
 Common utility functions for everyday programming tasks.