Python SDK
Everything you need to know to use Payman with Python
Interact with the Payman AI Platform’s API using Python. This SDK is designed for both end users and developers, making it easy to move money, automate workflows, and build powerful AI-driven financial applications.
Installation
Environment Setup
Before running the SDK, set up your environment variables in a .env
file at the root of your project:
Get these credentials from your Payman dashboard after registering an app. They are required for both SDK usage.
Authentication & Initialization
You can initialize the client in several ways, depending on your use case:
Using Client Credentials (Recommended)
Using an Authorization Code (OAuth)
Using an Access Token or Refresh Token
You can also initialize with only a refresh token:
Making Requests
Get a Formatted Response
Get a Raw Response
Streaming Requests
Use the on_message
callback for real-time updates, long-running
tasks, or progress monitoring. You can also stream raw responses by passing
raw=True
.
Using Metadata
You can attach metadata at different levels to customize and track your requests:
Request-level metadata:
Message-level metadata:
Part-level metadata:
Session Management
Sessions allow you to maintain context across multiple requests. Each client instance manages its own session by default, so you can have ongoing conversations or workflows that remember previous actions.
How Sessions Work
- Every client instance starts a new session unless you provide a
session_id
. - The session ID is included in every response from
client.ask()
. - You can use this session ID to resume a conversation or workflow at any time, even across different client instances or after a restart.
Resuming a Session
To resume a previous session, pass the session_id
when initializing the client:
You can also resume with the with_token
method:
To get the current session ID from any client instance:
Session management is essential for building conversational agents, multi-step workflows, or any scenario where you want to maintain state across requests.
Token Management
Tokens are fetched and refreshed automatically. You can also access them directly if needed:
Tokens refresh automatically before they expire. If you provide a refresh token, the SDK will use it as needed.
Error Handling
All API calls will raise an exception if the request fails. You can catch and handle these exceptions as needed:
API Reference (At a Glance)
PaymanClient Static Methods
with_credentials(config: PaymanConfig) -> PaymanClient
with_auth_code(config: PaymanConfig, auth_code: str) -> PaymanClient
with_token(client_id: str, token_info: Dict[str, Any], ...) -> PaymanClient
Instance Methods
ask(text: str, options: Optional[AskOptions] = None, raw: bool = False)
get_access_token() -> Optional[Dict[str, Any]]
get_refresh_token() -> Optional[str]
is_access_token_expired() -> bool
get_session_id() -> str
get_client_name() -> Optional[str]
Need help? Email us at [email protected]