Metadata-Version: 2.4
Name: charter-integration-sdk
Version: 0.0.1
Summary: JSON-RPC integration contract for Charter — the only dependency provider integrations need.
Project-URL: Homepage, https://github.com/charter-tool/charter
Project-URL: Repository, https://github.com/charter-tool/charter
Project-URL: Issues, https://github.com/charter-tool/charter/issues
Project-URL: Changelog, https://github.com/charter-tool/charter/blob/main/CHANGELOG.md
Author: Paulo Alvarado Garcia
License: MIT
Keywords: integration,json-rpc,sdk,workflow
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
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
Requires-Python: >=3.11
Requires-Dist: pydantic>=2.0
Description-Content-Type: text/markdown

# 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.

```bash
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](../../README.md).

## 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`](../charter-core/README.md).
- It does not manage projects, install requirements, or resolve capabilities; that belongs to [`charter-cli`](../charter-cli/README.md).

## Python Provider Skeleton

```python
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`:

```text
→ {"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`:

```python
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:

```toml
[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

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