fora-sdk 0.1.7

Typed builder for Fora voice-AI workflows

fora-sdk

Typed builder for Fora voice-AI workflows. Fetches the node-spec catalog from the Fora backend at session start, validates every call against it at the call site, and produces ReactFlowDTO-compatible JSON.

Install

pip install fora-sdk

For local development against a checked-out monorepo:

pip install -e sdk/python/

Usage

from fora_sdk import ForaClient, Workflow

with ForaClient(base_url="http://localhost:8000", api_key="...") as client:
    wf = Workflow(client=client, name="loan_qualification")

    start = wf.add(
        type="startCall",
        name="greeting",
        prompt="You are Sarah from Acme Loans. Greet the caller warmly.",
        greeting_type="text",
        greeting="Hi {{first_name}}, this is Sarah.",
    )
    qualify = wf.add(
        type="agentNode",
        name="qualify",
        prompt="Ask about loan amount and timeline.",
    )
    done = wf.add(type="endCall", name="done", prompt="Thank the caller.")

    wf.edge(start, qualify, label="interested", condition="Caller expressed interest.")
    wf.edge(qualify, done, label="done", condition="Qualification complete.")

    client.save_workflow(workflow_id=123, workflow=wf)

What gets validated at the call site

The SDK fetches the spec for each node type via get_node_type and raises ValidationError immediately when:

• an unknown field is passed (catches typos)
• a required field is missing or empty
• a scalar type is wrong (e.g., string for a boolean)
• an options value isn't in the allowed list

When a spec carries an llm_hint, the hint is appended to the error message so an LLM agent can self-correct on retry:

tool_uuids: expected tool_refs, got str
  Hint: List of tool UUIDs from `list_tools`.

Server-side Pydantic validators run on save and surface anything the SDK lets through (compound invariants, cross-field rules).

Environment

FORA_API_URL=http://localhost:8000   # default (legacy DOGRAH_API_URL also accepted)
FORA_API_KEY=sk-...                  # sent as X-API-Key (legacy DOGRAH_API_KEY also accepted)

License

BSD 2-Clause — see LICENSE.