seme-sdk 0.1.0

Python SDK for SecondMe API

SecondMe Python SDK (seme-sdk)

A Python SDK for interacting with the SecondMe API.

Installation

pip install seme-sdk

Or install from source:

git clone https://github.com/secondme/seme-sdk.git
cd seme-sdk
pip install -e .

Quick Start

Using API Key

from seme import SecondMeClient

# Create client with API Key
client = SecondMeClient(api_key="lba_ak_xxxxx...")

# Get user information
user = client.get_user_info()
print(f"Hello, {user.name}!")

# Streaming chat
for chunk in client.chat_stream("Hello, introduce yourself!"):
    print(chunk.delta, end="", flush=True)

# Close the client when done
client.close()

Using OAuth2

from seme import OAuth2Client, SecondMeClient

# Create OAuth2 client
oauth = OAuth2Client(
    client_id="your_client_id",
    client_secret="your_client_secret",
    redirect_uri="https://your-app.com/callback"
)

# Get authorization URL
auth_url = oauth.get_authorization_url(
    scopes=["user.info", "chat", "note.add"]
)
print(f"Direct user to: {auth_url}")

# Exchange authorization code for tokens
tokens = oauth.exchange_code(code="lba_ac_xxxxx...")

# Create client with auto-refresh
client = SecondMeClient.from_oauth(
    oauth_client=oauth,
    token_response=tokens,
    on_token_refresh=lambda t: print(f"Token refreshed!")
)

API Reference

SecondMeClient

The main client for interacting with SecondMe API.

Initialization

# With API Key (long-lived)
client = SecondMeClient(api_key="lba_ak_xxxxx...")

# With Access Token (short-lived, 2 hours)
client = SecondMeClient(access_token="lba_at_xxxxx...")

# With auto-refresh from OAuth2
client = SecondMeClient.from_oauth(oauth_client, token_response)

User API

# Get user information
user = client.get_user_info()
print(user.name, user.email, user.bio)

# Get user interest shades
shades = client.get_user_shades()
for shade in shades:
    print(shade.shade_name, shade.confidence_level)

# Get user soft memory (with pagination)
memories = client.get_user_softmemory(
    keyword="python",  # optional filter
    page_no=1,
    page_size=20
)
for memory in memories.items:
    print(memory.content)

Note API

# Add a text note
note_id = client.add_note(
    content="This is my note content",
    title="My Note"  # optional
)

# Add a note with URLs
note_id = client.add_note(
    urls=["https://example.com/article"],
    memory_type="URL"
)

Chat API

# Streaming chat
for chunk in client.chat_stream("Hello!"):
    print(chunk.delta, end="", flush=True)

# Chat with session continuity
session_id = None
for chunk in client.chat_stream("Hi!", session_id=session_id):
    if chunk.session_id:
        session_id = chunk.session_id
    print(chunk.delta, end="", flush=True)

# Continue conversation
for chunk in client.chat_stream("Tell me more", session_id=session_id):
    print(chunk.delta, end="", flush=True)

# Chat with custom system prompt
for chunk in client.chat_stream(
    "Tell me a joke",
    system_prompt="You are a friendly comedian."
):
    print(chunk.delta, end="", flush=True)

# Get session list
sessions = client.get_session_list()
for session in sessions:
    print(session.session_id, session.last_message)

# Get session messages
messages = client.get_session_messages(session_id="xxx")
for msg in messages:
    print(f"{msg.role}: {msg.content}")

OAuth2Client

For OAuth2 authorization flow.

from seme import OAuth2Client

oauth = OAuth2Client(
    client_id="your_client_id",
    client_secret="your_client_secret",
    redirect_uri="https://your-app.com/callback"
)

# Generate authorization URL
url = oauth.get_authorization_url(
    scopes=["user.info", "chat"],
    state="csrf_token"  # optional
)

# Exchange code for tokens
tokens = oauth.exchange_code(code="lba_ac_xxxxx...")
print(tokens.access_token)
print(tokens.refresh_token)
print(tokens.expires_in)

# Manually refresh token
new_tokens = oauth.refresh_token(tokens.refresh_token)

Available Scopes

Scope	Description
user.info	Access user basic information
user.info.shades	Access user interest shades
user.info.softmemory	Access user soft memory
note.add	Add notes
chat	Chat and session management

Exception Handling

from seme import (
    SecondMeClient,
    SecondMeError,
    AuthenticationError,
    PermissionDeniedError,
    NotFoundError,
    InvalidParameterError,
    RateLimitError,
    ServerError,
    TokenExpiredError,
)

try:
    client = SecondMeClient(api_key="invalid_key")
    user = client.get_user_info()
except AuthenticationError as e:
    print(f"Authentication failed: {e}")
except PermissionDeniedError as e:
    print(f"Permission denied: {e}")
except TokenExpiredError as e:
    print(f"Token expired: {e}")
except SecondMeError as e:
    print(f"API error: {e}")

Data Models

UserInfo

class UserInfo:
    name: str
    email: str
    avatar: str
    bio: str
    self_introduction: str
    voice_id: str
    profile_completeness: float

Shade

class Shade:
    id: str
    shade_name: str
    confidence_level: float
    public_content: str
    private_content: str

SoftMemory

class SoftMemory:
    id: str
    content: str
    created_at: datetime
    memory_type: str

ChatChunk

class ChatChunk:
    content: str      # Accumulated content
    delta: str        # New content in this chunk
    done: bool        # Whether streaming is complete
    session_id: str
    message_id: str

Session

class Session:
    session_id: str
    app_id: str
    last_message: str
    last_update_time: datetime
    message_count: int

Development

Setup

# Clone the repository
git clone https://github.com/secondme/seme-sdk.git
cd seme-sdk

# Install with dev dependencies
pip install -e ".[dev]"

Running Tests

pytest tests/

Code Style

ruff check .
ruff format .

License

MIT License - see LICENSE for details.