Skip to content

Commit b10ca3f

Browse files
RahulHereRahulHere
RahulHere
authored and
RahulHere
committed
Add pip install example for testing TestPyPI packages
Create examples/pip directory with scripts to test the SDK when installed via pip from TestPyPI. Files: - README.md: Documentation for pip installation and usage - client_example_json.py: Python example using JSON server configuration - client_example_json_run.sh: Script to set up venv, install from TestPyPI, start MCP servers, and run the example Usage: cd examples/pip ./client_example_json_run.sh # Or with specific version: SDK_VERSION=0.1.0.dev20260131170458 ./client_example_json_run.sh
1 parent b7628cb commit b10ca3f

File tree

3 files changed

+377
-0
lines changed

3 files changed

+377
-0
lines changed

‎examples/pip/README.md‎

Lines changed: 171 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,171 @@
1+
# Using gopher-orch SDK via pip
2+
3+
This guide shows how to use the gopher-orch Python SDK when installed via pip.
4+
5+
## Installation
6+
7+
```bash
8+
pip install gopher-orch
9+
```
10+
11+
The package will automatically detect your platform and load the native library from the corresponding platform-specific package.
12+
13+
### Supported Platforms
14+
15+
| Platform | Architecture | Package |
16+
|----------|-------------|---------|
17+
| macOS | ARM64 (Apple Silicon) | gopher-orch-native-darwin-arm64 |
18+
| macOS | x64 (Intel) | gopher-orch-native-darwin-x64 |
19+
| Linux | x64 | gopher-orch-native-linux-x64 |
20+
| Linux | ARM64 | gopher-orch-native-linux-arm64 |
21+
| Windows | x64 | gopher-orch-native-win32-x64 |
22+
| Windows | ARM64 | gopher-orch-native-win32-arm64 |
23+
24+
### Installing from TestPyPI
25+
26+
For testing pre-release versions:
27+
28+
```bash
29+
pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ gopher-orch
30+
```
31+
32+
## Quick Start
33+
34+
### Using API Key
35+
36+
```python
37+
from gopher_orch import GopherAgent
38+
39+
# Create agent with API key (fetches server config from Gopher API)
40+
agent = GopherAgent.create_with_api_key(
41+
'AnthropicProvider',
42+
'claude-3-haiku-20240307',
43+
'your-gopher-api-key'
44+
)
45+
46+
# Run a query
47+
answer = agent.run('What is the weather like in New York?')
48+
print(answer)
49+
50+
# Clean up when done
51+
agent.dispose()
52+
```
53+
54+
### Using Server Configuration
55+
56+
```python
57+
import json
58+
from gopher_orch import GopherAgent
59+
60+
# Server configuration JSON
61+
server_config = json.dumps({
62+
"succeeded": True,
63+
"code": 200000000,
64+
"message": "success",
65+
"data": {
66+
"servers": [
67+
{
68+
"version": "2025-01-09",
69+
"serverId": "1",
70+
"name": "my-mcp-server",
71+
"transport": "http_sse",
72+
"config": {
73+
"url": "http://localhost:3001/mcp",
74+
"headers": {}
75+
},
76+
"connectTimeout": 5000,
77+
"requestTimeout": 30000,
78+
},
79+
],
80+
},
81+
})
82+
83+
# Create agent with server config
84+
agent = GopherAgent.create_with_server_config(
85+
'AnthropicProvider',
86+
'claude-3-haiku-20240307',
87+
server_config
88+
)
89+
90+
# Run a query
91+
answer = agent.run('List available tools')
92+
print(answer)
93+
94+
# Clean up when done
95+
agent.dispose()
96+
```
97+
98+
## Running the Example
99+
100+
### Prerequisites
101+
102+
1. Python 3.8+ installed
103+
2. MCP servers running (see examples/server3001 and examples/server3002)
104+
3. ANTHROPIC_API_KEY environment variable set
105+
106+
### Run with the provided script
107+
108+
```bash
109+
cd examples/pip
110+
111+
# Use default (latest) SDK version from TestPyPI
112+
./client_example_json_run.sh
113+
114+
# Or specify a specific version
115+
SDK_VERSION=0.1.0.dev20260131170458 ./client_example_json_run.sh
116+
```
117+
118+
### Run manually
119+
120+
```bash
121+
# Create a virtual environment
122+
python3 -m venv venv
123+
source venv/bin/activate
124+
125+
# Install from TestPyPI (for testing)
126+
pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ gopher-orch
127+
128+
# Or install from PyPI (when released)
129+
# pip install gopher-orch
130+
131+
# Run the example
132+
python client_example_json.py
133+
```
134+
135+
## API Reference
136+
137+
### GopherAgent
138+
139+
#### Static Methods
140+
141+
- `GopherAgent.create_with_api_key(provider, model, api_key)` - Create agent using Gopher API key
142+
- `GopherAgent.create_with_server_config(provider, model, server_config_json)` - Create agent with server configuration JSON
143+
144+
#### Instance Methods
145+
146+
- `agent.run(query, timeout_ms=30000)` - Run a query and return the response
147+
- `agent.dispose()` - Release resources (must be called when done)
148+
149+
## Troubleshooting
150+
151+
### Native library not found
152+
153+
If you see "Failed to load gopher-orch library", ensure:
154+
155+
1. You're on a supported platform
156+
2. The platform-specific package is installed
157+
3. Try reinstalling: `pip install --force-reinstall gopher-orch`
158+
159+
### Permission errors on macOS
160+
161+
If you get permission errors loading the library:
162+
163+
```bash
164+
xattr -d com.apple.quarantine $(python -c "import gopher_orch_native_darwin_arm64; print(gopher_orch_native_darwin_arm64.get_library_file())")
165+
```
166+
167+
## Environment Variables
168+
169+
- `ANTHROPIC_API_KEY` - Required for using Anthropic models
170+
- `DEBUG=1` - Enable debug logging for library loading
171+
- `GOPHER_ORCH_LIBRARY_PATH` - Override the native library path

‎examples/pip/client_example_json.py‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
#!/usr/bin/env python3
2+
"""
3+
Example using JSON server configuration with pip-installed SDK.
4+
5+
This example shows how to use the gopher-orch SDK when installed via pip.
6+
The native library is automatically loaded from the platform-specific package.
7+
"""
8+
9+
import json
10+
import sys
11+
12+
from gopher_orch import GopherAgent
13+
14+
15+
# Server configuration for local MCP servers
16+
SERVER_CONFIG = json.dumps({
17+
"succeeded": True,
18+
"code": 200000000,
19+
"message": "success",
20+
"data": {
21+
"servers": [
22+
{
23+
"version": "2025-01-09",
24+
"serverId": "1",
25+
"name": "server1",
26+
"transport": "http_sse",
27+
"config": {"url": "http://127.0.0.1:3001/mcp", "headers": {}},
28+
"connectTimeout": 5000,
29+
"requestTimeout": 30000,
30+
},
31+
{
32+
"version": "2025-01-09",
33+
"serverId": "2",
34+
"name": "server2",
35+
"transport": "http_sse",
36+
"config": {"url": "http://127.0.0.1:3002/mcp", "headers": {}},
37+
"connectTimeout": 5000,
38+
"requestTimeout": 30000,
39+
},
40+
],
41+
},
42+
})
43+
44+
45+
def main():
46+
provider = "AnthropicProvider"
47+
model = "claude-3-haiku-20240307"
48+
49+
try:
50+
# Create agent with JSON server configuration
51+
agent = GopherAgent.create_with_server_config(provider, model, SERVER_CONFIG)
52+
print("GopherAgent created!")
53+
54+
# Get question from command line args or use default
55+
args = sys.argv[1:]
56+
question = " ".join(args) if args else "What is the weather like in New York?"
57+
print(f"Question: {question}")
58+
59+
# Run the query
60+
answer = agent.run(question)
61+
print("Answer:")
62+
print(answer)
63+
64+
# Cleanup
65+
agent.dispose()
66+
except Exception as e:
67+
print(f"Error: {e}", file=sys.stderr)
68+
import traceback
69+
traceback.print_exc()
70+
sys.exit(1)
71+
72+
73+
if __name__ == "__main__":
74+
main()

‎examples/pip/client_example_json_run.sh‎

Lines changed: 132 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
1+
#!/bin/bash
2+
3+
# Run the Python client example using pip-installed SDK
4+
# This demonstrates how to use gopher-orch when installed via pip
5+
6+
set -e
7+
8+
# Colors for output
9+
RED='\033[0;31m'
10+
GREEN='\033[0;32m'
11+
YELLOW='\033[1;33m'
12+
CYAN='\033[0;36m'
13+
NC='\033[0m' # No Color
14+
15+
# Get the script directory
16+
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
17+
EXAMPLES_DIR="$(dirname "$SCRIPT_DIR")"
18+
PROJECT_DIR="$(dirname "$EXAMPLES_DIR")"
19+
WORK_DIR="$SCRIPT_DIR/test-project"
20+
21+
# SDK version to install (can be overridden via environment variable)
22+
SDK_VERSION="${SDK_VERSION:-}"
23+
24+
# Kill any existing processes on ports 3001 and 3002
25+
kill_port() {
26+
local port=$1
27+
local pids=$(lsof -ti :$port 2>/dev/null || true)
28+
if [ -n "$pids" ]; then
29+
echo -e "${YELLOW}Killing existing process on port $port${NC}"
30+
echo "$pids" | xargs kill -9 2>/dev/null || true
31+
fi
32+
}
33+
34+
# Cleanup function
35+
cleanup() {
36+
echo -e "\n${YELLOW}Cleaning up...${NC}"
37+
kill_port 3001
38+
kill_port 3002
39+
# Deactivate virtual environment if active
40+
if [ -n "$VIRTUAL_ENV" ]; then
41+
deactivate 2>/dev/null || true
42+
fi
43+
echo -e "${GREEN}Done${NC}"
44+
}
45+
46+
trap cleanup EXIT
47+
48+
echo -e "${GREEN}======================================${NC}"
49+
echo -e "${GREEN}Running pip SDK Example${NC}"
50+
echo -e "${GREEN}======================================${NC}"
51+
echo ""
52+
53+
# Create test project directory
54+
echo -e "${YELLOW}Setting up test project...${NC}"
55+
rm -rf "$WORK_DIR"
56+
mkdir -p "$WORK_DIR"
57+
cd "$WORK_DIR"
58+
59+
# Create virtual environment
60+
echo -e "${YELLOW}Creating virtual environment...${NC}"
61+
python3 -m venv venv
62+
source venv/bin/activate
63+
64+
# Install SDK from TestPyPI
65+
echo -e "${YELLOW}Installing gopher-orch from TestPyPI...${NC}"
66+
if [ -n "$SDK_VERSION" ]; then
67+
echo -e "${CYAN}Installing version: $SDK_VERSION${NC}"
68+
pip install --index-url https://test.pypi.org/simple/ \
69+
--extra-index-url https://pypi.org/simple/ \
70+
"gopher-orch==$SDK_VERSION"
71+
else
72+
echo -e "${CYAN}Installing latest version${NC}"
73+
pip install --index-url https://test.pypi.org/simple/ \
74+
--extra-index-url https://pypi.org/simple/ \
75+
gopher-orch
76+
fi
77+
78+
# Show installed version
79+
echo -e "${CYAN}Installed packages:${NC}"
80+
pip list | grep -i gopher
81+
82+
# Copy the example Python file
83+
cp "$SCRIPT_DIR/client_example_json.py" .
84+
85+
# Kill any existing processes on ports
86+
kill_port 3001
87+
kill_port 3002
88+
89+
# Start server3001
90+
echo -e "${YELLOW}Starting server3001...${NC}"
91+
cd "$EXAMPLES_DIR/server3001"
92+
if [ ! -d "node_modules" ]; then
93+
echo -e "${YELLOW}Installing dependencies for server3001...${NC}"
94+
npm install
95+
fi
96+
npm run dev > /dev/null 2>&1 &
97+
SERVER3001_PID=$!
98+
echo -e "${GREEN}server3001 started (PID: $SERVER3001_PID)${NC}"
99+
100+
# Start server3002
101+
echo -e "${YELLOW}Starting server3002...${NC}"
102+
cd "$EXAMPLES_DIR/server3002"
103+
if [ ! -d "node_modules" ]; then
104+
echo -e "${YELLOW}Installing dependencies for server3002...${NC}"
105+
npm install
106+
fi
107+
npm run dev > /dev/null 2>&1 &
108+
SERVER3002_PID=$!
109+
echo -e "${GREEN}server3002 started (PID: $SERVER3002_PID)${NC}"
110+
111+
# Wait for servers to start
112+
echo -e "${YELLOW}Waiting for servers to start...${NC}"
113+
sleep 3
114+
115+
# Run the Python client
116+
echo ""
117+
echo -e "${YELLOW}Running Python client...${NC}"
118+
echo ""
119+
cd "$WORK_DIR"
120+
121+
# Run with Python
122+
python client_example_json.py "$@"
123+
124+
echo ""
125+
echo -e "${GREEN}Example completed${NC}"
126+
echo ""
127+
echo -e "${CYAN}To run this example manually:${NC}"
128+
echo " 1. python3 -m venv venv && source venv/bin/activate"
129+
echo " 2. pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ gopher-orch"
130+
echo " 3. python client_example_json.py"
131+
132+
exit 0

0 commit comments

Comments
 (0)