mirror of
https://github.com/hanzoai/stack.git
synced 2026-11-19 03:06:57 +00:00
11 KiB
11 KiB
Python SDK Monorepo Structure (Complete)
Transform python-sdk into a monorepo containing all Python packages except dev/ide:
python-sdk/
├── pkg/
│ ├── hanzoai/ # Core SDK (current src/hanzoai)
│ │ ├── pyproject.toml
│ │ ├── README.md
│ │ └── src/
│ │ └── hanzoai/
│ │ ├── __init__.py
│ │ ├── agents.py # Imports from hanzo-agents
│ │ ├── mcp.py # Imports from hanzo-mcp
│ │ ├── cluster.py # Imports from hanzo-cluster
│ │ ├── a2a.py # Imports from hanzo-a2a
│ │ └── ... (existing SDK files)
│ │
│ ├── hanzo-cluster/ # Local AI cluster management
│ │ ├── pyproject.toml
│ │ ├── README.md
│ │ └── src/
│ │ └── hanzo_cluster/
│ │ ├── __init__.py
│ │ ├── cluster.py
│ │ ├── exo_integration.py
│ │ ├── models.py
│ │ └── api.py
│ │
│ ├── hanzo-miner/ # Distributed compute mining
│ │ ├── pyproject.toml
│ │ ├── README.md
│ │ └── src/
│ │ └── hanzo_miner/
│ │ ├── __init__.py
│ │ ├── miner.py
│ │ ├── wallet.py
│ │ ├── rewards.py
│ │ └── network.py
│ │
│ ├── hanzo-mcp/ # MCP server and client (from ide/pkg/mcp)
│ │ ├── pyproject.toml
│ │ ├── README.md
│ │ └── src/
│ │ └── hanzo_mcp/
│ │ ├── __init__.py
│ │ ├── server.py
│ │ ├── cli.py
│ │ ├── tools/ # All MCP tools
│ │ └── prompts/
│ │
│ ├── hanzo-a2a/ # Agent-to-agent communication protocol
│ │ ├── pyproject.toml
│ │ ├── README.md
│ │ └── src/
│ │ └── hanzo_a2a/
│ │ ├── __init__.py
│ │ ├── protocol.py # A2A wire protocol
│ │ ├── messaging.py # Message passing
│ │ ├── discovery.py # Agent discovery
│ │ ├── auth.py # Agent authentication
│ │ ├── routing.py # Message routing
│ │ └── bridge.py # MCP<->A2A bridge
│ │
│ ├── hanzo-tools/ # Tool framework and base classes
│ │ ├── pyproject.toml
│ │ ├── README.md
│ │ └── src/
│ │ └── hanzo_tools/
│ │ ├── __init__.py
│ │ ├── base.py # BaseTool class
│ │ ├── registry.py # ToolRegistry
│ │ ├── context.py # ToolContext
│ │ ├── permissions.py # PermissionManager
│ │ ├── batch.py # BatchTool
│ │ ├── pagination.py # Pagination support
│ │ ├── streaming.py # Streaming results
│ │ └── decorators.py # Tool decorators
│ │
│ ├── hanzo-agents/ # Agent SDK (from ide/pkg/agents)
│ │ ├── pyproject.toml
│ │ ├── README.md
│ │ └── src/
│ │ └── hanzo_agents/
│ │ ├── __init__.py
│ │ ├── core/
│ │ ├── memory/
│ │ ├── routing/
│ │ └── cli/
│ │
│ ├── hanzo-network/ # Agent networks (from ide/pkg/hanzo_network)
│ │ ├── pyproject.toml
│ │ ├── README.md
│ │ └── src/
│ │ └── hanzo_network/
│ │ ├── __init__.py
│ │ ├── core/
│ │ └── tools/
│ │
│ ├── hanzo-memory/ # Memory and RAG tools
│ │ ├── pyproject.toml
│ │ ├── README.md
│ │ └── src/
│ │ └── hanzo_memory/
│ │ ├── __init__.py
│ │ ├── kv_store.py
│ │ ├── vector_store.py
│ │ ├── rag.py
│ │ └── embeddings.py
│ │
│ ├── hanzo-aci/ # AI Compute Interface (from ide/pkg/aci)
│ │ ├── pyproject.toml
│ │ ├── README.md
│ │ └── src/
│ │ └── hanzo_aci/
│ │ ├── __init__.py
│ │ └── ... (all aci code)
│ │
│ ├── hanzo-analytics/ # Analytics (from ide/pkg/analytics)
│ │ ├── pyproject.toml
│ │ ├── README.md
│ │ └── src/
│ │ └── hanzo_analytics/
│ │ ├── __init__.py
│ │ └── ... (all analytics code)
│ │
│ └── hanzo-mcp-client/ # MCP client library (if separate from server)
│ ├── pyproject.toml
│ ├── README.md
│ └── src/
│ └── hanzo_mcp_client/
│ ├── __init__.py
│ ├── client.py
│ └── transport.py
│
├── tests/ # Unified test suite
│ ├── test_hanzoai/
│ ├── test_cluster/
│ ├── test_miner/
│ ├── test_mcp/
│ ├── test_a2a/
│ ├── test_tools/
│ ├── test_agents/
│ ├── test_network/
│ ├── test_memory/
│ └── test_integration/
│
├── docs/ # Unified documentation
│ ├── api/
│ ├── guides/
│ ├── protocols/
│ └── examples/
│
├── examples/ # Example code
│ ├── local_ai/
│ ├── agent_networks/
│ ├── mining/
│ ├── a2a_communication/
│ └── unified/
│
├── scripts/ # Build and utility scripts
│ ├── build_all.py
│ ├── test_all.py
│ ├── publish.py
│ └── migrate_from_ide.py
│
├── Makefile # Top-level makefile
├── pyproject.toml # Workspace configuration
├── README.md
└── .github/
└── workflows/
├── ci.yml
└── release.yml
Package Relationships
graph TD
hanzoai[hanzoai<br/>Main SDK] --> cluster[hanzo-cluster]
hanzoai --> miner[hanzo-miner]
hanzoai --> mcp[hanzo-mcp]
hanzoai --> agents[hanzo-agents]
hanzoai --> a2a[hanzo-a2a]
mcp --> tools[hanzo-tools]
agents --> tools
agents --> memory[hanzo-memory]
agents --> a2a
network[hanzo-network] --> agents
network --> a2a
cluster --> aci[hanzo-aci]
miner --> analytics[hanzo-analytics]
mcp --> mcpclient[hanzo-mcp-client]
Migration Plan
Phase 1: Setup Monorepo Structure
cd python-sdk
mkdir -p pkg
mv src/hanzoai pkg/hanzoai/src/hanzoai
Phase 2: Extract Core Framework
- Create pkg/hanzo-tools from ide/pkg/mcp/hanzo_mcp/tools/common/
- Create pkg/hanzo-a2a as new protocol package
Phase 3: Migrate from IDE monorepo
# From ide monorepo
cp -r pkg/mcp python-sdk/pkg/hanzo-mcp
cp -r pkg/agents python-sdk/pkg/hanzo-agents
cp -r pkg/hanzo_network python-sdk/pkg/hanzo-network
cp -r pkg/aci python-sdk/pkg/hanzo-aci
cp -r pkg/analytics python-sdk/pkg/hanzo-analytics
Phase 4: Extract and Refactor
- Extract cluster code from hanzoai/cluster.py → pkg/hanzo-cluster
- Extract miner code → pkg/hanzo-miner
- Extract tool base classes → pkg/hanzo-tools
- Create memory package from agent memory tools
Phase 5: Update Dependencies
Each package declares its dependencies:
hanzoai/pyproject.toml
[project]
name = "hanzoai"
dependencies = [] # No direct deps, uses optional
[project.optional-dependencies]
cluster = ["hanzo-cluster>=0.1.0"]
miner = ["hanzo-miner>=0.1.0"]
mcp = ["hanzo-mcp>=0.1.0"]
agents = ["hanzo-agents>=0.1.0"]
a2a = ["hanzo-a2a>=0.1.0"]
all = ["hanzoai[cluster,miner,mcp,agents,a2a]"]
hanzo-mcp/pyproject.toml
[project]
dependencies = [
"hanzo-tools>=0.1.0",
"fastmcp>=0.1.0",
"mcp>=0.1.0",
]
hanzo-agents/pyproject.toml
[project]
dependencies = [
"hanzo-tools>=0.1.0",
"hanzo-memory>=0.1.0",
"hanzo-a2a>=0.1.0",
]
Workspace Configuration
[project]
name = "hanzo-python-monorepo"
version = "2.0.0"
description = "Hanzo AI Python SDK Monorepo"
[tool.rye]
managed = true
workspace = { members = ["pkg/*"] }
[tool.rye.scripts]
# Development
dev = "rye sync --all-features"
test = "pytest tests/ -v"
lint = "ruff check pkg/"
format = "ruff format pkg/"
typecheck = "mypy pkg/"
# Build
build-all = "python scripts/build_all.py"
build = { chain = ["build:hanzo-tools", "build:rest"] }
"build:hanzo-tools" = "cd pkg/hanzo-tools && rye build"
"build:rest" = "python scripts/build_all.py --skip hanzo-tools"
# Testing
test-all = "python scripts/test_all.py"
test-unit = "pytest tests/ -v -m 'not integration'"
test-integration = "pytest tests/ -v -m integration"
# Publishing
publish-all = "python scripts/publish.py"
publish-test = "python scripts/publish.py --test-pypi"
# Migration
migrate = "python scripts/migrate_from_ide.py"
Installation Examples
# For users - install what they need
pip install hanzoai # Core SDK only
pip install hanzoai[mcp] # With MCP tools
pip install hanzoai[agents] # With agents
pip install hanzoai[cluster] # With local AI
pip install hanzoai[all] # Everything
# For specific tools
pip install hanzo-mcp # Just MCP server/tools
pip install hanzo-agents # Just agent SDK
pip install hanzo-cluster # Just cluster management
# For developers - install everything in dev mode
cd python-sdk
rye sync --all-features
Benefits
- Single Source of Truth: All Python packages in one place
- Unified CI/CD: One set of tests, one release process
- Better Integration Testing: Test across packages easily
- Consistent Tooling: Same build/test/lint setup everywhere
- Easier Dependency Management: Rye workspace handles it all
- IDE keeps focus: IDE monorepo only has dev/ide packages