# Echo SDK
A bridge library for developing plugins for the Echo multi-agent system.
## 🎯 Purpose
- **Clean Interfaces**: Well-defined contracts for plugin development
- **Zero Core Dependencies**: Plugins only depend on the SDK, not the core system
- **Independent Distribution**: Plugins can be distributed as standalone packages
- **Version Management**: Dynamic SDK versioning with compatibility checks
- **Testing Isolation**: Test plugins without running the core system
- **Auto-Registration**: Automatic plugin discovery through global registry
- **Hybrid Discovery**: Support for both pip-installable and directory-based plugins
- **Runtime Dependency Installation**: Automatic installation of plugin dependencies
## 📚 Core Concepts
### Plugin Interface (`BasePlugin`)
Every plugin must implement the `BasePlugin` interface:
- `get_metadata()`: Returns `PluginMetadata` with name, version, capabilities, and LLM requirements
- `create_agent()`: Factory method for creating agent instances
- `validate_dependencies()`: Optional dependency validation
- `health_check()`: Optional health check implementation
### Agent Interface (`BasePluginAgent`)
Every agent must implement the `BasePluginAgent` interface:
- `get_tools()`: Returns list of LangChain tools
- `get_system_prompt()`: Returns the system prompt for the agent
- `bind_model()`: Binds tools to an LLM model (inherited from base class)
- `initialize()`: Initializes the agent
- `cleanup()`: Cleans up agent resources
- `create_agent_node()`: Creates LangGraph node function (inherited from base class)
- `should_continue()`: Decides whether to call tools or return to coordinator (inherited from base class)
### Plugin Registry
The SDK provides a global registry for plugin discovery:
- `register_plugin(plugin_class)`: Register a plugin class with the global registry
- `discover_plugins()`: Discover all registered plugins (used by core system)
- `get_plugin_registry()`: Access the global registry instance
### Plugin Contracts (`PluginContract`)
The bridge between core system and plugins:
- Wraps plugin classes for standardized interaction
- Provides validation and health check interfaces
- Enables communication without direct imports
## 🔧 Advanced Features
### Plugin Discovery
The SDK provides comprehensive plugin discovery capabilities:
```python
from echo_sdk import import_plugins_from_environment, import_plugins_from_directories
# Discover pip-installable plugins only
pip_count = import_plugins_from_environment()
# Discover directory-based plugins
dir_count = import_plugins_from_directories(["./plugins", "./custom_plugins"])
```
### Discovery Functions
```python
from echo_sdk.utils import (
# Environment discovery
import_plugins_from_environment,
get_environment_discovery_summary,
list_installed_environment_packages,
list_imported_environment_packages,
reset_environment_discovery,
# Directory discovery
import_plugins_from_directories,
get_directory_discovery_summary,
list_loaded_directories,
list_imported_directory_modules,
reset_directory_discovery,
)
```
### Directory-Based Plugin Discovery
Enable directory-based plugin loading via environment variables:
```bash
# Enable directory discovery
export ECHO_ENABLE_DIRECTORY_PLUGINS=true
# Configure plugin directories
export ECHO_PLUGIN_DIRS="/path/to/plugins,/another/path"
export ECHO_PLUGIN_DIR="./plugins"
```
### Plugin Validation
The SDK includes comprehensive validation:
```python
from echo_sdk.utils import validate_plugin_structure
errors = validate_plugin_structure(MyPlugin)
if errors:
print("Plugin validation failed:", errors)
```
### Model Configuration
The SDK provides flexible model configuration through `ModelConfig`:
```python
from echo_sdk.base.metadata import ModelConfig
config = ModelConfig(
provider="openai",
model_name="gpt-4o",
temperature=0.1,
max_tokens=1024,
additional_params={"top_p": 0.9}
)
```
### Version Compatibility
Check SDK compatibility:
```python
from echo_sdk.utils import check_compatibility, get_sdk_version
is_compatible = check_compatibility(">=0.1.0,<0.2.0", get_sdk_version())
```
### Health Checks
Implement custom health checks:
```python
class MyPlugin(BasePlugin):
@staticmethod
def health_check():
return {
"healthy": True,
"details": "All systems operational"
}
```
### Runtime Dependency Installation
The SDK supports automatic installation of plugin dependencies:
```python
from echo_sdk.utils import install_packages
# Install dependencies declared in plugin metadata
success, log = install_packages(["requests", "numpy"], prefer_poetry=True)
```
## 📦 Package Structure
```
sdk/
├── src/echo_sdk/ # SDK source code
│ ├── __init__.py # Main SDK exports with dynamic versioning
│ ├── base/ # Core interfaces
│ │ ├── __init__.py
│ │ ├── agent.py # BasePluginAgent interface
│ │ ├── plugin.py # BasePlugin interface
│ │ ├── metadata.py # PluginMetadata, ModelConfig
│ │ └── loggable.py # Loggable base class
│ ├── tools/ # Tool utilities
│ │ ├── __init__.py
│ │ ├── decorators.py # @tool decorator (LangChain tool wrapper)
│ │ └── registry.py # Tool registry
│ ├── registry/ # Plugin registry system
│ │ ├── __init__.py
│ │ ├── contracts.py # PluginContract wrapper
│ │ └── plugin_registry.py # Global registry
│ ├── types/ # Type definitions
│ │ ├── __init__.py
│ │ ├── state.py # AgentState TypedDict
│ │ └── messages.py # LangChain message types
│ ├── utils/ # Utility functions
│ │ ├── __init__.py
│ │ ├── validation.py # Plugin validation
│ │ ├── helpers.py # Version compatibility
│ │ ├── environment_discovery.py # Pip plugin discovery
│ │ ├── directory_discovery.py # Directory-based discovery
│ │ └── installers.py # Runtime dependency installation
│ └── examples/ # Template examples
│ ├── __init__.py
│ └── template_plugin/ # Complete plugin template
├── pyproject.toml # Package configuration
├── deploy.sh # Deployment script with dynamic versioning
├── README.md # This documentation
└── LICENSE # MIT license
```
## 🔧 Key Features
### Core Dependencies
- **LangChain Core**: For tool definitions and model binding
- **LangGraph**: For multi-agent orchestration
- **Pydantic**: For data validation and serialization
- **Python 3.13+**: Modern Python features and type hints
### Version Information
- **Current Version**: 0.1.2 (dynamic from pyproject.toml)
- **Python Support**: 3.13+
- **LangChain Core**: >=0.3.74,<0.4.0
- **LangGraph**: >=0.6.5,<0.7.0
- **Pydantic**: >=2.11.7,<3.0.0
### Dynamic Versioning
The SDK uses dynamic versioning that reads from the installed package:
```python
import echo_sdk
print(echo_sdk.__version__) # Shows actual installed version
```
### Agent State Management
The SDK provides comprehensive state management for multi-agent workflows:
```python
from echo_sdk.types.state import AgentState
# State includes:
# - messages: LangChain message sequence
# - current_agent: Active agent identifier
# - agent_hops: Agent transition counter
# - tool_hops: Tool call counter
# - plugin_context: Plugin-specific context
# - routing_history: Agent routing history
```
## 🔍 Plugin Discovery System
### Automatic Discovery
The SDK automatically discovers plugins through multiple mechanisms:
1. **Environment Discovery**: Automatically detects and imports plugins installed via pip
2. **Directory Discovery**: Scans configured directories for plugin modules
3. **Hybrid Discovery**: Combines both methods for comprehensive plugin coverage
### Discovery Functions
```python
from echo_sdk.utils import (
# Environment discovery
import_plugins_from_environment,
get_environment_discovery_summary,
list_installed_environment_packages,
list_imported_environment_packages,
reset_environment_discovery,
# Directory discovery
import_plugins_from_directories,
get_directory_discovery_summary,
list_loaded_directories,
list_imported_directory_modules,
reset_directory_discovery,
)
```
### Discovery Statistics
Get comprehensive discovery information:
```python
from echo_sdk.utils import get_environment_discovery_summary, get_directory_discovery_summary
env_stats = get_environment_discovery_summary()
dir_stats = get_directory_discovery_summary()
print(f"Environment plugins: {env_stats['imported_count']}")
print(f"Directory plugins: {dir_stats['imported_count']}")
```
### Environment Configuration
The SDK supports environment-based configuration for plugin discovery:
```bash
# Enable directory-based plugin discovery
export ECHO_ENABLE_DIRECTORY_PLUGINS=true
# Configure plugin directories (comma-separated)
export ECHO_PLUGIN_DIRS="/path/to/plugins,/another/path"
# Set default plugin directory
export ECHO_PLUGIN_DIR="./plugins"
# Configure agent behavior
export ECHO_MAX_AGENT_HOPS=5
export ECHO_MAX_TOOL_HOPS=25
```
## 🧪 Testing
Test your plugins in isolation using SDK contracts:
```python
import pytest
from echo_sdk import PluginContract, discover_plugins
from echo_sdk.utils import validate_plugin_structure
def test_my_plugin():
# Test plugin structure
errors = validate_plugin_structure(MyPlugin)
assert not errors, f"Plugin validation failed: {errors}"
# Test plugin contract
contract = PluginContract(MyPlugin)
assert contract.is_valid()
# Test metadata
metadata = contract.get_metadata()
assert metadata.name == "my_plugin"
assert metadata.version
# Test agent creation
agent = contract.create_agent()
tools = agent.get_tools()
assert len(tools) > 0
# Test health check
health = contract.health_check()
assert health.get("healthy", False)
def test_plugin_discovery():
# Test that plugin is discoverable via SDK
plugins = discover_plugins()
plugin_names = [p.name for p in plugins]
assert "my_plugin" in plugin_names
def test_discovery_reset():
# Test discovery state management
from echo_sdk.utils import reset_environment_discovery, reset_directory_discovery
# Reset discovery state
reset_environment_discovery()
reset_directory_discovery()
# Rediscover plugins
env_count = import_plugins_from_environment()
dir_count = import_plugins_from_directories(["./plugins"])
assert env_count >= 0
assert dir_count >= 0
def test_agent_interface():
"""Test that agent implements required interface."""
agent = MyAgent(MyPlugin.get_metadata())
# Test required methods
assert hasattr(agent, 'get_tools')
assert hasattr(agent, 'get_system_prompt')
assert hasattr(agent, 'initialize')
assert hasattr(agent, 'cleanup')
# Test tool binding
tools = agent.get_tools()
assert isinstance(tools, list)
assert all(hasattr(tool, 'name') for tool in tools)
```
## 📋 Plugin Template
The SDK includes a complete plugin template at `examples/template_plugin/` with:
- **Proper Project Structure**: Standard plugin package layout
- **Complete Implementation**: All required methods and interfaces
- **Documentation**: Comprehensive docstrings and examples
- **Validation Examples**: Dependency and health check implementations
- **Tool Examples**: Multiple tool types and patterns
### Template Features
The template plugin demonstrates:
```python
# Complete metadata with all fields
PluginMetadata(
name="template_plugin",
version="0.1.0",
description="Template plugin demonstrating Echo SDK usage",
capabilities=["example_capability", "template_operation", "sdk_demonstration"],
llm_requirements={
"provider": "openai",
"model": "gpt-4o",
"temperature": 0.1,
"max_tokens": 1024,
},
agent_type="specialized",
dependencies=["echo_sdk>=1.0.0,<2.0.0"],
)
# Dependency validation
@staticmethod
def validate_dependencies() -> list[str]:
errors = []
try:
import echo_sdk
except ImportError:
errors.append("echo_sdk is required")
return errors
# Health check implementation
@staticmethod
def health_check() -> dict:
return {
"healthy": True,
"details": "Template plugin is operational",
"checks": {"dependencies": "OK", "configuration": "OK"},
}
```
Study this template to understand best practices for SDK-based plugin development.
## 🚀 Deployment
The SDK includes a comprehensive deployment script with dynamic versioning:
```bash
cd /path/to/echo_ai/sdk
./deploy.sh
```
### Deployment Features
- **Dynamic Version Bumping**: Interactive patch/minor/major version selection
- **Pre-deployment Checks**: Git status, poetry installation, build verification
- **Colored Output**: Clear status indicators and progress feedback
- **Optional Git Tagging**: Automatic version tagging with push reminders
- **Build Verification**: Ensures successful package building before upload
### Version Management
The deployment script shows dynamic version progression:
```
Current version in pyproject.toml: 0.1.2
Currently installed version: 0.1.2
Select version bump type:
1) patch (0.1.2 -> 0.1.2)
2) minor (0.1.2 -> 0.2.0)
3) major (0.1.2 -> 1.0.0)
4) Skip version bump
```
## 🔒 Security Features
The SDK provides security boundaries and validation:
- **Plugin Structure Validation**: Comprehensive validation of plugin interfaces and implementations
- **Dependency Checking**: Validates plugin dependencies and SDK version compatibility
- **Safe Tool Execution**: Tool validation and type checking for safe execution
- **Version Compatibility**: Semantic version checking and compatibility enforcement
- **Health Monitoring**: Plugin health checks and failure detection
- **Contract Isolation**: Clean boundaries between core system and plugins
- **Discovery Isolation**: Separate discovery managers prevent cross-contamination
## 📈 Version Compatibility
The SDK uses semantic versioning and provides compatibility checking:
```python
from echo_sdk.utils import check_compatibility, get_sdk_version
# Check if plugin's SDK requirement is compatible
is_compatible = check_compatibility(">=0.1.0", get_sdk_version())
# Plugin metadata should specify SDK requirements
PluginMetadata(
name="my_plugin",
sdk_version=">=0.1.0", # SDK version requirement
# ...
)
```
## 🔗 Related Components
- **[Echo Core](https://github.com/jonaskahn/echo-ai)**: Core multi-agent orchestration system
- **[Echo Plugins](https://github.com/jonaskahn/echo-plugins)**: Example plugins and templates using this SDK
## 🚀 Code Quality
The SDK follows modern Python best practices:
- **KISS Principle**: Keep It Simple, Stupid - clean, focused methods
- **DRY Principle**: Don't Repeat Yourself - reusable components
- **Self-Documenting Code**: Meaningful names, no redundant comments
- **Consistent Formatting**: Black formatter for consistent style
- **Type Hints**: Full type annotations for better IDE support
- **Comprehensive Testing**: Thorough test coverage for all functionality
### Contribution Process
When contributing to the SDK:
1. **Fork and Branch**: Create a feature branch from main
2. **Setup Environment**: Use shared environment (recommended) or individual setup
3. **Follow Standards**: Use existing code style and patterns
4. **Add Tests**: Include tests for new features or bug fixes
5. **Quality Checks**: Run `pytest`, `black`, `mypy`, etc.
6. **Update Documentation**: Keep README and docstrings current
7. **Test Compatibility**: Ensure existing plugins still work
8. **Submit PR**: Create a pull request with clear description
### Development Commands
```bash
# With shared environment active
pytest # Run tests
black src/ # Format code
mypy src/ # Type checking
ruff check src/ # Linting
# Test plugin compatibility
pytest examples/template_plugin/
# Test discovery functionality
python -c "from echo_sdk.utils import import_plugins_from_environment; print(import_plugins_from_environment())"
```
## 📄 License
MIT License - see main project LICENSE file for details.
Raw data
{
"_id": null,
"home_page": "https://github.com/jonaskahn/echo-sdk",
"name": "echo-sdk",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.14,>=3.13",
"maintainer_email": null,
"keywords": "ai, agents, echo-ai, echo_sdk, langchain, langgraph, plugins",
"author": "Jonas Kahn",
"author_email": "me@ifelse.one",
"download_url": "https://files.pythonhosted.org/packages/b9/46/5d81ba40d0a39cf31ead2fe54808acff5a4a7489353e5a9552499963cd1d/echo_sdk-1.0.1.tar.gz",
"platform": null,
"description": "# Echo SDK\n\nA bridge library for developing plugins for the Echo multi-agent system.\n\n## \ud83c\udfaf Purpose\n\n- **Clean Interfaces**: Well-defined contracts for plugin development\n- **Zero Core Dependencies**: Plugins only depend on the SDK, not the core system\n- **Independent Distribution**: Plugins can be distributed as standalone packages\n- **Version Management**: Dynamic SDK versioning with compatibility checks\n- **Testing Isolation**: Test plugins without running the core system\n- **Auto-Registration**: Automatic plugin discovery through global registry\n- **Hybrid Discovery**: Support for both pip-installable and directory-based plugins\n- **Runtime Dependency Installation**: Automatic installation of plugin dependencies\n\n## \ud83d\udcda Core Concepts\n\n### Plugin Interface (`BasePlugin`)\n\nEvery plugin must implement the `BasePlugin` interface:\n\n- `get_metadata()`: Returns `PluginMetadata` with name, version, capabilities, and LLM requirements\n- `create_agent()`: Factory method for creating agent instances\n- `validate_dependencies()`: Optional dependency validation\n- `health_check()`: Optional health check implementation\n\n### Agent Interface (`BasePluginAgent`)\n\nEvery agent must implement the `BasePluginAgent` interface:\n\n- `get_tools()`: Returns list of LangChain tools\n- `get_system_prompt()`: Returns the system prompt for the agent\n- `bind_model()`: Binds tools to an LLM model (inherited from base class)\n- `initialize()`: Initializes the agent\n- `cleanup()`: Cleans up agent resources\n- `create_agent_node()`: Creates LangGraph node function (inherited from base class)\n- `should_continue()`: Decides whether to call tools or return to coordinator (inherited from base class)\n\n### Plugin Registry\n\nThe SDK provides a global registry for plugin discovery:\n\n- `register_plugin(plugin_class)`: Register a plugin class with the global registry\n- `discover_plugins()`: Discover all registered plugins (used by core system)\n- `get_plugin_registry()`: Access the global registry instance\n\n### Plugin Contracts (`PluginContract`)\n\nThe bridge between core system and plugins:\n\n- Wraps plugin classes for standardized interaction\n- Provides validation and health check interfaces\n- Enables communication without direct imports\n\n## \ud83d\udd27 Advanced Features\n\n### Plugin Discovery\n\nThe SDK provides comprehensive plugin discovery capabilities:\n\n```python\nfrom echo_sdk import import_plugins_from_environment, import_plugins_from_directories\n\n# Discover pip-installable plugins only\npip_count = import_plugins_from_environment()\n\n# Discover directory-based plugins\ndir_count = import_plugins_from_directories([\"./plugins\", \"./custom_plugins\"])\n```\n\n### Discovery Functions\n\n```python\nfrom echo_sdk.utils import (\n # Environment discovery\n import_plugins_from_environment,\n get_environment_discovery_summary,\n list_installed_environment_packages,\n list_imported_environment_packages,\n reset_environment_discovery,\n\n # Directory discovery\n import_plugins_from_directories,\n get_directory_discovery_summary,\n list_loaded_directories,\n list_imported_directory_modules,\n reset_directory_discovery,\n)\n```\n\n### Directory-Based Plugin Discovery\n\nEnable directory-based plugin loading via environment variables:\n\n```bash\n# Enable directory discovery\nexport ECHO_ENABLE_DIRECTORY_PLUGINS=true\n\n# Configure plugin directories\nexport ECHO_PLUGIN_DIRS=\"/path/to/plugins,/another/path\"\nexport ECHO_PLUGIN_DIR=\"./plugins\"\n```\n\n### Plugin Validation\n\nThe SDK includes comprehensive validation:\n\n```python\nfrom echo_sdk.utils import validate_plugin_structure\n\nerrors = validate_plugin_structure(MyPlugin)\nif errors:\n print(\"Plugin validation failed:\", errors)\n```\n\n### Model Configuration\n\nThe SDK provides flexible model configuration through `ModelConfig`:\n\n```python\nfrom echo_sdk.base.metadata import ModelConfig\n\nconfig = ModelConfig(\n provider=\"openai\",\n model_name=\"gpt-4o\",\n temperature=0.1,\n max_tokens=1024,\n additional_params={\"top_p\": 0.9}\n)\n```\n\n### Version Compatibility\n\nCheck SDK compatibility:\n\n```python\nfrom echo_sdk.utils import check_compatibility, get_sdk_version\n\nis_compatible = check_compatibility(\">=0.1.0,<0.2.0\", get_sdk_version())\n```\n\n### Health Checks\n\nImplement custom health checks:\n\n```python\nclass MyPlugin(BasePlugin):\n @staticmethod\n def health_check():\n return {\n \"healthy\": True,\n \"details\": \"All systems operational\"\n }\n```\n\n### Runtime Dependency Installation\n\nThe SDK supports automatic installation of plugin dependencies:\n\n```python\nfrom echo_sdk.utils import install_packages\n\n# Install dependencies declared in plugin metadata\nsuccess, log = install_packages([\"requests\", \"numpy\"], prefer_poetry=True)\n```\n\n## \ud83d\udce6 Package Structure\n\n```\nsdk/\n\u251c\u2500\u2500 src/echo_sdk/ # SDK source code\n\u2502 \u251c\u2500\u2500 __init__.py # Main SDK exports with dynamic versioning\n\u2502 \u251c\u2500\u2500 base/ # Core interfaces\n\u2502 \u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u2502 \u251c\u2500\u2500 agent.py # BasePluginAgent interface\n\u2502 \u2502 \u251c\u2500\u2500 plugin.py # BasePlugin interface\n\u2502 \u2502 \u251c\u2500\u2500 metadata.py # PluginMetadata, ModelConfig\n\u2502 \u2502 \u2514\u2500\u2500 loggable.py # Loggable base class\n\u2502 \u251c\u2500\u2500 tools/ # Tool utilities\n\u2502 \u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u2502 \u251c\u2500\u2500 decorators.py # @tool decorator (LangChain tool wrapper)\n\u2502 \u2502 \u2514\u2500\u2500 registry.py # Tool registry\n\u2502 \u251c\u2500\u2500 registry/ # Plugin registry system\n\u2502 \u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u2502 \u251c\u2500\u2500 contracts.py # PluginContract wrapper\n\u2502 \u2502 \u2514\u2500\u2500 plugin_registry.py # Global registry\n\u2502 \u251c\u2500\u2500 types/ # Type definitions\n\u2502 \u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u2502 \u251c\u2500\u2500 state.py # AgentState TypedDict\n\u2502 \u2502 \u2514\u2500\u2500 messages.py # LangChain message types\n\u2502 \u251c\u2500\u2500 utils/ # Utility functions\n\u2502 \u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u2502 \u251c\u2500\u2500 validation.py # Plugin validation\n\u2502 \u2502 \u251c\u2500\u2500 helpers.py # Version compatibility\n\u2502 \u2502 \u251c\u2500\u2500 environment_discovery.py # Pip plugin discovery\n\u2502 \u2502 \u251c\u2500\u2500 directory_discovery.py # Directory-based discovery\n\u2502 \u2502 \u2514\u2500\u2500 installers.py # Runtime dependency installation\n\u2502 \u2514\u2500\u2500 examples/ # Template examples\n\u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u2514\u2500\u2500 template_plugin/ # Complete plugin template\n\u251c\u2500\u2500 pyproject.toml # Package configuration\n\u251c\u2500\u2500 deploy.sh # Deployment script with dynamic versioning\n\u251c\u2500\u2500 README.md # This documentation\n\u2514\u2500\u2500 LICENSE # MIT license\n```\n\n## \ud83d\udd27 Key Features\n\n### Core Dependencies\n\n- **LangChain Core**: For tool definitions and model binding\n- **LangGraph**: For multi-agent orchestration\n- **Pydantic**: For data validation and serialization\n- **Python 3.13+**: Modern Python features and type hints\n\n### Version Information\n\n- **Current Version**: 0.1.2 (dynamic from pyproject.toml)\n- **Python Support**: 3.13+\n- **LangChain Core**: >=0.3.74,<0.4.0\n- **LangGraph**: >=0.6.5,<0.7.0\n- **Pydantic**: >=2.11.7,<3.0.0\n\n### Dynamic Versioning\n\nThe SDK uses dynamic versioning that reads from the installed package:\n\n```python\nimport echo_sdk\nprint(echo_sdk.__version__) # Shows actual installed version\n```\n\n### Agent State Management\n\nThe SDK provides comprehensive state management for multi-agent workflows:\n\n```python\nfrom echo_sdk.types.state import AgentState\n\n# State includes:\n# - messages: LangChain message sequence\n# - current_agent: Active agent identifier\n# - agent_hops: Agent transition counter\n# - tool_hops: Tool call counter\n# - plugin_context: Plugin-specific context\n# - routing_history: Agent routing history\n```\n\n## \ud83d\udd0d Plugin Discovery System\n\n### Automatic Discovery\n\nThe SDK automatically discovers plugins through multiple mechanisms:\n\n1. **Environment Discovery**: Automatically detects and imports plugins installed via pip\n2. **Directory Discovery**: Scans configured directories for plugin modules\n3. **Hybrid Discovery**: Combines both methods for comprehensive plugin coverage\n\n### Discovery Functions\n\n```python\nfrom echo_sdk.utils import (\n # Environment discovery\n import_plugins_from_environment,\n get_environment_discovery_summary,\n list_installed_environment_packages,\n list_imported_environment_packages,\n reset_environment_discovery,\n\n # Directory discovery\n import_plugins_from_directories,\n get_directory_discovery_summary,\n list_loaded_directories,\n list_imported_directory_modules,\n reset_directory_discovery,\n)\n```\n\n### Discovery Statistics\n\nGet comprehensive discovery information:\n\n```python\nfrom echo_sdk.utils import get_environment_discovery_summary, get_directory_discovery_summary\n\nenv_stats = get_environment_discovery_summary()\ndir_stats = get_directory_discovery_summary()\n\nprint(f\"Environment plugins: {env_stats['imported_count']}\")\nprint(f\"Directory plugins: {dir_stats['imported_count']}\")\n```\n\n### Environment Configuration\n\nThe SDK supports environment-based configuration for plugin discovery:\n\n```bash\n# Enable directory-based plugin discovery\nexport ECHO_ENABLE_DIRECTORY_PLUGINS=true\n\n# Configure plugin directories (comma-separated)\nexport ECHO_PLUGIN_DIRS=\"/path/to/plugins,/another/path\"\n\n# Set default plugin directory\nexport ECHO_PLUGIN_DIR=\"./plugins\"\n\n# Configure agent behavior\nexport ECHO_MAX_AGENT_HOPS=5\nexport ECHO_MAX_TOOL_HOPS=25\n```\n\n## \ud83e\uddea Testing\n\nTest your plugins in isolation using SDK contracts:\n\n```python\nimport pytest\nfrom echo_sdk import PluginContract, discover_plugins\nfrom echo_sdk.utils import validate_plugin_structure\n\n\ndef test_my_plugin():\n # Test plugin structure\n errors = validate_plugin_structure(MyPlugin)\n assert not errors, f\"Plugin validation failed: {errors}\"\n\n # Test plugin contract\n contract = PluginContract(MyPlugin)\n assert contract.is_valid()\n\n # Test metadata\n metadata = contract.get_metadata()\n assert metadata.name == \"my_plugin\"\n assert metadata.version\n\n # Test agent creation\n agent = contract.create_agent()\n tools = agent.get_tools()\n assert len(tools) > 0\n\n # Test health check\n health = contract.health_check()\n assert health.get(\"healthy\", False)\n\n\ndef test_plugin_discovery():\n # Test that plugin is discoverable via SDK\n plugins = discover_plugins()\n plugin_names = [p.name for p in plugins]\n assert \"my_plugin\" in plugin_names\n\n\ndef test_discovery_reset():\n # Test discovery state management\n from echo_sdk.utils import reset_environment_discovery, reset_directory_discovery\n\n # Reset discovery state\n reset_environment_discovery()\n reset_directory_discovery()\n\n # Rediscover plugins\n env_count = import_plugins_from_environment()\n dir_count = import_plugins_from_directories([\"./plugins\"])\n assert env_count >= 0\n assert dir_count >= 0\n\n\ndef test_agent_interface():\n \"\"\"Test that agent implements required interface.\"\"\"\n agent = MyAgent(MyPlugin.get_metadata())\n \n # Test required methods\n assert hasattr(agent, 'get_tools')\n assert hasattr(agent, 'get_system_prompt')\n assert hasattr(agent, 'initialize')\n assert hasattr(agent, 'cleanup')\n \n # Test tool binding\n tools = agent.get_tools()\n assert isinstance(tools, list)\n assert all(hasattr(tool, 'name') for tool in tools)\n```\n\n## \ud83d\udccb Plugin Template\n\nThe SDK includes a complete plugin template at `examples/template_plugin/` with:\n\n- **Proper Project Structure**: Standard plugin package layout\n- **Complete Implementation**: All required methods and interfaces\n- **Documentation**: Comprehensive docstrings and examples\n- **Validation Examples**: Dependency and health check implementations\n- **Tool Examples**: Multiple tool types and patterns\n\n### Template Features\n\nThe template plugin demonstrates:\n\n```python\n# Complete metadata with all fields\nPluginMetadata(\n name=\"template_plugin\",\n version=\"0.1.0\",\n description=\"Template plugin demonstrating Echo SDK usage\",\n capabilities=[\"example_capability\", \"template_operation\", \"sdk_demonstration\"],\n llm_requirements={\n \"provider\": \"openai\",\n \"model\": \"gpt-4o\",\n \"temperature\": 0.1,\n \"max_tokens\": 1024,\n },\n agent_type=\"specialized\",\n dependencies=[\"echo_sdk>=1.0.0,<2.0.0\"],\n)\n\n# Dependency validation\n@staticmethod\ndef validate_dependencies() -> list[str]:\n errors = []\n try:\n import echo_sdk\n except ImportError:\n errors.append(\"echo_sdk is required\")\n return errors\n\n# Health check implementation\n@staticmethod\ndef health_check() -> dict:\n return {\n \"healthy\": True,\n \"details\": \"Template plugin is operational\",\n \"checks\": {\"dependencies\": \"OK\", \"configuration\": \"OK\"},\n }\n```\n\nStudy this template to understand best practices for SDK-based plugin development.\n\n## \ud83d\ude80 Deployment\n\nThe SDK includes a comprehensive deployment script with dynamic versioning:\n\n```bash\ncd /path/to/echo_ai/sdk\n./deploy.sh\n```\n\n### Deployment Features\n\n- **Dynamic Version Bumping**: Interactive patch/minor/major version selection\n- **Pre-deployment Checks**: Git status, poetry installation, build verification\n- **Colored Output**: Clear status indicators and progress feedback\n- **Optional Git Tagging**: Automatic version tagging with push reminders\n- **Build Verification**: Ensures successful package building before upload\n\n### Version Management\n\nThe deployment script shows dynamic version progression:\n\n```\nCurrent version in pyproject.toml: 0.1.2\nCurrently installed version: 0.1.2\n\nSelect version bump type:\n1) patch (0.1.2 -> 0.1.2)\n2) minor (0.1.2 -> 0.2.0)\n3) major (0.1.2 -> 1.0.0)\n4) Skip version bump\n```\n\n## \ud83d\udd12 Security Features\n\nThe SDK provides security boundaries and validation:\n\n- **Plugin Structure Validation**: Comprehensive validation of plugin interfaces and implementations\n- **Dependency Checking**: Validates plugin dependencies and SDK version compatibility\n- **Safe Tool Execution**: Tool validation and type checking for safe execution\n- **Version Compatibility**: Semantic version checking and compatibility enforcement\n- **Health Monitoring**: Plugin health checks and failure detection\n- **Contract Isolation**: Clean boundaries between core system and plugins\n- **Discovery Isolation**: Separate discovery managers prevent cross-contamination\n\n## \ud83d\udcc8 Version Compatibility\n\nThe SDK uses semantic versioning and provides compatibility checking:\n\n```python\nfrom echo_sdk.utils import check_compatibility, get_sdk_version\n\n# Check if plugin's SDK requirement is compatible\nis_compatible = check_compatibility(\">=0.1.0\", get_sdk_version())\n\n# Plugin metadata should specify SDK requirements\nPluginMetadata(\n name=\"my_plugin\",\n sdk_version=\">=0.1.0\", # SDK version requirement\n # ...\n)\n```\n\n## \ud83d\udd17 Related Components\n\n- **[Echo Core](https://github.com/jonaskahn/echo-ai)**: Core multi-agent orchestration system\n- **[Echo Plugins](https://github.com/jonaskahn/echo-plugins)**: Example plugins and templates using this SDK\n\n## \ud83d\ude80 Code Quality\n\nThe SDK follows modern Python best practices:\n\n- **KISS Principle**: Keep It Simple, Stupid - clean, focused methods\n- **DRY Principle**: Don't Repeat Yourself - reusable components\n- **Self-Documenting Code**: Meaningful names, no redundant comments\n- **Consistent Formatting**: Black formatter for consistent style\n- **Type Hints**: Full type annotations for better IDE support\n- **Comprehensive Testing**: Thorough test coverage for all functionality\n\n### Contribution Process\n\nWhen contributing to the SDK:\n\n1. **Fork and Branch**: Create a feature branch from main\n2. **Setup Environment**: Use shared environment (recommended) or individual setup\n3. **Follow Standards**: Use existing code style and patterns\n4. **Add Tests**: Include tests for new features or bug fixes\n5. **Quality Checks**: Run `pytest`, `black`, `mypy`, etc.\n6. **Update Documentation**: Keep README and docstrings current\n7. **Test Compatibility**: Ensure existing plugins still work\n8. **Submit PR**: Create a pull request with clear description\n\n### Development Commands\n\n```bash\n# With shared environment active\npytest # Run tests\nblack src/ # Format code\nmypy src/ # Type checking\nruff check src/ # Linting\n\n# Test plugin compatibility\npytest examples/template_plugin/\n\n# Test discovery functionality\npython -c \"from echo_sdk.utils import import_plugins_from_environment; print(import_plugins_from_environment())\"\n```\n\n## \ud83d\udcc4 License\n\nMIT License - see main project LICENSE file for details.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Echo SDK - To building custom AI agent plugins for Echo AI Framework",
"version": "1.0.1",
"project_urls": {
"Documentation": "https://echo_sdk.readthedocs.io/",
"Homepage": "https://github.com/jonaskahn/echo-sdk",
"Repository": "https://github.com/jonaskahn/echo-sdk.git",
"issues": "https://github.com/jonaskahn/echo-sdk/issues"
},
"split_keywords": [
"ai",
" agents",
" echo-ai",
" echo_sdk",
" langchain",
" langgraph",
" plugins"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "bf08aacb8636b3e75f84738ba7fb6ede6932a2be0f4d9ea26ed1ef32d7c89f61",
"md5": "2a47659143109457a27da094ecb2e799",
"sha256": "98c389e06f0aae315cb50686e5f6dd279597e88c6cf0ff24ed42fd53c3f71f8b"
},
"downloads": -1,
"filename": "echo_sdk-1.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2a47659143109457a27da094ecb2e799",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.14,>=3.13",
"size": 31292,
"upload_time": "2025-08-27T07:35:05",
"upload_time_iso_8601": "2025-08-27T07:35:05.931675Z",
"url": "https://files.pythonhosted.org/packages/bf/08/aacb8636b3e75f84738ba7fb6ede6932a2be0f4d9ea26ed1ef32d7c89f61/echo_sdk-1.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "b9465d81ba40d0a39cf31ead2fe54808acff5a4a7489353e5a9552499963cd1d",
"md5": "8c94d44d5e282c548271abe1e9129efa",
"sha256": "30d79818eefbb3fc083f5b5fc6da680cac6746a9ba9062b324fa4f55db881d7b"
},
"downloads": -1,
"filename": "echo_sdk-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "8c94d44d5e282c548271abe1e9129efa",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.14,>=3.13",
"size": 27113,
"upload_time": "2025-08-27T07:35:07",
"upload_time_iso_8601": "2025-08-27T07:35:07.769506Z",
"url": "https://files.pythonhosted.org/packages/b9/46/5d81ba40d0a39cf31ead2fe54808acff5a4a7489353e5a9552499963cd1d/echo_sdk-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-27 07:35:07",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "jonaskahn",
"github_project": "echo-sdk",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "echo-sdk"
}
JSON
