Metadata-Version: 2.4
Name: astraform-remote-domain-author-kit
Version: 0.1.0
Summary: Python author kit for Astraform remote-domain.v1 services
License-Expression: Apache-2.0
Project-URL: Documentation, https://github.com/astraform/platform/blob/main/docs/guides/remote-domain-authoring-guide.md
Project-URL: Source, https://github.com/astraform/platform
Project-URL: Publishing, https://github.com/astraform/platform/blob/main/docs/platform/remote-domain-sdk-publishing.md
Keywords: astraform,remote-domain,simulation,conformance
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Framework :: FastAPI
Classifier: Typing :: Typed
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Provides-Extra: fastapi
Requires-Dist: fastapi<1.0,>=0.115; extra == "fastapi"
Provides-Extra: test
Requires-Dist: fastapi<1.0,>=0.115; extra == "test"
Requires-Dist: httpx<1.0,>=0.28; extra == "test"
Requires-Dist: pytest<9.0,>=8.3; extra == "test"

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

```bash
pip install astraform-remote-domain-author-kit
```

FastAPI helper included:

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

Repo-local development:

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

## Core Usage

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

```python
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`](../docs/platform/remote-domain-sdk-publishing.md).

Release guardrail:

```bash
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.
