astraform-remote-domain-author-kit 0.1.0

Python author kit for Astraform remote-domain.v1 services

astraform-remote-domain-author-kit

This is the Python author kit for remote-domain.v1.

Brutal truth: an "SDK" alone is not enough. If teams still have to reverse engineer request envelopes, invent their own starter layout, or guess how to prove conformance, you did not ship onboarding. You shipped homework.

This author kit is broader than a thin SDK. It includes:

• reusable protocol constants and envelope builders
• request validation helpers
• an optional FastAPI app factory
• a starter template inside the package

If you only want helper functions, that is the SDK-like layer. The author kit is the whole package around it.

Install

Current status: this package has Python packaging metadata and a PyPI release workflow, but no public release has been proven yet. The commands below describe the intended consumer install shape after the first PyPI publish. For repo-local development today, use editable installs from this workspace.

Protocol helpers only:

pip install astraform-remote-domain-author-kit

FastAPI helper included:

pip install 'astraform-remote-domain-author-kit[fastapi]'

Repo-local development:

pip install -e './remote-domain-author-kit-python[fastapi,test]'

Core Usage

from astraform.remote_domain.author_kit.protocol import build_manifest
from astraform.remote_domain.author_kit.protocol import build_projection
from astraform.remote_domain.author_kit.protocol import opaque_state
from astraform.remote_domain.author_kit.protocol import projection_envelope
from astraform.remote_domain.author_kit.protocol import success_envelope
from astraform.remote_domain.author_kit.protocol import validate_request_envelope


def manifest() -> dict:
    return build_manifest(
        domain_id="acme-ops",
        display_name="Acme Operations Domain",
        description="Remote proof domain",
        schema_version="acme-ops.state.v1",
        supported_agent_types=["Operator"],
        supported_interaction_modes=["SIMULATION", "HYBRID"],
        tools=[
            {
                "name": "lookup_case",
                "description": "Look up a case in the remote domain.",
                "inputSchema": {"type": "object", "additionalProperties": False},
            }
        ],
    )


def prepare(request: dict) -> dict:
    validate_request_envelope(
        request,
        expected_domain_id="acme-ops",
        expected_operation="prepare",
        require_idempotency=True,
    )
    state = opaque_state(
        "acme-ops.state.v1",
        {"personaName": "Taylor", "completedWorkCount": 0},
    )
    projection = build_projection(
        runtime_metadata={"domainProfile": "acme"},
        status_view={"completedWorkCount": 0},
        inspection_view={"tasks": []},
    )
    return success_envelope(
        request,
        runtime_identity="acme-ops::Taylor",
        next_state=state,
        projection=projection,
    )


def status(request: dict) -> dict:
    validate_request_envelope(
        request,
        expected_domain_id="acme-ops",
        expected_operation="status",
        require_state=True,
    )
    return projection_envelope(
        request,
        projection=build_projection(
            runtime_metadata={"domainProfile": "acme"},
            status_view={"completedWorkCount": 0},
            inspection_view={"tasks": []},
        ),
    )

FastAPI App Factory

from astraform.remote_domain.author_kit.fastapi import create_fastapi_app

app = create_fastapi_app(service=my_remote_domain_service)

The service object must implement:

• manifest()
• prepare(payload)
• execute_work(payload)
• status(payload)
• inspection(payload)
• shutdown(payload)

Starter Template

The bundled starter template lives under:

• astraform/remote_domain/author_kit/templates/fastapi-minimal

It is intentionally boring. That is a feature. Teams need a truthful starting point, not a framework demo that hides the protocol.

Publishing Status

This package should be released through the shared Python + Java SDK publishing process documented in docs/platform/remote-domain-sdk-publishing.md.

Release guardrail:

SDK_VERSION=0.1.0 scripts/check-remote-domain-sdk-release-gates.sh

Do not call this a partner-ready SDK release until:

• the package is published to PyPI
• astraform-remote-domain-conformance is published with a compatible version
• an external consumer project installs both packages from the registry
• the consumer project passes remote-domain.v1 conformance outside this monorepo

Public package note: PyPI distributions expose this SDK implementation. Keep host runtime internals and domain-private logic out of this package.