GeniSpace Python SDK

Official Python SDK for GeniSpace AI Platform (API aligned with sdk-javascript)

🎯 Overview

GeniSpace Python SDK is the official Python client for GeniSpace.ai, providing full API access for user management, agent control, task execution, storage, and more—with the same interface as the JavaScript/TypeScript SDK.

Key Features

• 🔐 API Key authentication — Secure API key management and auth
• 👤 User management — Profile, settings, teams, statistics
• 🔑 API Key management — List, create, update, revoke, validate
• 🤖 Agents — Create, execute, chat, sessions, memory
• 📋 Tasks — List, execute, logs, statistics
• 📦 Storage — File/folder upload, list, delete, search
• 🔄 Auto retry — Built-in retry on network errors
• 📊 Unified errors — GeniSpaceError with code and status_code

🚀 Installation

pip install genispace

Or install from source (for development or unreleased versions):

pip install -e .
# Or dependencies only
pip install -r requirements.txt

🔧 Quick Start

Basic Usage

from genispace import GeniSpace

# Supports api_key / base_url (Python) or apiKey / baseURL (JS-style)
client = GeniSpace(
    api_key="your-api-key-here",
    base_url="https://api.genispace.ai",  # Optional, default
    timeout=30000,   # Optional, milliseconds
    retries=3,       # Optional
)

# Get current user
try:
    user = client.users.get_profile()
    print("Current user:", user)
except Exception as e:
    print("Failed:", e)

Using environment variables

import os
from genispace import GeniSpace

client = GeniSpace(
    api_key=os.environ.get("GENISPACE_API_KEY", ""),
    base_url=os.environ.get("GENISPACE_BASE_URL", "https://api.genispace.ai"),
)

Error handling

from genispace import GeniSpace, GeniSpaceError

try:
    result = client.agents.execute("agent-id", {"inputs": {}})
except GeniSpaceError as e:
    if e.code == "UNAUTHORIZED":
        print("API key invalid or expired")
    elif e.code == "RATE_LIMIT_EXCEEDED":
        print("Rate limit exceeded")
    else:
        print("API error:", e.message, e.code, e.status_code)

📚 API Reference

User Management (Users)

# Get user profile
profile = client.users.get_profile()

# Update profile
client.users.update_profile({"name": "New Name", "company": "New Company"})

# Change password
client.users.update_password({
    "currentPassword": "current-password",
    "newPassword": "new-password",
})

# Get / update settings (teamId + preferences)
settings = client.users.get_settings()
client.users.update_settings({"preferences": {"theme": "dark"}})

# Bind phone
client.users.bind_phone("+8613800138000")

# List teams
teams = client.users.get_teams()

# User statistics
stats = client.users.get_statistics()

API Key Management (ApiKeys)

# List
api_keys = client.api_keys.list()

# Create
new_key = client.api_keys.create({
    "name": "Development Key",
    "application": "Client App",
    "expiresAt": "2025-12-31T23:59:59Z",
    "permissions": ["read:tasks", "write:agents"],
})
print("New key (returned only at creation):", new_key.get("key"))

# Update / revoke
client.api_keys.update("key-id", {"name": "Updated Name"})
client.api_keys.revoke("key-id")

# Validate (unauthenticated request)
validation = client.api_keys.validate("your-api-key-to-check")
print("Valid:", validation.get("valid"))
if validation.get("keyInfo"):
    print("Owner:", validation["keyInfo"]["owner"]["name"])

# Team-related
client.api_keys.list_team_keys("team-id")
client.api_keys.list_member_keys("team-id", "member-id")
client.api_keys.revoke_member_key("team-id", "member-id", "key-id")

Agent Management (Agents)

# List (supports page, limit, agentType, search)
result = client.agents.list({"page": 1, "limit": 20, "agentType": "CHAT"})

# Create
agent = client.agents.create({
    "name": "Customer Service Assistant",
    "model": "gpt-4",
    "systemPrompt": "You are a professional customer service assistant",
    "agentType": "CHAT",
    "description": "Customer service assistant",
})

# Chat
response = client.agents.chat(agent["id"], {
    "contents": [{"type": "text", "text": "Hello, I need help"}],
    "session_id": "session-123",
    "stream": False,
})

# Execute task
result = client.agents.execute(agent["id"], {
    "inputs": {"query": "Analyze this document", "memory": True},
    "settings": {"temperature": 0.7, "maxTokens": 2000},
})

# Sessions
session = client.agents.create_session({
    "userAgentId": agent["id"],
    "title": "Customer Service Chat",
    "sessionType": "chat",
})
sessions = client.agents.get_sessions()
client.agents.get_session(session["sessionId"])
client.agents.update_session(session["sessionId"], {"title": "New Title"})
client.agents.delete_session(session["sessionId"])

# Memory
client.agents.get_memory(agent["id"])
client.agents.create_memory(agent["id"], {"content": "User prefers dark mode"})
client.agents.search_memory(agent["id"], {"query": "preference"})
client.agents.clear_session_memory(agent["id"], session["sessionId"])

Task Management (Tasks)

# List (returns { "data": [...], "pagination": {...} })
result = client.tasks.list({
    "status": "COMPLETED",
    "type": "SCHEDULED",
    "page": 1,
    "limit": 10,
})
tasks = result["data"]
pagination = result["pagination"]

# Execute
execution = client.tasks.execute("task-id", {"param": "value"})

# Details and execution records
task = client.tasks.get_task("task-id")
execution_detail = client.tasks.get_execution("execution-id")
schema = client.tasks.get_schema("task-id")

# Run status and logs
run_status = client.tasks.get_run_status("task-execution-id")
client.tasks.cancel_execution("execution-id")
stats = client.tasks.get_task_stats("task-id")
logs = client.tasks.get_execution_logs_paginated("execution-id", {"page": 1})

Storage

# Upload (file can be path, file-like, or (filename, fileobj))
file_info = client.storage.upload_file("/path/to/file.txt", options={"folderId": "folder-id"})
# Or
with open("file.txt", "rb") as f:
    file_info = client.storage.upload_file(f, options={"fileName": "file.txt"})

# List and manage files
files = client.storage.list_files({"folderId": "folder-id"})
file_info = client.storage.get_file("file-id")
content = client.storage.get_file_content("file-id")  # bytes
client.storage.delete_file("file-id")
client.storage.delete_files(["id1", "id2"])
client.storage.rename_file("file-id", "new-name.txt")
client.storage.move_file("file-id", "target-folder-id")

# Folders
folder = client.storage.create_folder("Folder", parent_id="parent-id")
folders = client.storage.list_folders("parent-id")
client.storage.rename_folder("folder-id", "New Name")
client.storage.delete_folder("folder-id")

# Batch delete and stats
client.storage.batch_delete([{"id": "id1", "type": "file"}, {"id": "id2", "type": "folder"}])
stats = client.storage.get_stats()
search_result = client.storage.search_files("query", {"page": 1})

🔐 Authentication and Security

• Create API keys in GeniSpace Platform → Settings → API Keys.
• Prefer environment variables: GENISPACE_API_KEY, GENISPACE_BASE_URL.

🛠️ Advanced Usage

Update config at runtime

client.update_api_key("new-api-key")
client.update_base_url("https://custom-api.example.com")
config = client.get_config()

Pagination example

def get_all_tasks(client):
    all_tasks = []
    page = 1
    while True:
        result = client.tasks.list({"page": page, "limit": 100})
        all_tasks.extend(result["data"])
        pagination = result.get("pagination", {})
        if page >= pagination.get("pages", 1):
            break
        page += 1
    return all_tasks

🧪 Testing

Unit tests are provided for Users, ApiKeys, Agents, Tasks, Storage (mocked HTTP; no live API required):

# Install dev dependencies
pip install -r requirements-dev.txt

# Run all tests
PYTHONPATH=. python -m pytest tests/ -v

# Run by resource
PYTHONPATH=. python -m pytest tests/test_users.py tests/test_api_keys.py -v
PYTHONPATH=. python -m pytest tests/test_agents.py tests/test_tasks.py tests/test_storage.py -v
PYTHONPATH=. python -m pytest tests/test_client.py -v

Coverage: client (config, errors), users (profile/settings/teams/stats), api_keys (list/create/update/revoke/validate/team), agents (list/create/execute/chat/sessions/memory), tasks (list/execute/executions/schema/run status/stats), storage (upload/list/get/delete/folders/stats/search).

📦 Publishing (to PyPI)

Automated (GitHub Actions)

• Pushing a tag v*.*.* (e.g. v1.0.1) triggers .github/workflows/publish.yml, which:
  • Parses the version from the tag and updates pyproject.toml
  • Runs python -m build to produce sdist and wheel
  • Uploads to PyPI with twine upload
• Configure PYPI_API_TOKEN in the repo Secrets (PyPI → Account settings → API tokens).

Manual publish

# 1. Install build and upload tools
pip install build twine

# 2. Confirm version in pyproject.toml

# 3. Build
python -m build

# 4. Upload to PyPI (set TWINE_USERNAME=__token__ and TWINE_PASSWORD to your PyPI token)
twine upload dist/*

# Test PyPI (optional)
twine upload --repository testpypi dist/*

🔗 Related Links

• Website: https://genispace.ai
• Documentation: https://docs.genispace.ai
• JavaScript SDK: sdk-javascript (API reference)
• Issue Reports: GitHub Issues
• 中文说明: README_CN.md

📄 License

MIT License.

---

Built by GeniSpace.ai Dev Team