terse-cli 0.1.16 → 0.1.18

package/templates/python/codegen/partials/deterministic-tools-section.hbs

@@ -0,0 +1,308 @@
+
+
+# === Deterministic tools ===
+
+{{#if hasAttioTools}}
+_ATTIO_FILTER_ATTRS_BY_OBJECT: dict[str, frozenset[str]] = {
+{{#each attio.objects}}
+{{#if hasAttributes}}
+    {{{apiSlugRepr}}}: {{{attrSlugsFrozensetRepr}}},
+{{/if}}
+{{/each}}
+}
+
+
+def _attio_invalid_filter_error(obj_slug: str, attribute: str | None = None) -> ValueError:
+    message = f"Invalid Attio filter for object {obj_slug!r}"
+    if attribute is not None:
+        message += f" on attribute {attribute!r}"
+    message += ": list shorthand is not supported."
+    if attribute == 'domains':
+        message += ' Use scalar shorthand "useterse.ai" or explicit Attio syntax {"domain": {"$eq": "useterse.ai"}}.'
+    else:
+        message += " Use a scalar shorthand or explicit Attio operator/object syntax instead."
+    return ValueError(message)
+
+
+def _validate_attio_filter_node(
+    obj_slug: str,
+    value: object,
+    *,
+    attr_slugs: frozenset[str],
+    current_attribute: str | None = None,
+) -> None:
+    if isinstance(value, dict):
+        for raw_key, child in value.items():
+            if not isinstance(raw_key, str):
+                raise ValueError(f"Invalid Attio filter for object {obj_slug!r}: filter keys must be strings.")
+            key = raw_key
+            if key in ('$and', '$or'):
+                if not isinstance(child, list):
+                    raise ValueError(f"Invalid Attio filter for object {obj_slug!r}: {key} must be a list.")
+                for item in child:
+                    if not isinstance(item, dict):
+                        raise ValueError(f"Invalid Attio filter for object {obj_slug!r}: {key} entries must be objects.")
+                    _validate_attio_filter_node(obj_slug, item, attr_slugs=attr_slugs)
+                continue
+            if key == '$not':
+                if not isinstance(child, dict):
+                    raise ValueError(f"Invalid Attio filter for object {obj_slug!r}: $not must be an object.")
+                _validate_attio_filter_node(obj_slug, child, attr_slugs=attr_slugs)
+                continue
+            if key == '$in':
+                if not isinstance(child, list):
+                    raise ValueError(f"Invalid Attio filter for object {obj_slug!r}: $in must be a list.")
+                continue
+            if key == 'path':
+                if not isinstance(child, list):
+                    raise ValueError(f"Invalid Attio filter for object {obj_slug!r}: path must be a list.")
+                continue
+            if key == 'constraints':
+                if not isinstance(child, dict):
+                    raise ValueError(f"Invalid Attio filter for object {obj_slug!r}: constraints must be an object.")
+                _validate_attio_filter_node(
+                    obj_slug,
+                    child,
+                    attr_slugs=attr_slugs,
+                    current_attribute=current_attribute,
+                )
+                continue
+
+            attribute: str | None = key if key in attr_slugs else current_attribute
+            if isinstance(child, list):
+                raise _attio_invalid_filter_error(obj_slug, attribute)
+            _validate_attio_filter_node(
+                obj_slug,
+                child,
+                attr_slugs=attr_slugs,
+                current_attribute=attribute,
+            )
+
+
+def _serialize_attio_filter(obj_slug: str, value: object | None) -> str | None:
+    if value is None:
+        return None
+
+    parsed = value
+    if isinstance(value, str):
+        try:
+            parsed = json.loads(value)
+        except json.JSONDecodeError as exc:
+            raise ValueError(f"Attio filters for object {obj_slug!r} must be valid JSON objects.") from exc
+
+    if not isinstance(parsed, dict):
+        raise ValueError(f"Attio filters for object {obj_slug!r} must be objects.")
+
+    _validate_attio_filter_node(
+        obj_slug,
+        parsed,
+        attr_slugs=_ATTIO_FILTER_ATTRS_BY_OBJECT.get(obj_slug, frozenset()),
+    )
+    return json.dumps(parsed, separators=(',', ':'), sort_keys=True)
+
+
+def _serialize_attio_records(records: Sequence[object]) -> str:
+    return json.dumps(records, separators=(',', ':'), sort_keys=True)
+
+
+class _AttioTools:
+    def __init__(self, agent: _SdkTerseAgent) -> None:
+        self._agent = agent
+{{#each attio.tools}}
+{{#if (eq name "attio_list_objects")}}{{> attio-list-objects-method tool=this attio=../attio}}{{/if}}
+{{#if (eq name "attio_query_records")}}{{> attio-query-records-method tool=this attio=../attio}}{{/if}}
+{{#if (eq name "attio_upsert_record")}}{{> attio-upsert-record-method tool=this attio=../attio}}{{/if}}
+{{/each}}
+{{/if}}
+{{#if hasSlackTools}}
+
+def _normalize_slack_channel_id(channel: object) -> str:
+    if hasattr(channel, 'channel_id'):
+        return str(getattr(channel, 'channel_id'))
+    return str(channel)
+
+
+def _serialize_slack_blocks(blocks: object | None) -> str | None:
+    if blocks is None:
+        return None
+    if isinstance(blocks, str):
+        return blocks
+    return json.dumps(blocks, separators=(',', ':'))
+
+
+class _SlackTools:
+    def __init__(self, agent: _SdkTerseAgent) -> None:
+        self._agent = agent
+{{#each slack.tools}}
+{{#if (eq name "slack_send_message")}}
+
+    def send_message(
+        self,
+        *,
+        channel: SlackChannel | str,
+        message: str,
+        thread_ts: str | None = None,
+        blocks: object | None = None,
+    ) -> SlackSendMessageToolOutput:
+        return SlackSendMessageToolOutput.model_validate(
+            self._agent.execute_tool(
+                {{{nameRepr}}},
+                _compact_dict(
+                    integrationId={{{../slack.instanceIdRepr}}},
+                    channelId=_normalize_slack_channel_id(channel),
+                    message=message,
+                    thread_ts=thread_ts,
+                    blocks=_serialize_slack_blocks(blocks),
+                ),
+            )
+        )
+{{/if}}
+{{#if (eq name "slack_list_channels")}}
+
+    def list_channels(
+        self,
+        *,
+        types: str | None = None,
+        limit: int | None = None,
+        cursor: str | None = None,
+    ) -> SlackListChannelsToolOutput:
+        return SlackListChannelsToolOutput.model_validate(
+            self._agent.execute_tool(
+                {{{nameRepr}}},
+                _compact_dict(
+                    integrationId={{{../slack.instanceIdRepr}}},
+                    types=types,
+                    limit=limit,
+                    cursor=cursor,
+                ),
+            )
+        )
+{{/if}}
+{{#if (eq name "slack_list_users")}}
+
+    def list_users(self, *, query: str | None = None) -> SlackListUsersToolOutput:
+        return SlackListUsersToolOutput.model_validate(
+            self._agent.execute_tool(
+                {{{nameRepr}}},
+                _compact_dict(
+                    integrationId={{{../slack.instanceIdRepr}}},
+                    query=query,
+                ),
+            )
+        )
+{{/if}}
+{{#if (eq name "slack_read_conversation")}}
+
+    def read_conversation(
+        self,
+        *,
+        channel: SlackChannel | str,
+        limit: int | None = None,
+        cursor: str | None = None,
+    ) -> SlackReadConversationToolOutput:
+        return SlackReadConversationToolOutput.model_validate(
+            self._agent.execute_tool(
+                {{{nameRepr}}},
+                _compact_dict(
+                    integrationId={{{../slack.instanceIdRepr}}},
+                    channelId=_normalize_slack_channel_id(channel),
+                    limit=limit,
+                    cursor=cursor,
+                ),
+            )
+        )
+{{/if}}
+{{/each}}
+{{/if}}
+{{#if hasSnowflakeTools}}
+
+class _SnowflakeTools:
+    def __init__(self, agent: _SdkTerseAgent) -> None:
+        self._agent = agent
+{{#each snowflake.tools}}
+
+    def {{methodName}}(self, query: str) -> {{outputModel}}:
+        return {{outputModel}}.model_validate(
+            self._agent.execute_tool(
+                {{{nameRepr}}},
+                {'integrationId': {{{../snowflake.instanceIdRepr}}}, 'query': query},
+            )
+        )
+{{/each}}
+{{/if}}
+{{#if hasAnyDeterministicTools}}
+
+class GeneratedTools:
+{{#if hasAttioTools}}
+    attio: _AttioTools
+{{/if}}
+{{#if hasSlackTools}}
+    slack: _SlackTools
+{{/if}}
+{{#if hasSnowflakeTools}}
+    snowflake: _SnowflakeTools
+{{/if}}
+
+    def __init__(
+        self,
+{{#if hasAttioTools}}
+        attio: _AttioTools | None = None,
+{{/if}}
+{{#if hasSlackTools}}
+        slack: _SlackTools | None = None,
+{{/if}}
+{{#if hasSnowflakeTools}}
+        snowflake: _SnowflakeTools | None = None,
+{{/if}}
+    ) -> None:
+{{#if hasAttioTools}}
+        if attio is not None:
+            self.attio = attio
+{{/if}}
+{{#if hasSlackTools}}
+        if slack is not None:
+            self.slack = slack
+{{/if}}
+{{#if hasSnowflakeTools}}
+        if snowflake is not None:
+            self.snowflake = snowflake
+{{/if}}
+{{else}}
+
+class GeneratedTools:
+    pass
+{{/if}}
+
+
+class TerseAgent(_SdkTerseAgent):
+    tools: GeneratedTools
+
+
+def create_tools(agent: _SdkTerseAgent) -> GeneratedTools:
+    manual_tool_configs = getattr(agent, "manual_tool_configs", None) or agent.skills
+    allowed = {config.integration_type for config in manual_tool_configs}
+{{#if hasAnyDeterministicTools}}
+    return GeneratedTools(
+{{#if hasAttioTools}}
+        attio=_AttioTools(agent) if 'attio' in allowed else None,
+{{/if}}
+{{#if hasSlackTools}}
+        slack=_SlackTools(agent) if 'slack' in allowed else None,
+{{/if}}
+{{#if hasSnowflakeTools}}
+        snowflake=_SnowflakeTools(agent) if 'snowflake' in allowed else None,
+{{/if}}
+    )
+{{else}}
+    _ = allowed
+    return GeneratedTools()
+{{/if}}
+
+
+def attach_tools(agent: _SdkTerseAgent) -> GeneratedTools:
+    tools = create_tools(agent)
+    agent.attach_tools(tools)
+    return tools
+
+
+__all__ = {{{exportedNamesRepr}}}

package/templates/python/codegen/partials/file-header.hbs

@@ -0,0 +1,32 @@
+"""
+Generated by `terse generate`. Do not edit manually.
+
+Type checking:
+    uv run ty check src/
+"""
+
+from __future__ import annotations
+{{#if typingImportsLine}}
+
+{{typingImportsLine}}
+{{/if}}
+{{#if pydanticImportsLine}}
+
+{{pydanticImportsLine}}
+{{/if}}
+{{#if needsJsonImport}}
+
+import json
+{{/if}}
+
+from terse_sdk import (
+{{#each sdkImports}}
+    {{this}},
+{{/each}}
+)
+
+
+def _compact_dict(**values: object) -> dict[str, object]:
+    """Drop None values while preserving falsey config values like False and []."""
+
+    return {key: value for key, value in values.items() if value is not None}

package/templates/python/codegen/partials/schedule-section.hbs

@@ -0,0 +1,9 @@
+
+
+# === Schedule ===
+
+
+class Schedule:
+    @staticmethod
+    def cron(expression: str) -> TriggerConfig:
+        return TriggerConfig(integration_id='system', integration_type='cron_job', config_type='time_trigger', config=_compact_dict(cronExpression=expression))

package/templates/python/codegen/partials/slack-section.hbs

@@ -0,0 +1,178 @@
+{{#if slack}}
+
+
+# === Slack ===
+
+
+class SlackChannel(BaseModel):
+    model_config = ConfigDict(frozen=True)
+    channel_id: str
+    name: str
+{{#if slack.channels.length}}
+{{#each slack.channels}}
+    {{staticName}}: ClassVar["SlackChannel"]
+{{/each}}
+
+{{#each slack.channels}}
+SlackChannel.{{staticName}} = SlackChannel(channel_id={{{channelIdRepr}}}, name={{{nameRepr}}})
+{{/each}}
+{{/if}}
+
+
+class Slack:
+    @staticmethod
+    def on_message(channel: SlackChannel, *, user_ids: Sequence[str] | None = None) -> TriggerConfig:
+        return TriggerConfig(
+            integration_id={{{slack.instanceIdRepr}}},
+            integration_type='slack',
+            event_type='message',
+            config_type='slack',
+            config=_compact_dict(
+                channelId=channel.channel_id,
+                channelName=channel.name,
+                listenToUserDms=False,
+                userIds=list(user_ids) if user_ids is not None else None,
+                eventTypes=['message'],
+            ),
+        )
+
+    @staticmethod
+    def on_dm(*, user_ids: Sequence[str] | None = None) -> TriggerConfig:
+        return TriggerConfig(
+            integration_id={{{slack.instanceIdRepr}}},
+            integration_type='slack',
+            event_type='message',
+            config_type='slack',
+            config=_compact_dict(
+                listenToUserDms=True,
+                userIds=list(user_ids) if user_ids is not None else None,
+                eventTypes=['message'],
+            ),
+        )
+
+    @staticmethod
+    def trigger(
+        *,
+        channel: SlackChannel | None = None,
+        listen_to_user_dms: bool | None = None,
+        user_ids: Sequence[str] | None = None,
+        event_types: Sequence[SlackEventType] | None = None,
+    ) -> TriggerConfig:
+        return TriggerConfig(
+            integration_id={{{slack.instanceIdRepr}}},
+            integration_type='slack',
+            config_type='slack',
+            config=_compact_dict(
+                channelId=channel.channel_id if channel is not None else None,
+                channelName=channel.name if channel is not None else None,
+                listenToUserDms=listen_to_user_dms,
+                userIds=list(user_ids) if user_ids is not None else None,
+                eventTypes=list(event_types) if event_types is not None else None,
+            ),
+        )
+
+    @staticmethod
+    def skill(
+        *,
+        channel: SlackChannel | None = None,
+        user_ids: Sequence[str] | None = None,
+        user_names: Sequence[str] | None = None,
+        listen_to_user_dms: bool | None = None,
+    ) -> SkillConfig[{{slack.skillToolType}}]:
+        return SkillConfig(
+            integration_id={{{slack.instanceIdRepr}}},
+            integration_type='slack',
+            config_type='slack_output',
+            config=_compact_dict(
+                channelId=channel.channel_id if channel is not None else None,
+                channelName=channel.name if channel is not None else None,
+                userIds=list(user_ids) if user_ids is not None else None,
+                userNames=list(user_names) if user_names is not None else None,
+                listenToUserDms=listen_to_user_dms,
+            ),
+        )
+{{else}}
+
+
+# === Slack ===
+
+
+class SlackChannel:
+    def __init__(self, channel_id: str, name: str) -> None:
+        self.channel_id = channel_id
+        self.name = name
+
+
+class Slack:
+    @staticmethod
+    def on_message(channel: SlackChannel, *, user_ids: list[str] | None = None) -> TriggerConfig:
+        return TriggerConfig(
+            integration_id='slack_placeholder',
+            integration_type='slack',
+            event_type='message',
+            config_type='slack',
+            config=_compact_dict(
+                channelId=channel.channel_id,
+                channelName=channel.name,
+                listenToUserDms=False,
+                userIds=list(user_ids) if user_ids is not None else None,
+                eventTypes=['message'],
+            ),
+        )
+
+    @staticmethod
+    def on_dm(*, user_ids: list[str] | None = None) -> TriggerConfig:
+        return TriggerConfig(
+            integration_id='slack_placeholder',
+            integration_type='slack',
+            event_type='message',
+            config_type='slack',
+            config=_compact_dict(
+                listenToUserDms=True,
+                userIds=list(user_ids) if user_ids is not None else None,
+                eventTypes=['message'],
+            ),
+        )
+
+    @staticmethod
+    def trigger(
+        *,
+        channel: SlackChannel | None = None,
+        listen_to_user_dms: bool | None = None,
+        user_ids: list[str] | None = None,
+        event_types: list[str] | None = None,
+    ) -> TriggerConfig:
+        return TriggerConfig(
+            integration_id='slack_placeholder',
+            integration_type='slack',
+            config_type='slack',
+            config=_compact_dict(
+                channelId=channel.channel_id if channel is not None else None,
+                channelName=channel.name if channel is not None else None,
+                listenToUserDms=listen_to_user_dms,
+                userIds=list(user_ids) if user_ids is not None else None,
+                eventTypes=list(event_types) if event_types is not None else None,
+            ),
+        )
+
+    @staticmethod
+    def skill(
+        *,
+        channel: SlackChannel | None = None,
+        user_ids: list[str] | None = None,
+        user_names: list[str] | None = None,
+        listen_to_user_dms: bool | None = None,
+    ) -> SkillConfig[str]:
+        return SkillConfig(
+            integration_id='slack_placeholder',
+            integration_type='slack',
+            config_type='slack_output',
+            config=_compact_dict(
+                channelId=channel.channel_id if channel is not None else None,
+                channelName=channel.name if channel is not None else None,
+                userIds=list(user_ids) if user_ids is not None else None,
+                userNames=list(user_names) if user_names is not None else None,
+                listenToUserDms=listen_to_user_dms,
+            ),
+        )
+{{/if}}

package/templates/python/codegen/partials/snowflake-section.hbs

@@ -0,0 +1,26 @@
+{{#if snowflake}}
+
+
+# === Snowflake ===
+
+
+class Snowflake:
+    @staticmethod
+    def skill() -> SkillConfig[{{snowflake.skillToolType}}]:
+        return SkillConfig(integration_id={{{snowflake.instanceIdRepr}}}, integration_type='snowflake', config_type='snowflake_output', config=_compact_dict())
+{{else}}
+
+
+# === Snowflake ===
+
+
+class Snowflake:
+    @staticmethod
+    def skill() -> SkillConfig[str]:
+        return SkillConfig(
+            integration_id='snowflake_placeholder',
+            integration_type='snowflake',
+            config_type='snowflake_output',
+            config=_compact_dict(),
+        )
+{{/if}}

package/templates/python/codegen/partials/tool-name-types.hbs

@@ -0,0 +1,18 @@
+{{#if hasAnyToolNameTypes}}
+
+
+# === Tool name types ===
+
+{{#if attioToolNamesLiteral}}
+AttioToolNames = Literal[{{{attioToolNamesLiteral}}}]
+{{/if}}
+{{#if slackToolNamesLiteral}}
+SlackToolNames = Literal[{{{slackToolNamesLiteral}}}]
+{{/if}}
+{{#if snowflakeToolNamesLiteral}}
+SnowflakeToolNames = Literal[{{{snowflakeToolNamesLiteral}}}]
+{{/if}}
+{{#if allToolNamesLiteral}}
+AllToolNames = Literal[{{{allToolNamesLiteral}}}]
+{{/if}}
+{{/if}}

package/templates/python/init/.python-version.hbs

@@ -0,0 +1 @@
+3.11

package/templates/python/init/README.md.hbs

@@ -0,0 +1,40 @@
+# {{projectName}}
+
+Project scaffolded by `terse-cli`.
+
+## Prerequisites
+
+- Python `>=3.11`
+- [`uv`](https://docs.astral.sh/uv/getting-started/installation/) for dependency management and local commands
+
+If `terse init` did not install dependencies automatically, install `uv` and run:
+
+```bash
+uv sync
+```
+
+## Quick Start
+
+```bash
+uv sync
+terse test
+terse deploy
+```
+
+Edit `src/main.py` to register jobs with `@app.job(...)`.
+
+## Generated Helpers
+
+The starter scaffold registers `Attio.skill()` and `Snowflake.skill()` by default.
+
+After you connect Attio, Slack, or Snowflake in Terse, rerun `terse generate` to refresh `src/terse_generated.py` with the real integration IDs, generated resources, and deterministic tool wrappers.
+
+Import helpers like `Attio`, `AttioObject`, `Schedule`, `Slack`, `SlackChannel`, `Snowflake`, and `TerseAgent` from `terse_generated`.
+
+If a job includes the integration in `triggers=` or `skills=`, it can call deterministic wrappers like:
+
+```python
+agent.tools.snowflake.execute_query(query="select 1")
+```
+
+Use `agent.tools.slack.*` for direct deterministic Slack calls. Use `skills=[Slack.skill(...)]` when you want Slack to be visible to the model during `run()` or `run_and_wait()`.

package/templates/python/init/gitignore.hbs

@@ -0,0 +1,3 @@
+.venv
+__pycache__
+.env

package/templates/python/init/pyproject.toml.hbs

@@ -0,0 +1,16 @@
+[project]
+name = "{{projectName}}"
+version = "0.1.0"
+requires-python = ">=3.11"
+dependencies = [
+    "{{sdkDependency}}",
+]
+
+[tool.uv]
+package = false
+
+[dependency-groups]
+dev = ["ty"]
+
+[tool.ty.environment]
+python = ".venv"

package/templates/python/init/src/main.py.hbs

@@ -0,0 +1,21 @@
+from terse_sdk import CronJobInputEvent, SdkAgentStreamEventFinalOutput, Terse
+from terse_generated import Attio, Schedule, Snowflake, TerseAgent
+
+app = Terse()
+
+@app.job(
+    name="{{projectName}}",
+    triggers=[Schedule.cron("0 9 * * 1")],
+    skills=[
+        Attio.skill(),
+        Snowflake.skill(),
+    ],
+)
+def run_job(event: CronJobInputEvent, agent: TerseAgent) -> None:
+    prompt = (
+        "Tell a joke"
+        f"Context: {event.formatted_content}"
+    )
+    for stream_event in agent.run(prompt, event):
+        if isinstance(stream_event, SdkAgentStreamEventFinalOutput):
+            print(stream_event.final_output)

package/templates/typescript/codegen/generated.hbs

@@ -0,0 +1,17 @@
+{{> header}}
+
+{{#if github}}{{> github-section github}}{{/if~}}
+{{#if gmail}}{{> gmail-section gmail}}{{/if~}}
+{{#if slack}}{{> slack-section slack}}{{/if~}}
+{{#if figma}}{{> figma-section figma}}{{/if~}}
+{{#if linear}}{{> linear-section linear}}{{/if~}}
+{{#if atlassian}}{{> atlassian-section atlassian}}{{/if~}}
+{{#if notion}}{{> notion-section notion}}{{/if~}}
+{{#if posthog}}{{> posthog-section posthog}}{{/if~}}
+{{#if datadog}}{{> datadog-section datadog}}{{/if~}}
+{{#if launchdarkly}}{{> launchdarkly-section launchdarkly}}{{/if~}}
+{{#if workos}}{{> workos-section workos}}{{/if~}}
+{{#if attio}}{{> attio-section attio}}{{/if~}}
+{{#if snowflake}}{{> snowflake-section snowflake}}{{/if~}}
+{{#if tools}}{{> tools-section tools}}{{/if}}
+{{> system-section system}}