charter-integration-sdk

Protocol and integration contract package for Charter. Install this when you are building an integration and want the shared message models and WorkflowIntegration interface without pulling in the runtime or CLI.

pip install charter-integration-sdk

Use This Package When

• You are authoring a Charter integration in Python.
• You need the JSON-RPC message models used by subprocess integrations.
• You want to validate integration inputs and outputs against the same contract the runtime uses.

For workflow authoring, project config, and end-to-end run examples, see the main Charter README.

What charter-integration-sdk Provides

• WorkflowIntegration, ResolvedStep, and StepContext
• WorkflowIntegration plus typed config-model discovery for Python integrations
• JSON-RPC request/response models for setup, execute, and teardown
• shared output-type definitions used by integrations and the runtime

What It Does Not Do

• It does not run workflows; that belongs to charter-core.
• It does not manage projects, install requirements, or resolve capabilities; that belongs to charter-cli.

Python Provider Skeleton

from pydantic import BaseModel

from typing import Any

from charter_integration_sdk import ResolvedStep, StepContext, WorkflowIntegration


class MyConfig(BaseModel):
    api_token: str


class MyIntegration(WorkflowIntegration):
    config: MyConfig

    async def execute(self, step: ResolvedStep, context: StepContext) -> Any:
        instruction = step.with_config["prompt"]
        inputs = context.inputs

        result = do_work(instruction, inputs, api_token=self.config.api_token)
        return result

step contains the runner-normalized step definition. The integration receives the merged config at execute time; it is responsible for deciding which fields apply at setup vs invocation. context.inputs is the resolved input map your integration should actually use at execution time.

context.outputs and context.named_outputs are convenience views over prior step outputs, but artifact-backed values are only guaranteed to be hydrated when the current step declares them in inputs:. For undeclared artifact dependencies, those views may still contain artifact refs rather than full payloads.

Subprocess Protocol

Subprocess-backed integrations speak newline-delimited JSON-RPC 2.0 over stdin / stdout:

→ {"jsonrpc":"2.0","id":"1","method":"setup","params":{"run_id":"abc123"}}
← {"jsonrpc":"2.0","id":"1","result":{"ok":true}}

→ {"jsonrpc":"2.0","id":"2","method":"execute","params":{"step":{...},"context":{...}}}
← {"jsonrpc":"2.0","id":"2","result":{"value":"some value"}}

→ {"jsonrpc":"2.0","id":"3","method":"teardown","params":{}}
← {"jsonrpc":"2.0","id":"3","result":{"ok":true}}

The matching models are available from charter_integration_sdk.messages:

from charter_integration_sdk.messages import (
    ExecuteParams,
    ExecuteResult,
    JsonRpcRequest,
    JsonRpcResponse,
    SetupParams,
    SetupResult,
    TeardownParams,
    TeardownResult,
)

Entry Point Registration

If you package a Python integration for uses: resolution, register it under the charter.integrations entry-point group:

[project.entry-points."charter.integrations"]
my_llm = "my_package.integrations:MyIntegration"
stripe_api = "my_package.integrations:StripeIntegration"

Charter discovers uses: integrations from installed package metadata at runtime, so the integration package must be installed in the active environment.

Public API Highlights

from charter_integration_sdk import (
    ExecuteParams,
    ExecuteResult,
    JsonRpcRequest,
    JsonRpcResponse,
    ResolvedStep,
    SetupParams,
    SetupResult,
    StepContext,
    TeardownParams,
    TeardownResult,
    WorkflowIntegration,
    integration_config_model,
)