astraform-remote-domain-author-kit 0.1.2__tar.gz

astraform_remote_domain_author_kit-0.1.2/PKG-INFO

@@ -0,0 +1,329 @@
+Metadata-Version: 2.4
+Name: astraform-remote-domain-author-kit
+Version: 0.1.2
+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: the published PyPI baseline is
+`astraform-remote-domain-author-kit==0.1.0`. The workspace release target is
+`0.1.2`, which adds the current Population Builder catalog/readiness starter
+shape. Do not claim external Python catalog authoring support until `0.1.2` is
+actually published to PyPI.
+
+Protocol helpers only:
+
+```bash
+pip install astraform-remote-domain-author-kit==0.1.0
+```
+
+FastAPI helper included:
+
+```bash
+pip install 'astraform-remote-domain-author-kit[fastapi]==0.1.0'
+```
+
+For catalog-enabled `0.1.2` work before publication, use the monorepo editable
+install or a private pre-release wheel.
+
+Repo-local development:
+
+```bash
+pip install -e './remote-domain-author-kit-python[fastapi,test]'
+```
+
+Starter-template validation is part of the release gate. It still runs the
+template's `scripts/bootstrap-local-sdk.sh` path against the repo-local SDK
+source, then separately runs an external-consumer smoke from the exact built
+local author-kit and conformance wheels. That smoke creates a clean project,
+copies the starter through the installed `astraform-remote-domain-copy-starter`
+command, installs the copied starter with `--no-deps`, runs
+`validate-population-catalog`, and passes
+`remote-domain-conformance --population-catalog`. That keeps the source
+bootstrap and release artifact paths honest before the matching SDK version is
+visible on PyPI.
+
+## 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": []},
+        ),
+    )
+```
+
+Domain providers may add optional `evidence_events=[...]` to
+`success_envelope(...)` or `projection_envelope(...)`. Use that lane for
+provider-internal evidence that Astraform cannot observe directly, such as a
+private third-party call or domain-owned policy check.
+
+## FastAPI App Factory
+
+```python
+from astraform.remote_domain.author_kit.fastapi import create_fastapi_app
+
+app = create_fastapi_app(
+    service=my_remote_domain_service,
+    policy_wind_tunnel_service=my_policy_wind_tunnel_service,
+)
+```
+
+The service object must implement:
+
+- `manifest()`
+- optional `population_catalog()` for
+  `GET /api/remote-domain/v1/population/catalog`
+- `prepare(payload)`
+- `execute_work(payload)`
+- `status(payload)`
+- `inspection(payload)`
+- `shutdown(payload)`
+
+`population_catalog()` must return `domain_population_catalog.v1`. The FastAPI
+factory validates the catalog before returning it, so missing archetype fields,
+bad recipe numbers, unknown archetype references, and malformed eligibility
+fail before Population Builder treats the provider as usable.
+
+Prefer a file-backed catalog over an inline Python dict. That keeps the domain
+authoring surface reviewable and conformance-testable:
+
+```python
+from importlib import resources
+
+from astraform.remote_domain.author_kit import load_population_catalog
+
+
+def population_catalog() -> dict:
+    catalog_file = resources.files("my_remote_domain").joinpath("population_catalog.json")
+    return load_population_catalog(catalog_file)
+```
+
+`load_population_catalog(...)` reads JSON and runs the same
+`validate_population_catalog(...)` checks used by the FastAPI route.
+
+The bundled `fastapi-minimal` starter also installs a provider-local preflight:
+
+```bash
+validate-population-catalog
+```
+
+That command validates `src/acme_remote_domain/population_catalog.json` before
+the provider starts and prints the exact rejected field when the catalog is
+malformed. Treat it as the first command after editing archetypes, segment
+templates, validation rules, or run-path eligibility.
+
+The optional `policy_wind_tunnel_service` object exposes the remote Wind Tunnel
+provider routes:
+
+- `GET /policy-wind-tunnel/pack`
+- `GET /policy-wind-tunnel/presets`
+- `POST /policy-wind-tunnel/runs`
+- `GET /policy-wind-tunnel/runs/{runId}`
+- `POST /policy-wind-tunnel/runs/{runId}/lifecycle`
+- `GET /policy-wind-tunnel/runs/{runId}/bundle`
+- `GET /policy-wind-tunnel/runs/{runId}/artifacts/{artifactType}`
+- `GET /policy-wind-tunnel/runs/{runId}/artifacts/{artifactType}/readiness`
+- `GET /policy-wind-tunnel/runs/{runId}/evidence-pack`
+- `GET /policy-wind-tunnel/runs/{runId}/evidence-pack/readiness`
+
+The readiness routes are metadata-only checks for dashboard download UX. They
+must prove the same provider-owned artifact/evidence-pack path is readable
+without materializing the JSON body or ZIP archive.
+
+## Policy Expressions
+
+When a domain exposes Policy Wind Tunnel behavior, CEL-compatible
+`PolicyExpression` definitions are the portable decision contract. They are for
+decision gates, eligibility checks, thresholds, and conformance-testable public
+rules.
+
+They are not the execution engine. Keep state mutation, external calls,
+proprietary scoring, and side effects inside your service implementation or
+domain-owned execution target. Use the expression's `executionTarget` as a
+stable provider-owned target name.
+
+Python providers should publish the same `/policy-wind-tunnel/pack` metadata as
+Java providers. The helper below builds the portable parts of that response:
+
+```python
+from astraform.remote_domain.author_kit import build_policy_expression
+from astraform.remote_domain.author_kit import build_policy_wind_tunnel_pack_metadata
+
+
+def wind_tunnel_pack() -> dict:
+    return build_policy_wind_tunnel_pack_metadata(
+        capabilities={"remoteProviderReady": True, "evidenceExport": True},
+        control_schema={
+            "type": "object",
+            "properties": {
+                "blockerCount": {"type": "integer", "minimum": 0},
+            },
+        },
+        ui_schema={
+            "fields": [
+                {"name": "blockerCount", "widget": "number", "label": "Blockers"},
+            ],
+        },
+        outcome_schema={
+            "schemaVersion": "domain_outcome_schema.v1",
+            "metricDefinitions": [
+                {
+                    "metricId": "blockerCount",
+                    "label": "Blockers",
+                    "unit": "count",
+                    "evidence": "domain-state",
+                },
+            ],
+        },
+        domain_labels={
+            "actorSingular": "campaign",
+            "actorPlural": "campaigns",
+            "simulatedActorsLabel": "Simulated campaigns",
+        },
+        policy_expressions=[
+            build_policy_expression(
+                expression_id="acme.blockers.acceptable",
+                expression="metrics.blockerCount <= 10",
+                execution_target="acme-policy-service",
+                description="Blockers must stay under launch threshold.",
+            ),
+        ],
+    )
+```
+
+See
+[`docs/architecture/scenario-lab-policy-expressions.md`](../docs/architecture/scenario-lab-policy-expressions.md)
+for the contract shape and CEL subset.
+
+## Starter Template
+
+Copy the bundled FastAPI starter from the installed author kit:
+
+```bash
+astraform-remote-domain-copy-starter acme-remote-domain
+cd acme-remote-domain
+pip install --no-deps -e .
+validate-population-catalog
+remote-domain-conformance --app acme_remote_domain.main:app --domain-id acme-remote --population-catalog
+```
+
+The underlying template resource 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 is 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.2 scripts/check-remote-domain-sdk-release-gates.sh
+```
+
+PyPI artifacts are immutable. Do not rerun a publish for an already published
+version; run smoke-only verification or bump the SDK version.
+
+Public package note: PyPI distributions expose this SDK implementation. Keep
+host runtime internals and domain-private logic out of this package.

astraform_remote_domain_author_kit-0.1.2/README.md

@@ -0,0 +1,307 @@
+# 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: the published PyPI baseline is
+`astraform-remote-domain-author-kit==0.1.0`. The workspace release target is
+`0.1.2`, which adds the current Population Builder catalog/readiness starter
+shape. Do not claim external Python catalog authoring support until `0.1.2` is
+actually published to PyPI.
+
+Protocol helpers only:
+
+```bash
+pip install astraform-remote-domain-author-kit==0.1.0
+```
+
+FastAPI helper included:
+
+```bash
+pip install 'astraform-remote-domain-author-kit[fastapi]==0.1.0'
+```
+
+For catalog-enabled `0.1.2` work before publication, use the monorepo editable
+install or a private pre-release wheel.
+
+Repo-local development:
+
+```bash
+pip install -e './remote-domain-author-kit-python[fastapi,test]'
+```
+
+Starter-template validation is part of the release gate. It still runs the
+template's `scripts/bootstrap-local-sdk.sh` path against the repo-local SDK
+source, then separately runs an external-consumer smoke from the exact built
+local author-kit and conformance wheels. That smoke creates a clean project,
+copies the starter through the installed `astraform-remote-domain-copy-starter`
+command, installs the copied starter with `--no-deps`, runs
+`validate-population-catalog`, and passes
+`remote-domain-conformance --population-catalog`. That keeps the source
+bootstrap and release artifact paths honest before the matching SDK version is
+visible on PyPI.
+
+## 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": []},
+        ),
+    )
+```
+
+Domain providers may add optional `evidence_events=[...]` to
+`success_envelope(...)` or `projection_envelope(...)`. Use that lane for
+provider-internal evidence that Astraform cannot observe directly, such as a
+private third-party call or domain-owned policy check.
+
+## FastAPI App Factory
+
+```python
+from astraform.remote_domain.author_kit.fastapi import create_fastapi_app
+
+app = create_fastapi_app(
+    service=my_remote_domain_service,
+    policy_wind_tunnel_service=my_policy_wind_tunnel_service,
+)
+```
+
+The service object must implement:
+
+- `manifest()`
+- optional `population_catalog()` for
+  `GET /api/remote-domain/v1/population/catalog`
+- `prepare(payload)`
+- `execute_work(payload)`
+- `status(payload)`
+- `inspection(payload)`
+- `shutdown(payload)`
+
+`population_catalog()` must return `domain_population_catalog.v1`. The FastAPI
+factory validates the catalog before returning it, so missing archetype fields,
+bad recipe numbers, unknown archetype references, and malformed eligibility
+fail before Population Builder treats the provider as usable.
+
+Prefer a file-backed catalog over an inline Python dict. That keeps the domain
+authoring surface reviewable and conformance-testable:
+
+```python
+from importlib import resources
+
+from astraform.remote_domain.author_kit import load_population_catalog
+
+
+def population_catalog() -> dict:
+    catalog_file = resources.files("my_remote_domain").joinpath("population_catalog.json")
+    return load_population_catalog(catalog_file)
+```
+
+`load_population_catalog(...)` reads JSON and runs the same
+`validate_population_catalog(...)` checks used by the FastAPI route.
+
+The bundled `fastapi-minimal` starter also installs a provider-local preflight:
+
+```bash
+validate-population-catalog
+```
+
+That command validates `src/acme_remote_domain/population_catalog.json` before
+the provider starts and prints the exact rejected field when the catalog is
+malformed. Treat it as the first command after editing archetypes, segment
+templates, validation rules, or run-path eligibility.
+
+The optional `policy_wind_tunnel_service` object exposes the remote Wind Tunnel
+provider routes:
+
+- `GET /policy-wind-tunnel/pack`
+- `GET /policy-wind-tunnel/presets`
+- `POST /policy-wind-tunnel/runs`
+- `GET /policy-wind-tunnel/runs/{runId}`
+- `POST /policy-wind-tunnel/runs/{runId}/lifecycle`
+- `GET /policy-wind-tunnel/runs/{runId}/bundle`
+- `GET /policy-wind-tunnel/runs/{runId}/artifacts/{artifactType}`
+- `GET /policy-wind-tunnel/runs/{runId}/artifacts/{artifactType}/readiness`
+- `GET /policy-wind-tunnel/runs/{runId}/evidence-pack`
+- `GET /policy-wind-tunnel/runs/{runId}/evidence-pack/readiness`
+
+The readiness routes are metadata-only checks for dashboard download UX. They
+must prove the same provider-owned artifact/evidence-pack path is readable
+without materializing the JSON body or ZIP archive.
+
+## Policy Expressions
+
+When a domain exposes Policy Wind Tunnel behavior, CEL-compatible
+`PolicyExpression` definitions are the portable decision contract. They are for
+decision gates, eligibility checks, thresholds, and conformance-testable public
+rules.
+
+They are not the execution engine. Keep state mutation, external calls,
+proprietary scoring, and side effects inside your service implementation or
+domain-owned execution target. Use the expression's `executionTarget` as a
+stable provider-owned target name.
+
+Python providers should publish the same `/policy-wind-tunnel/pack` metadata as
+Java providers. The helper below builds the portable parts of that response:
+
+```python
+from astraform.remote_domain.author_kit import build_policy_expression
+from astraform.remote_domain.author_kit import build_policy_wind_tunnel_pack_metadata
+
+
+def wind_tunnel_pack() -> dict:
+    return build_policy_wind_tunnel_pack_metadata(
+        capabilities={"remoteProviderReady": True, "evidenceExport": True},
+        control_schema={
+            "type": "object",
+            "properties": {
+                "blockerCount": {"type": "integer", "minimum": 0},
+            },
+        },
+        ui_schema={
+            "fields": [
+                {"name": "blockerCount", "widget": "number", "label": "Blockers"},
+            ],
+        },
+        outcome_schema={
+            "schemaVersion": "domain_outcome_schema.v1",
+            "metricDefinitions": [
+                {
+                    "metricId": "blockerCount",
+                    "label": "Blockers",
+                    "unit": "count",
+                    "evidence": "domain-state",
+                },
+            ],
+        },
+        domain_labels={
+            "actorSingular": "campaign",
+            "actorPlural": "campaigns",
+            "simulatedActorsLabel": "Simulated campaigns",
+        },
+        policy_expressions=[
+            build_policy_expression(
+                expression_id="acme.blockers.acceptable",
+                expression="metrics.blockerCount <= 10",
+                execution_target="acme-policy-service",
+                description="Blockers must stay under launch threshold.",
+            ),
+        ],
+    )
+```
+
+See
+[`docs/architecture/scenario-lab-policy-expressions.md`](../docs/architecture/scenario-lab-policy-expressions.md)
+for the contract shape and CEL subset.
+
+## Starter Template
+
+Copy the bundled FastAPI starter from the installed author kit:
+
+```bash
+astraform-remote-domain-copy-starter acme-remote-domain
+cd acme-remote-domain
+pip install --no-deps -e .
+validate-population-catalog
+remote-domain-conformance --app acme_remote_domain.main:app --domain-id acme-remote --population-catalog
+```
+
+The underlying template resource 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 is 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.2 scripts/check-remote-domain-sdk-release-gates.sh
+```
+
+PyPI artifacts are immutable. Do not rerun a publish for an already published
+version; run smoke-only verification or bump the SDK version.
+
+Public package note: PyPI distributions expose this SDK implementation. Keep
+host runtime internals and domain-private logic out of this package.

astraform_remote_domain_author_kit-0.1.2/pyproject.toml

@@ -0,0 +1,58 @@
+[build-system]
+requires = ["setuptools>=77", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "astraform-remote-domain-author-kit"
+version = "0.1.2"
+description = "Python author kit for Astraform remote-domain.v1 services"
+readme = "README.md"
+requires-python = ">=3.12"
+license = "Apache-2.0"
+keywords = ["astraform", "remote-domain", "simulation", "conformance"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.12",
+  "Framework :: FastAPI",
+  "Typing :: Typed",
+]
+dependencies = []
+
+[project.urls]
+Documentation = "https://github.com/astraform/platform/blob/main/docs/guides/remote-domain-authoring-guide.md"
+Source = "https://github.com/astraform/platform"
+Publishing = "https://github.com/astraform/platform/blob/main/docs/platform/remote-domain-sdk-publishing.md"
+
+[project.optional-dependencies]
+fastapi = [
+  "fastapi>=0.115,<1.0",
+]
+test = [
+  "fastapi>=0.115,<1.0",
+  "httpx>=0.28,<1.0",
+  "pytest>=8.3,<9.0",
+]
+
+[project.scripts]
+astraform-remote-domain-copy-starter = "astraform.remote_domain.author_kit.templates:main"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+include-package-data = true
+
+[tool.setuptools.packages.find]
+where = ["src"]
+namespaces = true
+
+[tool.setuptools.package-data]
+"astraform.remote_domain.author_kit" = [
+  "templates/fastapi-minimal/README.md",
+  "templates/fastapi-minimal/pyproject.toml",
+  "templates/fastapi-minimal/scripts/*.sh",
+  "templates/fastapi-minimal/src/acme_remote_domain/*.json",
+  "templates/fastapi-minimal/src/acme_remote_domain/*.py",
+  "templates/fastapi-minimal/tests/*.py",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

astraform_remote_domain_author_kit-0.1.2/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+