feat: add sharpaikit Python SDK with gRPC control plane

Author: dxpython

python-client/.gitignore

@@ -0,0 +1,48 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+env/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Generated gRPC code (optional - can be committed or regenerated)
+# sharpaikit/_grpc/agent_pb2.py
+# sharpaikit/_grpc/agent_pb2_grpc.py
+
+# OS
+.DS_Store
+Thumbs.db
+

python-client/.pypirc.example

@@ -0,0 +1,11 @@
+# PyPI Configuration Example
+# Copy this file to ~/.pypirc and fill in your API token
+
+[pypi]
+username = __token__
+password = pypi-your-api-token-here
+
+[testpypi]
+username = __token__
+password = pypi-your-test-api-token-here
+

python-client/GRPC_SETUP.md

@@ -0,0 +1,85 @@
+# gRPC Setup Guide
+
+## Overview
+
+The SharpAIKit Python SDK uses gRPC for communication between Python and the C# runtime. This document explains how to set up and generate the required gRPC code.
+
+## Prerequisites
+
+1. **Protocol Buffers Compiler** (`protoc`)
+   - Install from: https://grpc.io/docs/protoc-installation/
+   - Or via package manager:
+     - macOS: `brew install protobuf`
+     - Ubuntu: `apt-get install protobuf-compiler`
+     - Windows: Download from GitHub releases
+
+2. **Python gRPC Tools**
+   ```bash
+   pip install grpcio-tools
+   ```
+
+## Generating gRPC Code
+
+### For Python
+
+```bash
+cd python-client
+python generate_grpc.py
+```
+
+This will generate:
+- `sharpaikit/_grpc/agent_pb2.py` - Protocol buffer message classes
+- `sharpaikit/_grpc/agent_pb2_grpc.py` - gRPC service stubs
+
+### Manual Generation
+
+If the script doesn't work, generate manually:
+
+```bash
+cd python-client
+python -m grpc_tools.protoc \
+    --proto_path=../../proto \
+    --python_out=sharpaikit/_grpc \
+    --grpc_python_out=sharpaikit/_grpc \
+    ../../proto/agent.proto
+```
+
+### For C#
+
+C# gRPC code is automatically generated during build via `Grpc.Tools` package.
+
+## Verifying Generation
+
+After generation, you should see:
+
+```bash
+ls sharpaikit/_grpc/
+# agent_pb2.py
+# agent_pb2_grpc.py
+# __init__.py
+```
+
+## Troubleshooting
+
+### "protoc: command not found"
+
+Install Protocol Buffers compiler (see Prerequisites).
+
+### "ModuleNotFoundError: No module named 'grpc_tools'"
+
+```bash
+pip install grpcio-tools
+```
+
+### Import Errors
+
+Ensure generated files are in `sharpaikit/_grpc/` and `__init__.py` exists.
+
+## Updating Proto Files
+
+If you modify `proto/agent.proto`:
+
+1. Regenerate Python code: `python generate_grpc.py`
+2. Rebuild C# project: `dotnet build src/SharpAIKit.Grpc/`
+3. Restart gRPC host
+

python-client/IMPLEMENTATION_PLAN.md

@@ -0,0 +1,99 @@
+# 完整功能实现计划
+
+## 📋 实现范围
+
+需要实现以下所有功能：
+
+### ⚠️ 部分支持 → 完全支持 (3项)
+1. **工具注册** - Python 端直接注册工具
+2. **日志** - 完整的 Python 端日志支持
+3. **工具定义** - 完整的工具定义和管理
+
+### ❌ 尚未支持 → 完全支持 (28项)
+1. **Chain (LCEL)** - 链式调用、管道、并行、分支
+2. **Memory 系统** - Buffer, Window, Summary, Vector, Entity
+3. **Prompt Templates** - 提示模板创建和格式化
+4. **Output Parsers** - JSON, Boolean, List, XML, Regex
+5. **Document Loaders** - Text, CSV, JSON, Markdown, Web, Directory
+6. **RAG Engine** - 文档索引、检索、问答
+7. **Code Interpreter** - C# 代码执行（通过 gRPC）
+8. **SharpGraph** - 图编排、节点、边、状态管理
+9. **DSPy Optimizer** - 自动提示词优化
+10. **MultiModal** - 图像支持
+11. **完整的 Observability** - 日志、指标、追踪
+
+## 🎯 实现策略
+
+### 阶段 1: 协议定义 ✅
+- [x] 创建完整的 `sharpaikit.proto` 文件
+- [x] 定义所有服务的消息类型
+
+### 阶段 2: C# gRPC 服务实现
+- [ ] ChainService - 链服务
+- [ ] MemoryService - 记忆服务
+- [ ] RAGService - RAG 服务
+- [ ] GraphService - 图服务
+- [ ] PromptService - 提示服务
+- [ ] OutputParserService - 输出解析服务
+- [ ] DocumentLoaderService - 文档加载服务
+- [ ] CodeInterpreterService - 代码解释器服务
+- [ ] OptimizerService - 优化器服务
+- [ ] ToolService - 工具服务
+- [ ] ObservabilityService - 可观测性服务
+
+### 阶段 3: Python SDK 客户端实现
+- [ ] Chain 客户端
+- [ ] Memory 客户端
+- [ ] RAG 客户端
+- [ ] Graph 客户端
+- [ ] Prompt 客户端
+- [ ] OutputParser 客户端
+- [ ] DocumentLoader 客户端
+- [ ] CodeInterpreter 客户端
+- [ ] Optimizer 客户端
+- [ ] Tool 客户端
+- [ ] Observability 客户端
+
+### 阶段 4: 高级封装
+- [ ] Python 端的高级 API（类似 Agent 类）
+- [ ] Fluent API 支持
+- [ ] 上下文管理器支持
+
+### 阶段 5: 文档和示例
+- [ ] 更新所有文档
+- [ ] 创建完整示例
+- [ ] 更新功能覆盖文档
+
+## 📝 实现顺序（优先级）
+
+### 高优先级（核心功能）
+1. **Chain Service** - 最常用的功能
+2. **Memory Service** - Agent 必需
+3. **RAG Service** - 重要功能
+4. **Tool Service** - 工具注册
+
+### 中优先级（增强功能）
+5. **Prompt Service** - 提示模板
+6. **OutputParser Service** - 输出解析
+7. **DocumentLoader Service** - 文档加载
+8. **Graph Service** - 图编排
+
+### 低优先级（高级功能）
+9. **CodeInterpreter Service** - C# 特有
+10. **Optimizer Service** - 高级优化
+11. **MultiModal** - 多模态（可集成到现有服务）
+12. **Observability Service** - 可观测性
+
+## 🚀 开始实现
+
+由于这是一个大工程，建议：
+1. 先实现核心服务（Chain, Memory, RAG）
+2. 然后实现增强功能
+3. 最后实现高级功能
+
+每个服务都需要：
+- C# gRPC 服务实现
+- Python SDK 客户端
+- 单元测试
+- 使用示例
+

python-client/INSTALL.md

@@ -0,0 +1,86 @@
+# SharpAIKit Python SDK Installation Guide
+
+## Prerequisites
+
+1. **Python 3.8+**
+2. **.NET 8.0 SDK** (for building the gRPC host)
+3. **uv** (recommended) or **pip**
+
+## Installation Steps
+
+### Step 1: Build the gRPC Host
+
+```bash
+cd ../src/SharpAIKit.Grpc.Host
+dotnet build -c Release
+```
+
+### Step 2: Generate Python gRPC Code
+
+```bash
+cd ../../python-client
+
+# Install grpc-tools if not already installed
+uv pip install grpcio-tools
+
+# Generate gRPC code
+python generate_grpc.py
+```
+
+This will generate:
+- `sharpaikit/_grpc/agent_pb2.py`
+- `sharpaikit/_grpc/agent_pb2_grpc.py`
+
+### Step 3: Install the Python SDK
+
+#### Using uv (Recommended)
+
+```bash
+uv pip install -e .
+```
+
+#### Using pip
+
+```bash
+pip install -e .
+```
+
+## Verification
+
+```python
+from sharpaikit import Agent
+
+# This will automatically start the host if needed
+agent = Agent(
+    api_key="your-api-key",
+    model="gpt-3.5-turbo",
+    auto_start_host=True
+)
+
+# Test connection
+result = agent.run("Hello")
+print(result.output)
+```
+
+## Troubleshooting
+
+### gRPC Code Not Generated
+
+If you see `ImportError: gRPC code not generated`, run:
+
+```bash
+python generate_grpc.py
+```
+
+### Host Process Fails to Start
+
+1. Ensure .NET 8.0 SDK is installed: `dotnet --version`
+2. Build the host: `cd ../src/SharpAIKit.Grpc.Host && dotnet build`
+3. Check port 50051 is available
+
+### Connection Errors
+
+1. Verify host is running: `lsof -i :50051`
+2. Check firewall settings
+3. Verify host address (default: localhost:50051)
+

python-client/LICENSE

@@ -0,0 +1,23 @@
+MIT License
+
+Copyright (c) 2025
+SharpAIKit Authors and Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the “Software”), to deal
+in the Software without restriction, including without limitation the rights to:
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software, along with attribution to
+“SharpAIKit Authors and Contributors”.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+DAMAGES, OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT,
+OR OTHERWISE, ARISING FROM, OUT OF, OR IN CONNECTION WITH THE SOFTWARE
+OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

python-client/MANIFEST.in

@@ -0,0 +1,23 @@
+include README_PYPI.md
+include LICENSE
+recursive-include sharpaikit *.py
+recursive-include sharpaikit/_grpc *.py
+global-exclude __pycache__
+global-exclude *.pyc
+global-exclude *.pyo
+global-exclude .DS_Store
+global-exclude *.egg-info
+global-exclude dist
+global-exclude build
+global-exclude examples
+global-exclude tests
+global-exclude *.md
+global-exclude *.sh
+global-exclude *.toml
+global-exclude *.lock
+global-exclude Makefile
+global-exclude setup.py
+global-exclude generate_grpc.py
+global-exclude build.sh
+global-exclude publish_to_pypi.sh
+