terse-sdk 0.1.0__tar.gz

terse_sdk-0.1.0/.gitignore

@@ -0,0 +1,30 @@
+/node_modules
+/backend/node_modules
+/backend/dist
+/packages/terse-sdk/node_modules
+/packages/terse-sdk/dist
+/packages/terse-sdk/src/shared
+/packages/terse-cli/node_modules
+/packages/terse-cli/dist
+.pnpm-store/
+
+# Python SDK artifacts
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.tox/
+.coverage
+.coverage.*
+htmlcov/
+.venv/
+venv/
+*.egg-info/
+pip-wheel-metadata/
+/packages/terse-python-sdk/build/
+/packages/terse-python-sdk/dist/
+/packages/terse-python-sdk/shared/
+/packages/terse-python-cli/build/
+/packages/terse-python-cli/dist/
+/packages/terse-python-cli/shared/

terse_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,135 @@
+Metadata-Version: 2.4
+Name: terse-sdk
+Version: 0.1.0
+Summary: Python SDK for building jobs on the Terse platform.
+Project-URL: Homepage, https://useterse.ai
+Author: Terse
+Keywords: agents,ai,automation,sdk,terse
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: httpx-sse<0.5,>=0.4
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: pydantic-settings>=2.13.1
+Requires-Dist: pydantic>=2.12.5
+Description-Content-Type: text/markdown
+
+# terse-sdk
+
+Python SDK for building jobs on the [Terse](https://useterse.ai) platform.
+
+Most users should start with `terse-cli`, which scaffolds a project and generates `terse_generated.py` helpers for the currently supported trigger and skill surface.
+
+## Installation
+
+```bash
+python -m pip install terse-sdk
+```
+
+## Runtime API
+
+The SDK provides:
+
+- `Terse` for runtime job registration
+- `@app.job(...)` for declaring jobs
+- `TerseAgent` for agent runs and deterministic tool execution
+- typed event models such as `CronJobInputEvent`
+- generated backend models under `terse_sdk.generated.models`
+
+## Quick Start
+
+```python
+from terse_sdk import CronJobInputEvent, EventType, Terse, TerseAgent
+
+app = Terse()
+
+@app.job(
+    name="example-job",
+    triggers=[],
+    skills=[],
+)
+def example(event: CronJobInputEvent, agent: TerseAgent) -> None:
+    for stream_event in agent.run(
+        "Answer with one short, cute sentence about this cron job.",
+        event,
+    ):
+        if stream_event.type == EventType.FINAL_OUTPUT:
+            print(stream_event.finalOutput)
+
+example(
+    CronJobInputEvent(
+        event_type="manual",
+        formatted_content="Manual local run",
+        debug_log="README example",
+    ),
+    TerseAgent(),
+)
+```
+
+That example is intentionally self-contained. In a real Terse project, trigger and skill configs normally come from the generated helpers in `terse_generated.py`, not from manually constructing low-level DTOs.
+
+## Generated Helpers
+
+The SDK package does not generate project helpers by itself.
+
+If you scaffold a project with `terse init` and then run `terse generate`, your project gets `src/terse_generated.py` with the currently supported helpers:
+
+- `Schedule.cron(...)`
+- `Attio.skill(...)`
+- `Snowflake.skill(...)`
+- deterministic wrappers on `agent.tools.attio` and `agent.tools.snowflake`
+
+Example inside a generated project:
+
+```python
+from terse_generated import Schedule, Snowflake, TerseAgent
+from terse_sdk import CronJobInputEvent, Terse
+
+app = Terse()
+
+@app.job(
+    name="snowflake-job",
+    triggers=[Schedule.cron("0 9 * * 1")],
+    skills=[Snowflake.skill()],
+)
+def example(event: CronJobInputEvent, agent: TerseAgent) -> None:
+    result = agent.tools.snowflake.execute_query(query="select current_date()")
+    print(result)
+```
+
+## Environment Variables
+
+- `TERSE_API_KEY`: required for agent runs and deterministic tool execution
+- `TERSE_BACKEND_URL`: optional backend override for local development
+- `TERSE_FRONTEND_URL`: optional frontend override for local development
+
+## Recommended Path
+
+If you want the full project workflow, install the CLI instead:
+
+```bash
+python -m pip install terse-cli
+terse init my-terse-job
+```
+
+## Source
+
+- Homepage: [useterse.ai](https://useterse.ai)
+- Repository: [github.com/TerseAI/Terse](https://github.com/TerseAI/Terse)
+- Issues: [github.com/TerseAI/Terse/issues](https://github.com/TerseAI/Terse/issues)
+
+## Development
+
+If you are working on the SDK itself from the monorepo:
+
+```bash
+npm run python:setup
+npm run python:check
+npm run python:build
+```

terse_sdk-0.1.0/README.md

@@ -0,0 +1,113 @@
+# terse-sdk
+
+Python SDK for building jobs on the [Terse](https://useterse.ai) platform.
+
+Most users should start with `terse-cli`, which scaffolds a project and generates `terse_generated.py` helpers for the currently supported trigger and skill surface.
+
+## Installation
+
+```bash
+python -m pip install terse-sdk
+```
+
+## Runtime API
+
+The SDK provides:
+
+- `Terse` for runtime job registration
+- `@app.job(...)` for declaring jobs
+- `TerseAgent` for agent runs and deterministic tool execution
+- typed event models such as `CronJobInputEvent`
+- generated backend models under `terse_sdk.generated.models`
+
+## Quick Start
+
+```python
+from terse_sdk import CronJobInputEvent, EventType, Terse, TerseAgent
+
+app = Terse()
+
+@app.job(
+    name="example-job",
+    triggers=[],
+    skills=[],
+)
+def example(event: CronJobInputEvent, agent: TerseAgent) -> None:
+    for stream_event in agent.run(
+        "Answer with one short, cute sentence about this cron job.",
+        event,
+    ):
+        if stream_event.type == EventType.FINAL_OUTPUT:
+            print(stream_event.finalOutput)
+
+example(
+    CronJobInputEvent(
+        event_type="manual",
+        formatted_content="Manual local run",
+        debug_log="README example",
+    ),
+    TerseAgent(),
+)
+```
+
+That example is intentionally self-contained. In a real Terse project, trigger and skill configs normally come from the generated helpers in `terse_generated.py`, not from manually constructing low-level DTOs.
+
+## Generated Helpers
+
+The SDK package does not generate project helpers by itself.
+
+If you scaffold a project with `terse init` and then run `terse generate`, your project gets `src/terse_generated.py` with the currently supported helpers:
+
+- `Schedule.cron(...)`
+- `Attio.skill(...)`
+- `Snowflake.skill(...)`
+- deterministic wrappers on `agent.tools.attio` and `agent.tools.snowflake`
+
+Example inside a generated project:
+
+```python
+from terse_generated import Schedule, Snowflake, TerseAgent
+from terse_sdk import CronJobInputEvent, Terse
+
+app = Terse()
+
+@app.job(
+    name="snowflake-job",
+    triggers=[Schedule.cron("0 9 * * 1")],
+    skills=[Snowflake.skill()],
+)
+def example(event: CronJobInputEvent, agent: TerseAgent) -> None:
+    result = agent.tools.snowflake.execute_query(query="select current_date()")
+    print(result)
+```
+
+## Environment Variables
+
+- `TERSE_API_KEY`: required for agent runs and deterministic tool execution
+- `TERSE_BACKEND_URL`: optional backend override for local development
+- `TERSE_FRONTEND_URL`: optional frontend override for local development
+
+## Recommended Path
+
+If you want the full project workflow, install the CLI instead:
+
+```bash
+python -m pip install terse-cli
+terse init my-terse-job
+```
+
+## Source
+
+- Homepage: [useterse.ai](https://useterse.ai)
+- Repository: [github.com/TerseAI/Terse](https://github.com/TerseAI/Terse)
+- Issues: [github.com/TerseAI/Terse/issues](https://github.com/TerseAI/Terse/issues)
+
+## Development
+
+If you are working on the SDK itself from the monorepo:
+
+```bash
+npm run python:setup
+npm run python:check
+npm run python:build
+```

terse_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[project]
+name = "terse-sdk"
+version = "0.1.0"
+description = "Python SDK for building jobs on the Terse platform."
+readme = "README.md"
+requires-python = ">=3.11"
+authors = [{ name = "Terse" }]
+keywords = ["terse", "ai", "agents", "automation", "sdk"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "httpx>=0.28.1",
+    "httpx-sse>=0.4,<0.5",
+    "pydantic>=2.12.5",
+    "pydantic-settings>=2.13.1",
+]
+
+[project.urls]
+Homepage = "https://useterse.ai"
+
+[build-system]
+requires = ["hatchling>=1.29.0"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/terse_sdk"]

terse_sdk-0.1.0/shared/ApiRoutes.ts

@@ -0,0 +1,350 @@
+/**
+ * API route path constants
+ *
+ * These constants standardize API route paths across frontend and backend,
+ * preventing magic strings and making refactoring easier.
+ *
+ * Dynamic routes use route objects with both Express patterns and URL builders
+ * to ensure frontend and backend stay in sync.
+ */
+
+// Type definitions for route objects
+
+export const ApiRoutes = {
+    // Authentication routes
+    AUTH: {
+        ME: "/me",
+        LOGIN: "/login",
+        LOGIN_URL: "/login/url",
+        LOGOUT: "/logout",
+        LOGOUT_URL: "/logout/url",
+        GITHUB_APP_CALLBACK: "/auth/github-app/callback",
+        WORKOS_CALLBACK: "/auth/workos/callback"
+    },
+
+    WORKOS: {
+        WIDGET_TOKEN: "/auth/workos/widget-token"
+    },
+
+    ORGANIZATIONS: {
+        CREATE: "/organizations",
+        GET_CURRENT: "/organizations/current",
+        LIST: "/organizations",
+        SWITCH: "/organizations/switch",
+        UPDATE: "/organizations",
+        LOGO_UPLOAD_URL: "/organizations/logo/upload-url",
+        LOGO: {
+            pattern: "/organizations/:organizationId/logo",
+            build: (organizationId: string) => `/organizations/${encodeURIComponent(organizationId)}/logo`,
+            params: { organizationId: "string" } as const
+        }
+    },
+
+    // Stats routes
+    STATS: "/stats",
+
+    // Run history routes
+    RUN_HISTORY: {
+        ALL: "/run-history",
+        ACTIONS: "/run-history/actions",
+        BY_AGENT_ID: {
+            pattern: "/run-history/:agentId",
+            build: (agentId: string) => `/run-history/${encodeURIComponent(agentId)}`,
+            params: { agentId: "string" } as const
+        },
+        CHAT_BY_RUN_ID: {
+            pattern: "/run-history/:runId/chat",
+            build: (runId: string) => `/run-history/${encodeURIComponent(runId)}/chat`,
+            params: { runId: "string" } as const
+        }
+    },
+
+    // Session routes
+    SESSION: {
+        TOKEN: "/session/token"
+    },
+
+    // GitHub routes
+    GITHUB: {
+        INTEGRATIONS: "/github/integrations",
+        INSTALLATION_URL: "/github/installation-url",
+        GET_REPOSITORIES_FOR_INTEGRATION: "/github/get-repositories-for-integration",
+        INSTALLATION_CALLBACK: "/github/installation-callback",
+        INSTALLATION_DELETED: "/github/installation-deleted",
+        UNIFIED_EVENT: "/github/unified-event"
+    },
+
+    // Atlassian/Jira routes
+    ATLASSIAN: {
+        INTEGRATIONS: "/atlassian/integrations",
+        OAUTH_CALLBACK: "/atlassian/oauth/callback"
+    },
+
+    JIRA: {
+        RESOURCES: "/jira/resources",
+        GET_API_KEY: "/jira/get-api-key",
+        SET_API_KEY: "/jira/set-api-key",
+        VALIDATE_AND_FETCH_PROJECTS: "/jira/validate-and-fetch-projects",
+        DELETE_CREDENTIALS: "/jira/delete-credentials"
+    },
+
+    // Confluence routes
+    CONFLUENCE: {
+        INTEGRATIONS: "/confluence/integrations",
+        RESOURCES: "/confluence/resources"
+    },
+
+    // Gmail routes
+    GMAIL: {
+        INTEGRATIONS: "/gmail/integrations",
+        CALLBACK: "/gmail/callback",
+        DELETE_INTEGRATION: "/gmail/delete-integration"
+    },
+
+    // Notion routes
+    NOTION: {
+        INTEGRATIONS: "/notion/integrations",
+        OAUTH_CALLBACK: "/notion/oauth/callback",
+        RESOURCES: "/notion/resources",
+        DELETE_INTEGRATION: "/notion/delete-integration"
+    },
+
+    // Figma routes
+    FIGMA: {
+        INTEGRATIONS: "/figma/integrations",
+        OAUTH_CALLBACK: "/figma/oauth/callback"
+    },
+
+    // Linear routes
+    LINEAR: {
+        OAUTH_CALLBACK: "/linear/oauth/callback",
+        WEBHOOK: "/linear/webhook",
+        INTEGRATIONS: "/linear/integrations",
+        TEAMS: "/linear/teams"
+    },
+
+    // Slack routes
+    SLACK: {
+        INTEGRATIONS: "/slack/integrations",
+        GET_CURRENT_INTEGRATION: "/slack/get-current-integration",
+        OAUTH_CALLBACK: "/slack/oauth-callback",
+        CHANNELS: "/slack/channels",
+        USERS: "/slack/users",
+        EVENTS: "/slack/events"
+    },
+
+    // Posthog routes
+    POSTHOG: {
+        INTEGRATIONS: "/posthog/integrations",
+        PROJECTS: "/posthog/projects"
+    },
+
+    // LaunchDarkly routes
+    LAUNCHDARKLY: {
+        INTEGRATIONS: "/launchdarkly/integrations",
+        PROJECTS_BY_INTEGRATION_ID: {
+            pattern: "/launchdarkly/integrations/:integrationId/projects",
+            build: (integrationId: string) => `/launchdarkly/integrations/${encodeURIComponent(integrationId)}/projects`,
+            params: { integrationId: "string" } as const
+        },
+        ENVIRONMENTS_BY_INTEGRATION_AND_PROJECT: {
+            pattern: "/launchdarkly/integrations/:integrationId/projects/:projectKey/environments",
+            build: (integrationId: string, projectKey: string) => `/launchdarkly/integrations/${encodeURIComponent(integrationId)}/projects/${encodeURIComponent(projectKey)}/environments`,
+            params: { integrationId: "string", projectKey: "string" } as const
+        }
+    },
+
+    // Datadog routes
+    DATADOG: {
+        INTEGRATIONS: "/datadog/integrations",
+        INDEXES: "/datadog/indexes"
+    },
+
+    // WorkOS Integration routes (customer's own WorkOS account)
+    WORKOS_INTEGRATION: {
+        INTEGRATIONS: "/workos-integration/integrations",
+        WEBHOOK_SECRET: "/workos-integration/webhook-secret"
+    },
+
+    // Snowflake routes
+    SNOWFLAKE: {
+        INTEGRATIONS: "/snowflake/integrations"
+    },
+
+    // Attio routes
+    ATTIO: {
+        INTEGRATIONS: "/attio/integrations",
+        OAUTH_CALLBACK: "/attio/oauth/callback",
+        OBJECTS: {
+            pattern: "/attio/integrations/:integrationId/objects",
+            build: (integrationId: string) => `/attio/integrations/${encodeURIComponent(integrationId)}/objects`,
+            params: { integrationId: "string" } as const
+        }
+    },
+
+    // Agents routes
+    AGENTS: {
+        LIST: "/agents",
+        RECENT: "/agents/recent",
+        BY_ID: {
+            pattern: "/agents/:id",
+            build: (id: string) => `/agents/${encodeURIComponent(id)}`,
+            params: { id: "string" } as const
+        }
+    },
+
+    IMPROVEMENTS: {
+        BY_AGENT_ID: {
+            pattern: "/agents/:agentId/improvements",
+            build: (agentId: string) => `/agents/${encodeURIComponent(agentId)}/improvements`,
+            params: { agentId: "string" } as const
+        },
+        APPLY: {
+            pattern: "/agents/:agentId/improvements/:id/apply",
+            build: (agentId: string, id: string) => `/agents/${encodeURIComponent(agentId)}/improvements/${encodeURIComponent(id)}/apply`,
+            params: { agentId: "string", id: "string" } as const
+        },
+        DISMISS: {
+            pattern: "/agents/:agentId/improvements/:id/dismiss",
+            build: (agentId: string, id: string) => `/agents/${encodeURIComponent(agentId)}/improvements/${encodeURIComponent(id)}/dismiss`,
+            params: { agentId: "string", id: "string" } as const
+        },
+        UNDO_DISMISS: {
+            pattern: "/agents/:agentId/improvements/:id/undo-dismiss",
+            build: (agentId: string, id: string) => `/agents/${encodeURIComponent(agentId)}/improvements/${encodeURIComponent(id)}/undo-dismiss`,
+            params: { agentId: "string", id: "string" } as const
+        },
+        TOGGLE_ENABLED: {
+            pattern: "/agents/:agentId/improvements-enabled",
+            build: (agentId: string) => `/agents/${encodeURIComponent(agentId)}/improvements-enabled`,
+            params: { agentId: "string" } as const
+        }
+    },
+
+    // Templates routes
+    TEMPLATES: "/templates",
+    PUBLIC: {
+        TEMPLATES: "/public/templates"
+    },
+
+    // Tools routes
+    TOOLS: {
+        THAT_REQUIRE_APPROVALS: "/tools/that-require-approvals"
+    },
+
+    // Integrations routes
+    INTEGRATIONS: {
+        INSTALLATION_DETAILS_BY_TYPE: {
+            pattern: "/integrations/:integrationType/installation-details",
+            build: (integrationType: string) => `/integrations/${encodeURIComponent(integrationType)}/installation-details`,
+            params: { integrationType: "string" } as const
+        },
+        LIST: "/integrations",
+        ACTIVE: "/integrations/active"
+    },
+
+    // Notification destinations routes
+    NOTIFICATION_DESTINATIONS: {
+        LIST: "/notification-destinations",
+        BY_ID: {
+            pattern: "/notification-destinations/:id",
+            build: (id: string) => `/notification-destinations/${encodeURIComponent(id)}`,
+            params: { id: "string" } as const
+        }
+    },
+
+    // API Tokens routes
+    API_TOKENS: {
+        LIST: "/api-tokens",
+        BY_ID: {
+            pattern: "/api-tokens/:id",
+            build: (id: string) => `/api-tokens/${encodeURIComponent(id)}`,
+            params: { id: "string" } as const
+        }
+    },
+
+    // SDK routes (authenticated via API tokens)
+    SDK: {
+        ME: "/sdk/me",
+        SAMPLE_EVENTS: "/sdk/sample-events",
+        TOOL_EXECUTE: "/sdk/tool-execute",
+        TOOL_DEFINITIONS: "/sdk/tool-definitions",
+        AGENT_RUN: "/sdk/agent-run",
+        SESSION_EVENTS: "/sdk/session-events",
+        DEPLOY: "/sdk/deploy"
+    },
+
+    NOTIFICATION_SETTINGS: "/notification-settings",
+
+    SENT_NOTIFICATIONS: {
+        LIST: "/sent-notifications"
+    },
+
+    PENDING_APPROVALS: {
+        LIST: "/pending-approvals"
+    },
+
+    // Webhooks routes
+    WEBHOOKS: {
+        GMAIL: "/webhooks/gmail",
+        FIGMA: "/webhooks/figma",
+        WORKOS: "/webhooks/workos",
+        JIRA_BY_ACCOUNT_ID: {
+            pattern: "/webhooks/jira/:accountId",
+            build: (accountId: string) => `/webhooks/jira/${encodeURIComponent(accountId)}`,
+            params: { accountId: "string" } as const
+        },
+        LINEAR_BY_USER_ID: {
+            pattern: "/webhooks/linear/:userId",
+            build: (userId: string) => `/webhooks/linear/${encodeURIComponent(userId)}`,
+            params: { userId: "string" } as const
+        },
+        SCHEDULE_BY_INPUT_ID: {
+            pattern: "/webhooks/schedule/:inputId",
+            build: (inputId: string) => `/webhooks/schedule/${encodeURIComponent(inputId)}`,
+            params: { inputId: "string" } as const
+        },
+        WORKOS_TRIGGER_BY_INTEGRATION_ID: {
+            pattern: "/webhooks/workos-trigger/:integrationId",
+            build: (integrationId: string) => `/webhooks/workos-trigger/${encodeURIComponent(integrationId)}`,
+            params: { integrationId: "string" } as const
+        }
+    },
+
+    // Schedule routes
+    SCHEDULE: {
+        TRIGGER_BY_INPUT_ID: {
+            pattern: "/schedule/trigger/:inputId",
+            build: (inputId: string) => `/schedule/trigger/${encodeURIComponent(inputId)}`,
+            params: { inputId: "string" } as const
+        },
+        TRIGGER_WITH_EVENT: {
+            pattern: "/schedule/trigger-with-event/:automationId",
+            build: (automationId: string) => `/schedule/trigger-with-event/${encodeURIComponent(automationId)}`,
+            params: { automationId: "string" } as const
+        }
+    },
+
+    // Refresh tokens route
+    REFRESH_TOKENS: "/refresh-tokens",
+    REVIEW_AGENTS: "/review-agents",
+
+    // Users routes
+    USERS: {
+        CREATE: "/users",
+        BY_ID: {
+            pattern: "/users/:id",
+            build: (id: string) => `/users/${encodeURIComponent(id)}`,
+            params: { id: "string" } as const
+        }
+    },
+
+    // Builder chat routes
+    BUILDER_CHAT: {
+        HISTORY_BY_SESSION_ID: {
+            pattern: "/builder-chat/:sessionId/history",
+            build: (sessionId: string) => `/builder-chat/${encodeURIComponent(sessionId)}/history`,
+            params: { sessionId: "string" } as const
+        }
+    }
+} as const

terse_sdk-0.1.0/shared/ApprovalTypes.ts

@@ -0,0 +1,36 @@
+import { IntegrationType } from "./Integrations"
+
+export type ApprovalActionType = "open_run_history" | "approve_action" | "reject_action"
+export type ApprovalRequestStatus = "pending" | "in_progress" | "completed"
+export type ApprovalRequestFilter = ApprovalRequestStatus | "all"
+
+export type ApprovalAction = {
+    type: ApprovalActionType
+    label: string
+    deepLink: string
+}
+
+export type ApprovalRequest = {
+    id: string
+    icon: IntegrationType
+    title: string
+    subheader: string
+    timestamp: string
+    status: ApprovalRequestStatus
+    actions: ApprovalAction[]
+    runId: string
+    agentId: string
+}
+
+export type GetPendingApprovalsResponse = {
+    items: ApprovalRequest[]
+}
+
+export function parseDeepLink(deepLink: string): { type: string; params: string[] } {
+    const parts = deepLink.split("|")
+    return { type: parts[0], params: parts.slice(1) }
+}
+
+export function encodeDeepLink(type: ApprovalActionType, ...params: string[]): string {
+    return [type, ...params].join("|")
+}