fora-sdk 0.1.7__tar.gz

fora_sdk-0.1.7/.gitignore

@@ -0,0 +1,3 @@
+dist/
+build/
+*.egg-info/

fora_sdk-0.1.7/LICENSE

@@ -0,0 +1,24 @@
+BSD 2-Clause License
+
+Copyright (c) 2025, Zansat Technologies Private Limited
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

fora_sdk-0.1.7/PKG-INFO

@@ -0,0 +1,103 @@
+Metadata-Version: 2.4
+Name: fora-sdk
+Version: 0.1.7
+Summary: Typed builder for Fora voice-AI workflows
+Project-URL: Homepage, https://github.com/Phoraapp/fora
+Project-URL: Repository, https://github.com/Phoraapp/fora
+Author-email: Phoraapp <phoraapp@gmail.com>
+License: BSD-2-Clause
+License-File: LICENSE
+Keywords: agent,fora,llm,sdk,voice-ai,workflow
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# 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
+
+```bash
+pip install fora-sdk
+```
+
+For local development against a checked-out monorepo:
+
+```bash
+pip install -e sdk/python/
+```
+
+## Usage
+
+```python
+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
+
+```bash
+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`.

fora_sdk-0.1.7/README.md

@@ -0,0 +1,77 @@
+# 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
+
+```bash
+pip install fora-sdk
+```
+
+For local development against a checked-out monorepo:
+
+```bash
+pip install -e sdk/python/
+```
+
+## Usage
+
+```python
+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
+
+```bash
+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`.

fora_sdk-0.1.7/pyproject.toml

@@ -0,0 +1,48 @@
+[project]
+name = "fora-sdk"
+version = "0.1.7"
+description = "Typed builder for Fora voice-AI workflows"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "BSD-2-Clause" }
+authors = [
+    { name = "Phoraapp", email = "phoraapp@gmail.com" },
+]
+keywords = ["fora", "voice-ai", "workflow", "sdk", "llm", "agent"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: BSD License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries",
+]
+dependencies = [
+    "httpx>=0.27",
+    "pydantic>=2.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/Phoraapp/fora"
+Repository = "https://github.com/Phoraapp/fora"
+
+[project.scripts]
+fora-sdk-codegen = "fora_sdk.codegen:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/fora_sdk"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

fora_sdk-0.1.7/src/fora_sdk/__init__.py

@@ -0,0 +1,35 @@
+"""Fora SDK — typed builder for voice-AI workflows.
+
+Runtime SDK: fetches the spec catalog from the Fora backend at session
+start and validates every `Workflow.add()` call against it. LLMs don't
+need to import per-node-type classes — the `type` argument is a string
+keyed against the fetched spec catalog.
+
+    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="...")
+        qualify = wf.add(type="agentNode", name="qualify", prompt="...")
+        wf.edge(start, qualify, label="interested", condition="...")
+        client.save_workflow(workflow_id=123, workflow=wf)
+
+For typed IDE autocomplete, generate per-node dataclasses via the SDK
+codegen (Phase 6) — the runtime and typed SDKs share this same core.
+"""
+
+from .client import ForaClient
+from .errors import ApiError, ForaSdkError, SpecMismatchError, ValidationError
+from .typed._base import TypedNode
+from .workflow import NodeRef, Workflow
+
+__all__ = [
+    "ApiError",
+    "ForaClient",
+    "ForaSdkError",
+    "NodeRef",
+    "SpecMismatchError",
+    "TypedNode",
+    "ValidationError",
+    "Workflow",
+]

fora_sdk-0.1.7/src/fora_sdk/_generated_client.py

@@ -0,0 +1,114 @@
+"""GENERATED — do not edit. Source: filtered OpenAPI from `api.app`.
+
+Regenerate with `./scripts/generate_sdk.sh`.
+
+`ForaClient` mixes in this class to get HTTP methods for every route
+decorated with `sdk_expose(...)` on the backend. Request/response types
+come from `_generated_models` (datamodel-codegen output).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from fora_sdk._generated_models import (
+    CreateToolRequest,
+    CreateWorkflowRequest,
+    CredentialResponse,
+    DocumentListResponseSchema,
+    InitiateCallRequest,
+    NodeSpec,
+    NodeTypesResponse,
+    RecordingListResponseSchema,
+    ToolResponse,
+    UpdateWorkflowRequest,
+    WorkflowListResponse,
+    WorkflowResponse,
+)
+
+
+class _GeneratedClient:
+    # `ForaClient.__init__` installs `self._request` (see client.py).
+
+    def create_tool(self, *, body: CreateToolRequest) -> ToolResponse:
+        """Create a reusable tool for the authenticated organization."""
+        data = self._request("POST", "/tools/", json=body.model_dump(mode="json", exclude_none=True))
+        return ToolResponse.model_validate(data)
+
+    def create_workflow(self, *, body: CreateWorkflowRequest) -> WorkflowResponse:
+        """Create a new workflow from a workflow definition."""
+        data = self._request("POST", "/workflow/create/definition", json=body.model_dump(mode="json", exclude_none=True))
+        return WorkflowResponse.model_validate(data)
+
+    def get_node_type(self, name: str) -> NodeSpec:
+        """Fetch a single node spec by name."""
+        data = self._request("GET", f"/node-types/{name}")
+        return NodeSpec.model_validate(data)
+
+    def get_workflow(self, workflow_id: int) -> WorkflowResponse:
+        """Get a single workflow by ID (returns draft if one exists, else published)."""
+        data = self._request("GET", f"/workflow/fetch/{workflow_id}")
+        return WorkflowResponse.model_validate(data)
+
+    def list_credentials(self) -> list[CredentialResponse]:
+        """List webhook credentials available to the authenticated organization."""
+        data = self._request("GET", "/credentials/")
+        return [CredentialResponse.model_validate(x) for x in data]
+
+    def list_documents(self, *, status: str | None = None, limit: int | None = None, offset: int | None = None) -> DocumentListResponseSchema:
+        """List knowledge base documents available to the authenticated organization."""
+        params: dict[str, Any] = {}
+        if status is not None:
+            params["status"] = status
+        if limit is not None:
+            params["limit"] = limit
+        if offset is not None:
+            params["offset"] = offset
+        data = self._request("GET", "/knowledge-base/documents", params=params)
+        return DocumentListResponseSchema.model_validate(data)
+
+    def list_node_types(self) -> NodeTypesResponse:
+        """List every registered node type with its spec. Pinned to spec_version."""
+        data = self._request("GET", "/node-types")
+        return NodeTypesResponse.model_validate(data)
+
+    def list_recordings(self, *, workflow_id: int | None = None, tts_provider: str | None = None, tts_model: str | None = None, tts_voice_id: str | None = None) -> RecordingListResponseSchema:
+        """List workflow recordings available to the authenticated organization."""
+        params: dict[str, Any] = {}
+        if workflow_id is not None:
+            params["workflow_id"] = workflow_id
+        if tts_provider is not None:
+            params["tts_provider"] = tts_provider
+        if tts_model is not None:
+            params["tts_model"] = tts_model
+        if tts_voice_id is not None:
+            params["tts_voice_id"] = tts_voice_id
+        data = self._request("GET", "/workflow-recordings/", params=params)
+        return RecordingListResponseSchema.model_validate(data)
+
+    def list_tools(self, *, status: str | None = None, category: str | None = None) -> list[ToolResponse]:
+        """List tools available to the authenticated organization."""
+        params: dict[str, Any] = {}
+        if status is not None:
+            params["status"] = status
+        if category is not None:
+            params["category"] = category
+        data = self._request("GET", "/tools/", params=params)
+        return [ToolResponse.model_validate(x) for x in data]
+
+    def list_workflows(self, *, status: str | None = None) -> list[WorkflowListResponse]:
+        """List all workflows in the authenticated organization."""
+        params: dict[str, Any] = {}
+        if status is not None:
+            params["status"] = status
+        data = self._request("GET", "/workflow/fetch", params=params)
+        return [WorkflowListResponse.model_validate(x) for x in data]
+
+    def test_phone_call(self, *, body: InitiateCallRequest) -> Any:
+        """Place a test call from a workflow to a phone number."""
+        return self._request("POST", "/telephony/initiate-call", json=body.model_dump(mode="json", exclude_none=True))
+
+    def update_workflow(self, workflow_id: int, *, body: UpdateWorkflowRequest) -> WorkflowResponse:
+        """Update a workflow's name and/or definition. Saves as a new draft."""
+        data = self._request("PUT", f"/workflow/{workflow_id}", json=body.model_dump(mode="json", exclude_none=True))
+        return WorkflowResponse.model_validate(data)