Platform SDK Client

Complete Python SDK for PraisonAI Platform API with connection pooling and full CRUD operations

The Platform SDK provides a complete async Python client for interacting with the PraisonAI Platform API, featuring connection pooling for optimal performance and comprehensive CRUD operations for all platform resources.

Quick Start

1. Install Package

   pip install praisonai-platform
   
2. Basic Usage

   from praisonai_platform import PlatformClient
   
   # Context manager (recommended - uses connection pooling)
   async with PlatformClient("http://localhost:8000") as client:
       # Register and auto-set token
       await client.register("[e-mail]", "password123")
       
       # Create workspace and project
       workspace = await client.create_workspace("My Team")
       project = await client.create_project(workspace["id"], "Sprint 1")
       
       # Create and manage issues
       issue = await client.create_issue(
           workspace["id"], 
           "Fix login bug", 
           project_id=project["id"]
       )
   
3. Standalone Usage

   # Without context manager (creates client per request)
   client = PlatformClient("http://localhost:8000", token="your-jwt-token")
   workspaces = await client.list_workspaces()
   

---

Connection Pooling

The client supports two usage patterns with automatic connection pooling optimization:

Pattern	Connection Strategy	Performance	Use Case
Context Manager	Single pooled client	⚡ High	Multiple API calls
Standalone	Client per request	🔄 Standard	Single API calls

---

API Methods

Authentication

Register

async with PlatformClient("http://localhost:8000") as client:
    user_data = await client.register(
        email="[e-mail]",
        password="secure123",
        name="John Doe"  # optional
    )
    # Token automatically set for future requests

Login

async with PlatformClient("http://localhost:8000") as client:
    auth_data = await client.login("[e-mail]", "secure123")
    # Token automatically set for future requests

Get Current User

user_info = await client.get_me()

Workspaces

Create & List

# Create workspace
workspace = await client.create_workspace("Development Team", slug="dev-team")

# List all workspaces
workspaces = await client.list_workspaces()

# Get specific workspace
workspace = await client.get_workspace("workspace-id")

Update & Delete

# Update workspace
updated = await client.update_workspace("workspace-id", name="New Name")

# Delete workspace
await client.delete_workspace("workspace-id")

Members

Add & List

# Add member to workspace
member = await client.add_member(
    workspace_id="ws-123",
    user_id="user-456", 
    role="admin"  # admin, member, viewer
)

# List workspace members
members = await client.list_members("ws-123")

Update & Remove

# Update member role
await client.update_member_role("ws-123", "user-456", "viewer")

# Remove member
await client.remove_member("ws-123", "user-456")

Projects

Create & List

# Create project
project = await client.create_project(
    workspace_id="ws-123",
    title="Q1 Sprint",
    description="First quarter development sprint"
)

# List projects
projects = await client.list_projects("ws-123")

# Get project details
project = await client.get_project("ws-123", "project-456")

Update & Stats

# Update project
await client.update_project("ws-123", "project-456", status="active")

# Get project statistics
stats = await client.get_project_stats("ws-123", "project-456")

# Delete project
await client.delete_project("ws-123", "project-456")

Issues

Create & List

# Create issue
issue = await client.create_issue(
    workspace_id="ws-123",
    title="Fix authentication bug",
    description="Users cannot log in with SSO",
    project_id="project-456",
    priority="high",  # none, low, medium, high, urgent
    assignee_type="user",
    assignee_id="user-789"
)

# List issues with filters
issues = await client.list_issues(
    workspace_id="ws-123",
    status="open",
    project_id="project-456"
)

Update & Get

# Get issue details
issue = await client.get_issue("ws-123", "issue-789")

# Update issue
await client.update_issue(
    workspace_id="ws-123", 
    issue_id="issue-789",
    status="in_progress",
    priority="urgent"
)

# Delete issue
await client.delete_issue("ws-123", "issue-789")

Comments

Add & List

# Add comment to issue
comment = await client.add_comment(
    workspace_id="ws-123",
    issue_id="issue-789",
    content="I'm investigating this bug now"
)

# List all comments on issue
comments = await client.list_comments("ws-123", "issue-789")

Agents

Create & List

# Create agent
agent = await client.create_agent(
    workspace_id="ws-123",
    name="Code Reviewer",
    runtime_mode="cloud",  # local, cloud
    instructions="Review all code changes for security issues"
)

# List agents
agents = await client.list_agents("ws-123")

# Get agent details
agent = await client.get_agent("ws-123", "agent-456")

Update & Delete

# Update agent
await client.update_agent(
    workspace_id="ws-123",
    agent_id="agent-456", 
    instructions="Focus on performance optimization"
)

# Delete agent
await client.delete_agent("ws-123", "agent-456")

Labels

Create & List

# Create label
label = await client.create_label(
    workspace_id="ws-123",
    name="bug",
    color="#ff0000",
    description="Bug reports"
)

# List labels
labels = await client.list_labels("ws-123")

Manage Issue Labels

# Add label to issue
await client.add_label_to_issue("ws-123", "issue-789", "label-123")

# Remove label from issue
await client.remove_label_from_issue("ws-123", "issue-789", "label-123")

# List issue labels
issue_labels = await client.list_issue_labels("ws-123", "issue-789")

# Update label
await client.update_label("ws-123", "label-123", color="#00ff00")

# Delete label
await client.delete_label("ws-123", "label-123")

Dependencies

Create & List

# Create dependency between issues
dependency = await client.create_dependency(
    workspace_id="ws-123",
    blocker_id="issue-123",  # Issue that blocks
    blocked_id="issue-456"   # Issue that is blocked
)

# List dependencies for workspace
dependencies = await client.list_dependencies("ws-123")

Delete

# Remove dependency
await client.delete_dependency("ws-123", "dependency-789")

Activity Tracking

Workspace Activity

# Get workspace activity feed
activities = await client.list_workspace_activity(
    workspace_id="ws-123",
    limit=50,
    offset=0
)

Issue Activity

# Get activity for specific issue
issue_activities = await client.list_issue_activity(
    workspace_id="ws-123",
    issue_id="issue-789"
)

---

Error Handling

The client raises httpx.HTTPStatusError for HTTP errors:

import httpx

try:
    async with PlatformClient("http://localhost:8000") as client:
        workspace = await client.get_workspace("invalid-id")
except httpx.HTTPStatusError as e:
    if e.response.status_code == 404:
        print("Workspace not found")
    elif e.response.status_code == 401:
        print("Authentication required")
    else:
        print(f"API error: {e.response.status_code}")

---

Best Practices

Use Connection Pooling

Always prefer the context manager pattern for multiple API calls to benefit from connection pooling:

# ✅ Good - Connection pooling
async with PlatformClient(base_url) as client:
    for workspace in await client.list_workspaces():
        projects = await client.list_projects(workspace["id"])

# ❌ Avoid - New connection per request  
client = PlatformClient(base_url)
for workspace in await client.list_workspaces():
    projects = await client.list_projects(workspace["id"])

Handle Token Management

The client automatically manages tokens after register() or login(). For existing tokens:

# Set token explicitly
client = PlatformClient("http://localhost:8000", token="your-jwt-token")

# Or let register/login set it automatically
async with PlatformClient("http://localhost:8000") as client:
    await client.login(email, password)  # Token auto-set
    # All subsequent requests use this token

Batch Related Operations

Group related API calls within the same context manager for optimal performance:

async with PlatformClient(base_url) as client:
    # Batch workspace setup
    workspace = await client.create_workspace("Team A")
    await client.add_member(workspace["id"], "user-1", "admin")
    await client.add_member(workspace["id"], "user-2", "member")
    
    # Batch project creation
    project = await client.create_project(workspace["id"], "Sprint 1")
    await client.create_issue(workspace["id"], "Setup CI/CD", project_id=project["id"])
    await client.create_issue(workspace["id"], "Write tests", project_id=project["id"])

Environment Configuration

Use environment variables for configuration in production:

import os

client = PlatformClient(
    base_url=os.getenv("PRAISON_PLATFORM_URL", "http://localhost:8000"),
    token=os.getenv("PRAISON_PLATFORM_TOKEN")
)

---

Related

Platform API Reference

Complete REST API documentation

Agent Platform Integration

Connect agents to platform resources