stigmer-sdk 0.1.0.dev0__py3-none-any.whl

stigmer/__init__.py

@@ -0,0 +1,152 @@
+"""Stigmer Python SDK — typed API client for all Stigmer platform resources.
+
+Usage::
+
+    from stigmer import StigmerClient, AgentInput
+
+    with StigmerClient("sk_live_abc123") as client:
+        agent = client.agents.create(AgentInput(name="my-agent", org="my-org"))
+        print(agent.metadata.name)
+"""
+
+from ._billing import (
+    BillingClient,
+    CreateBillingPortalSessionParams,
+    CreatePaymentMethodSetupSessionParams,
+    RetireModelPricingBaselineParams,
+    UpsertModelPricingBaselineParams,
+)
+from ._client import StigmerClient
+from ._runner_adapter import RunnerAdapter
+from ._github import GitHubClient, GitHubRepoParams
+from ._search import ApiResourceKind, SearchClient, SearchParams, SearchResponse
+from ._tokens import MintUserTokenResult, TokenClient
+
+# --- Resource clients and input types (generated) --------------------------
+
+from ._gen._agent import (
+    AgentClient,
+    AgentInput,
+    AgentMcpServerInput,
+    RunConfigInput,
+)
+from ._gen._apikey import ApiKeyClient, ApiKeyInput
+from ._gen._federationissuer import FederationIssuerClient, FederationIssuerInput
+from ._gen._grant import ApiResourceRefInput, GrantClient, GrantInput
+from ._gen._identityaccount import IdentityAccountClient, IdentityAccountInput
+from ._gen._oauthapp import OAuthAppClient, OAuthAppInput
+from ._gen._organization import OrganizationClient, OrganizationInput
+from ._gen._plugin import PluginClient
+from ._gen._run import (
+    AttachmentInput,
+    RunClient,
+    RunInput,
+)
+from ._gen._session import (
+    GitRepoSourceInput,
+    LocalPathSourceInput,
+    SessionClient,
+    SessionInput,
+    WorkspaceEntryInput,
+    WorkspaceSourceInput,
+)
+from ._gen._skill import SkillClient, SkillInput
+from ._gen._vault import (
+    VaultClient,
+    VaultConnectionInput,
+    VaultConnectionSignInInput,
+    VaultInput,
+    VaultSecretInput,
+)
+from ._skill import MAX_INLINE_ARTIFACT_BYTES, RoutedSkillClient
+
+# --- Shared types (generated) ----------------------------------------------
+
+from ._gen._types import (
+    DeleteResourceInput,
+    ResourceRef,
+)
+
+# --- Error types (generated) -----------------------------------------------
+
+from ._gen._errors import (
+    ErrorCode,
+    StigmerError,
+    is_not_found,
+    is_permission_denied,
+    is_retryable,
+    is_unauthenticated,
+)
+
+
+__all__ = [
+    # Client
+    "StigmerClient",
+    # Runner adapter
+    "RunnerAdapter",
+    # Billing
+    "BillingClient",
+    "CreateBillingPortalSessionParams",
+    "CreatePaymentMethodSetupSessionParams",
+    "RetireModelPricingBaselineParams",
+    "UpsertModelPricingBaselineParams",
+    # GitHub
+    "GitHubClient",
+    "GitHubRepoParams",
+    # Search
+    "ApiResourceKind",
+    "SearchClient",
+    "SearchParams",
+    "SearchResponse",
+    # User tokens
+    "MintUserTokenResult",
+    "TokenClient",
+    # Resource clients
+    "AgentClient",
+    "ApiKeyClient",
+    "FederationIssuerClient",
+    "GrantClient",
+    "IdentityAccountClient",
+    "OAuthAppClient",
+    "OrganizationClient",
+    "PluginClient",
+    "RunClient",
+    "SessionClient",
+    "SkillClient",
+    "VaultClient",
+    "RoutedSkillClient",
+    "MAX_INLINE_ARTIFACT_BYTES",
+    # Input types
+    "AgentInput",
+    "AgentMcpServerInput",
+    "ApiKeyInput",
+    "ApiResourceRefInput",
+    "AttachmentInput",
+    "DeleteResourceInput",
+    "FederationIssuerInput",
+    "GitRepoSourceInput",
+    "GrantInput",
+    "IdentityAccountInput",
+    "LocalPathSourceInput",
+    "OAuthAppInput",
+    "OrganizationInput",
+    "RunInput",
+    "RunConfigInput",
+    "SessionInput",
+    "SkillInput",
+    "VaultConnectionInput",
+    "VaultConnectionSignInInput",
+    "VaultInput",
+    "VaultSecretInput",
+    "WorkspaceEntryInput",
+    "WorkspaceSourceInput",
+    # Shared types
+    "ResourceRef",
+    # Errors
+    "ErrorCode",
+    "StigmerError",
+    "is_not_found",
+    "is_permission_denied",
+    "is_retryable",
+    "is_unauthenticated",
+]

stigmer/_billing.py

@@ -0,0 +1,220 @@
+"""Billing client for the Stigmer SDK."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Iterator
+
+import grpc
+
+from ai.stigmer.billing.v1 import billing_account_pb2
+from ai.stigmer.billing.v1 import command_pb2_grpc
+from ai.stigmer.billing.v1 import io_pb2 as billing_io_pb2
+from ai.stigmer.billing.v1 import model_pricing_baseline_pb2
+from ai.stigmer.billing.v1 import query_pb2_grpc
+
+from ._gen._errors import wrap_error
+
+
+@dataclass
+class CreateBillingPortalSessionParams:
+    """Parameters for creating a Stripe Billing Portal session."""
+
+    org: str
+    return_url: str
+
+
+@dataclass
+class CreatePaymentMethodSetupSessionParams:
+    """Parameters for creating a Stripe Checkout Session that saves a card."""
+
+    org: str
+    success_url: str
+    cancel_url: str
+
+
+@dataclass
+class UpsertModelPricingBaselineParams:
+    """Parameters for creating or revising a model registry baseline entry."""
+
+    baseline: model_pricing_baseline_pb2.ModelPricingBaseline
+    """The baseline entry to create or revise, keyed by
+    (model_id, provider, harness). Lifecycle fields (baseline_id, status,
+    decision stamps, pricing effective_at) are server-owned and ignored."""
+    revision_note: str = ""
+    """Optional operator note recorded on the revision for the audit trail."""
+
+
+@dataclass
+class RetireModelPricingBaselineParams:
+    """Parameters for retiring a model from the registry catalog."""
+
+    model_id: str
+    provider: str
+    harness: str
+    revision_note: str = ""
+    """Optional operator note recorded on the retirement."""
+
+
+class BillingClient:
+    """Billing bounded-context client.
+
+    Wraps the user-facing billing RPCs: the organization's billing account
+    (its Stripe customer), the Stripe portal and card setup sessions, and
+    the operator model-pricing surfaces.  Responses are returned as proto
+    messages — the proto types are the contract.  Token usage is read from
+    the run client's usage reports (``get_run_usage_report``,
+    ``get_session_usage_report``, ``get_agent_usage_report``,
+    ``get_org_usage_report``), counted in tokens and never priced.
+
+    The proxy's metering write (``recordLlmCallUsage``) is not exposed;
+    only the server calls it.
+    """
+
+    def __init__(self, channel: grpc.Channel) -> None:
+        self._command = command_pb2_grpc.BillingCommandControllerStub(channel)
+        self._query = query_pb2_grpc.BillingQueryControllerStub(channel)
+
+    # ── Account ──────────────────────────────────────────────────────────
+
+    def get_or_create_billing_account(
+        self, org: str
+    ) -> billing_account_pb2.BillingAccount:
+        """Provision or retrieve the billing account for an organization.
+
+        Idempotent: creates the account on first call, returns the existing
+        account on subsequent calls.
+        """
+        req = billing_io_pb2.GetOrCreateBillingAccountInput(org=org)
+        try:
+            return self._command.getOrCreateBillingAccount(req)
+        except grpc.RpcError as e:
+            raise wrap_error(e) from e
+
+    def get_billing_account(self, org: str) -> billing_account_pb2.BillingAccount:
+        """Retrieve the billing account for an organization."""
+        req = billing_io_pb2.GetBillingAccountInput(org=org)
+        try:
+            return self._query.getBillingAccount(req)
+        except grpc.RpcError as e:
+            raise wrap_error(e) from e
+
+    # ── Stripe ───────────────────────────────────────────────────────────
+
+    def create_billing_portal_session(
+        self, params: CreateBillingPortalSessionParams
+    ) -> billing_io_pb2.CreateBillingPortalSessionResponse:
+        """Create a Stripe Billing Portal session for payment method management.
+
+        Returns the Stripe-hosted portal URL.  The caller should redirect the
+        user to ``portal_url``; changes are synced back via webhooks.
+        """
+        req = billing_io_pb2.CreateBillingPortalSessionInput(
+            org=params.org,
+            return_url=params.return_url,
+        )
+        try:
+            return self._command.createBillingPortalSession(req)
+        except grpc.RpcError as e:
+            raise wrap_error(e) from e
+
+    def create_payment_method_setup_session(
+        self, params: CreatePaymentMethodSetupSessionParams
+    ) -> billing_io_pb2.CreatePaymentMethodSetupSessionResponse:
+        """Create a Stripe Checkout Session that saves a payment method.
+
+        Returns the Stripe-hosted setup URL.  The caller should redirect the
+        user to ``setup_url``.  This is how an organization puts a card on
+        file for its plan's invoices; nothing is charged.
+        """
+        req = billing_io_pb2.CreatePaymentMethodSetupSessionInput(
+            org=params.org,
+            success_url=params.success_url,
+            cancel_url=params.cancel_url,
+        )
+        try:
+            return self._command.createPaymentMethodSetupSession(req)
+        except grpc.RpcError as e:
+            raise wrap_error(e) from e
+
+    # ── Pricing ──────────────────────────────────────────────────────────
+
+    def list_model_pricing_baselines(
+        self,
+        include_history: bool = False,
+        page_size: int = 0,
+        page_token: str = "",
+    ) -> billing_io_pb2.ModelPricingBaselinesResponse:
+        """Retrieve one page of the model registry baseline catalog.
+
+        ACTIVE entries by default, or the full append-only revision history
+        with ``include_history=True``. ``page_size`` 0 asks for the default
+        page of 50, and above 100 reads 100; pass a response's
+        ``next_page_token`` as ``page_token`` to continue.
+
+        Platform-operator surface (``can_manage_model_pricing`` on
+        ``platform:stigmer``): rates are the providers' list prices.
+        """
+        req = billing_io_pb2.ListModelPricingBaselinesInput(
+            include_history=include_history,
+            page_size=page_size,
+            page_token=page_token,
+        )
+        try:
+            return self._query.listModelPricingBaselines(req)
+        except grpc.RpcError as e:
+            raise wrap_error(e) from e
+
+    def list_model_pricing_baselines_all(
+        self,
+        include_history: bool = False,
+        page_size: int = 0,
+        page_token: str = "",
+    ) -> Iterator[model_pricing_baseline_pb2.ModelPricingBaseline]:
+        """Every baseline of the catalog, page after page: follows
+        ``next_page_token`` from ``page_token`` until the catalog ends."""
+        token = page_token
+        while True:
+            page = self.list_model_pricing_baselines(include_history, page_size, token)
+            yield from page.entries
+            if not page.next_page_token:
+                return
+            token = page.next_page_token
+
+    def upsert_model_pricing_baseline(
+        self, params: UpsertModelPricingBaselineParams
+    ) -> model_pricing_baseline_pb2.ModelPricingBaseline:
+        """Create or revise one model registry baseline entry.
+
+        Append-only: an existing ACTIVE entry for the same
+        (model_id, provider, harness) key is superseded, never mutated, and
+        the registry is rebuilt immediately.  Returns the new
+        revision with server-stamped lifecycle fields.
+        """
+        req = billing_io_pb2.UpsertModelPricingBaselineInput(
+            baseline=params.baseline,
+            revision_note=params.revision_note,
+        )
+        try:
+            return self._command.upsertModelPricingBaseline(req)
+        except grpc.RpcError as e:
+            raise wrap_error(e) from e
+
+    def retire_model_pricing_baseline(
+        self, params: RetireModelPricingBaselineParams
+    ) -> model_pricing_baseline_pb2.ModelPricingBaseline:
+        """Retire one model from the registry catalog.
+
+        The rebuilt registry drops it from every price surface; the document
+        is kept for audit and the key can be revived by a subsequent upsert.
+        """
+        req = billing_io_pb2.RetireModelPricingBaselineInput(
+            model_id=params.model_id,
+            provider=params.provider,
+            harness=params.harness,
+            revision_note=params.revision_note,
+        )
+        try:
+            return self._command.retireModelPricingBaseline(req)
+        except grpc.RpcError as e:
+            raise wrap_error(e) from e

stigmer/_client.py

@@ -0,0 +1,124 @@
+"""Top-level Stigmer API client."""
+
+from __future__ import annotations
+
+from typing import Literal
+from types import TracebackType
+
+import grpc
+
+from ._billing import BillingClient
+from ._gen._client import GeneratedClient
+from ._github import GitHubClient
+from ._runner_adapter import RunnerAdapter
+from ._search import SearchClient
+from ._skill import RoutedSkillClient
+from ._tokens import TokenClient
+from ._transport import DEFAULT_TARGET, create_channel
+
+ExecutionTargetOption = Literal["local", "cloud"]
+
+_EXECUTION_TARGET_MAP = {
+    "local": 1,   # EXECUTION_TARGET_LOCAL
+    "cloud": 2,   # EXECUTION_TARGET_CLOUD
+}
+
+
+class StigmerClient(GeneratedClient):
+    """Stigmer API client.
+
+    Extends the code-generated :class:`GeneratedClient` so every resource
+    sub-client (agents, sessions, plugins, oauthapps, …) is inherited
+    automatically — new resource clients added by codegen appear on this
+    class without manual wiring.
+
+    On top of the generated resource clients, ``StigmerClient`` adds:
+
+    - Configuration and gRPC channel setup
+    - Cross-resource :attr:`search` client
+    - :attr:`github` OAuth integration client
+    - :attr:`billing` bounded-context client
+    - :attr:`tokens` user-token minting client (service-account keys)
+
+    Usage::
+
+        client = StigmerClient("sk_live_abc123")
+        agent = client.agents.get("agent-id")
+        client.close()
+
+    As a context manager::
+
+        with StigmerClient("sk_live_abc123") as client:
+            agent = client.agents.get("agent-id")
+
+    With an app-level execution target::
+
+        client = StigmerClient("sk_live_abc123", execution_target="local")
+    """
+
+    search: SearchClient
+    github: GitHubClient
+    billing: BillingClient
+    tokens: TokenClient
+    skills: RoutedSkillClient
+    default_execution_target: int
+    runner_adapter: RunnerAdapter | None
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = DEFAULT_TARGET,
+        insecure: bool = False,
+        execution_target: ExecutionTargetOption | None = None,
+        runner_adapter: RunnerAdapter | None = None,
+    ) -> None:
+        """Create a Stigmer client.
+
+        Args:
+            api_key: Stigmer API key (``sk_live_...``).
+            base_url: gRPC target address. Defaults to ``api.stigmer.ai:443``.
+            insecure: Disable TLS (local development only).
+            execution_target: Default execution target for all sessions
+                created through this client. ``"local"`` means the client
+                provides runners; ``"cloud"`` means the server provisions
+                sandboxes. ``None`` lets the server decide.
+            runner_adapter: Runner adapter for local execution lifecycle
+                management. When ``execution_target`` is ``"local"``, the
+                adapter is driven when a session opens and closes.
+                Cloud consumers omit this.
+        """
+        if not api_key:
+            raise ValueError("stigmer: API key is required")
+
+        self._channel = create_channel(base_url, api_key, insecure=insecure)
+        super().__init__(self._channel)
+
+        self.default_execution_target = (
+            _EXECUTION_TARGET_MAP[execution_target] if execution_target else 0
+        )
+        self.runner_adapter = runner_adapter
+        self.search = SearchClient(self._channel)
+        self.github = GitHubClient(self._channel)
+        self.billing = BillingClient(self._channel)
+        self.tokens = TokenClient(self._channel)
+        # Shadow the inherited generated client with the size-routing wrapper
+        # (stigmer#675): `client.skills.push` simply works for any valid
+        # skill size — large artifacts ride the HTTP transfer lane.
+        self.skills = RoutedSkillClient(self._channel)
+
+    def close(self) -> None:
+        """Release the underlying gRPC channel."""
+        if self._channel is not None:
+            self._channel.close()
+
+    def __enter__(self) -> StigmerClient:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> None:
+        self.close()

stigmer/_gen/__init__.py

@@ -0,0 +1,152 @@
+# Code generated by stigmer-codegen. DO NOT EDIT.
+
+from ._bidi import BidiStream
+from ._client import GeneratedClient
+from ._agent import AgentClient, AgentInput, EnvVarDeclarationInput, HookSourceInput, HookConfigInput, HookGroupInput, HookHandlerInput, RunConfigInput, AgentMcpServerInput
+from ._apikey import ApiKeyClient, ApiKeyInput
+from ._channel import ChannelClient, ChannelInput, WebChannelConfigInput, WebChannelMessagesInput, SlackChannelConfigInput, WhatsAppChannelConfigInput
+from ._channelapp import ChannelAppClient, ChannelAppInput, SlackChannelAppConfigInput, WhatsAppChannelAppConfigInput
+from ._eval import EvalClient, EvalInput
+from ._evalrun import EvalRunClient, EvalRunInput, EvalRunCaseSourceInput, EvalRunTargetInput
+from ._federationissuer import FederationIssuerClient, FederationIssuerInput
+from ._grant import GrantClient, GrantInput, ApiResourceRefInput
+from ._identityaccount import IdentityAccountClient, IdentityAccountInput, IdentityAccountPreferencesInput
+from ._invitation import InvitationClient, InvitationInput
+from ._license import LicenseClient, LicenseInput, LicenseCustomerInput, EntitlementsInput, EntitlementLimitsInput
+from ._memory import MemoryClient, MemoryInput, MemoryProvenanceInput
+from ._oauthapp import OAuthAppClient, OAuthAppInput
+from ._organization import OrganizationClient, OrganizationInput, OrganizationPreferencesInput, OrganizationPoliciesInput, OrganizationEmbeddingInput
+from ._plan import PlanClient, PlanInput, PlanTermsInput
+from ._plugin import PluginClient, PluginInput, PluginAuthorInput
+from ._providerkey import ProviderKeyClient
+from ._run import RunClient, RunInput, SessionSpecInput, WorkspaceEntryInput, WorkspaceSourceInput, GitRepoSourceInput, LocalPathSourceInput, AttachmentInput, ConversationCatchupInput, EvalCaseContextInput, EvalMockServerInput, EvalMockToolInput, EvalMockPluginHomeInput, EvalMockAgentHomeInput
+from ._schedule import ScheduleClient, ScheduleInput, AgentInvocationInput
+from ._score import ScoreClient, ScoreInput, ScoreCriterionInput
+from ._scoringrule import ScoringRuleClient, ScoringRuleInput
+from ._session import SessionClient, SessionInput
+from ._skill import SkillClient, SkillInput
+from ._subscription import SubscriptionClient, SubscriptionInput
+from ._team import TeamClient, TeamInput
+from ._vault import VaultClient, VaultInput, VaultSecretInput, VaultConnectionInput, VaultConnectionSignInInput
+from ._types import (
+    DeleteResourceInput,
+    ResourceRef,
+)
+from ._errors import (
+    ErrorCode,
+    StigmerError,
+    is_not_found,
+    is_permission_denied,
+    is_retryable,
+    is_unauthenticated,
+    is_unimplemented,
+    wrap_error,
+)
+
+__all__ = [
+    "GeneratedClient",
+    "AgentClient",
+    "AgentInput",
+    "EnvVarDeclarationInput",
+    "HookSourceInput",
+    "HookConfigInput",
+    "HookGroupInput",
+    "HookHandlerInput",
+    "RunConfigInput",
+    "AgentMcpServerInput",
+    "ApiKeyClient",
+    "ApiKeyInput",
+    "ChannelClient",
+    "ChannelInput",
+    "WebChannelConfigInput",
+    "WebChannelMessagesInput",
+    "SlackChannelConfigInput",
+    "WhatsAppChannelConfigInput",
+    "ChannelAppClient",
+    "ChannelAppInput",
+    "SlackChannelAppConfigInput",
+    "WhatsAppChannelAppConfigInput",
+    "EvalClient",
+    "EvalInput",
+    "EvalRunClient",
+    "EvalRunInput",
+    "EvalRunCaseSourceInput",
+    "EvalRunTargetInput",
+    "FederationIssuerClient",
+    "FederationIssuerInput",
+    "GrantClient",
+    "GrantInput",
+    "ApiResourceRefInput",
+    "IdentityAccountClient",
+    "IdentityAccountInput",
+    "IdentityAccountPreferencesInput",
+    "InvitationClient",
+    "InvitationInput",
+    "LicenseClient",
+    "LicenseInput",
+    "LicenseCustomerInput",
+    "EntitlementsInput",
+    "EntitlementLimitsInput",
+    "MemoryClient",
+    "MemoryInput",
+    "MemoryProvenanceInput",
+    "OAuthAppClient",
+    "OAuthAppInput",
+    "OrganizationClient",
+    "OrganizationInput",
+    "OrganizationPreferencesInput",
+    "OrganizationPoliciesInput",
+    "OrganizationEmbeddingInput",
+    "PlanClient",
+    "PlanInput",
+    "PlanTermsInput",
+    "PluginClient",
+    "PluginInput",
+    "PluginAuthorInput",
+    "ProviderKeyClient",
+    "RunClient",
+    "RunInput",
+    "SessionSpecInput",
+    "WorkspaceEntryInput",
+    "WorkspaceSourceInput",
+    "GitRepoSourceInput",
+    "LocalPathSourceInput",
+    "AttachmentInput",
+    "ConversationCatchupInput",
+    "EvalCaseContextInput",
+    "EvalMockServerInput",
+    "EvalMockToolInput",
+    "EvalMockPluginHomeInput",
+    "EvalMockAgentHomeInput",
+    "ScheduleClient",
+    "ScheduleInput",
+    "AgentInvocationInput",
+    "ScoreClient",
+    "ScoreInput",
+    "ScoreCriterionInput",
+    "ScoringRuleClient",
+    "ScoringRuleInput",
+    "SessionClient",
+    "SessionInput",
+    "SkillClient",
+    "SkillInput",
+    "SubscriptionClient",
+    "SubscriptionInput",
+    "TeamClient",
+    "TeamInput",
+    "VaultClient",
+    "VaultInput",
+    "VaultSecretInput",
+    "VaultConnectionInput",
+    "VaultConnectionSignInInput",
+    "DeleteResourceInput",
+    "ResourceRef",
+    "ErrorCode",
+    "StigmerError",
+    "is_not_found",
+    "is_permission_denied",
+    "is_retryable",
+    "is_unauthenticated",
+    "is_unimplemented",
+    "wrap_error",
+]