finn-sdk 0.1.0

Python SDK for connecting to the Finn (finn-ai) agent over WebSocket.

finn-sdk (Python)

Python SDK for the Finn (finn-ai) agent over WebSocket. The async counterpart of the Node/TypeScript @riseanalytics/finn-sdk — same connection, events, and error codes.

Install

pip install finn-sdk

Requires Python 3.9+.

Usage

import asyncio
from finn_sdk import FinnClient

async def main():
    finn = FinnClient(url="https://finn.example.com", api_key="your-key")
    await finn.connect()

    # Stream tokens as they arrive
    turn = await finn.send_message(
        "What were Q3 deposits?",
        system_prompt="You are a terse analyst.",
    )
    async for chunk in turn:
        print(chunk.text, end="", flush=True)
    result = await turn.completed  # TurnResult(conversation_id, message_id, token_usage, ...)

    # Continue the same conversation
    follow = await finn.send_message("And Q4?", conversation_id=result.conversation_id)
    await follow.completed

    await finn.disconnect()

asyncio.run(main())

Or use the client as an async context manager (auto connect/disconnect):

async with FinnClient(url=url, api_key=key) as finn:
    answer = await finn.ask("How many active members do I have?")
    print(answer.text)

Notes

• Auth: pass api_key (static) or get_api_key (sync or async callable, for rotation). Sent as the Socket.IO handshake token.
• System prompt: system_prompt (client default or per-call override) applies only when a conversation is first created; it is ignored on continuation turns.
• Not streaming? await finn.ask(text) returns an AskResult (the turn result plus the full text). await finn.ask_json(text) parses the answer as JSON — prompt for JSON yourself; it raises FinnError(code="invalid_json") if it can't parse, with the raw answer on error.details["raw"].
• Interrupt: turn.interrupt() stops generation; the turn settles with interrupted=True.
• Errors: failures raise a FinnError whose code is one of unauthorized, rate_limited, timeout, conversation_read_only, stream_error, disconnected, invalid_json.
• Events: finn.on("connected" | "disconnect" | "reconnect" | "rateLimit" | "unauthorized", cb).
• Naming: methods and fields use Python snake_case (send_message, conversation_id, token_usage) — the TypeScript SDK uses camelCase.

Develop

pip install -e ".[test]"
pytest