Juntai Fuse API

Juntai Fuse API is the production API framework for registering one application handler surface and projecting it through supported protocol adapters.

The package contains:

• endpoint and entity-endpoint registration;
• the shared invocation and lifecycle kernel;
• HTTP and generated-gRPC production adapters;
• OpenAPI and protobuf generation;
• versioned, transport-neutral descriptor models; and
• exact dependency profiles for each supported adapter.

It does not provide application-specific contracts, identity, readiness, descriptor storage, entity storage, or simulated platform providers. Applications must supply their own resolver backed by their production data adapter.

Runtime setup

Install the package with the adapter extra used by the service:

uv add 'juntai-fuse-api[http]>=1,<2'
uv add 'juntai-fuse-api[grpc-generated]>=1,<2'

Select the versioned runtime profile and build a server. The shorthand is resolved against the package-owned compatibility matrix and still fails closed when an optional dependency is absent or outside its supported window:

from juntai.sdk.fuse_api import EndpointGroup, FuseServer, select_profile

profile = select_profile("juntai.fuse.profile.http/v1")

items = EndpointGroup("items", prefix="/items")

@items.endpoint(method="GET", path="/{item_id}", protocols=["http"])
async def get_item(item_id: str) -> dict[str, str]:
    return {"item_id": item_id}

server = FuseServer(profile=profile)
server.register(items)
server.enable_http()

The framework exposes stable implementation namespaces under decorators/, invocation/, models/, middleware/, protocols/, generation/, and testing/. The legacy top-level imports remain aliases to those same objects; there is no second invocation path or adapter implementation.

Service-owned OpenAPI artifacts

Generate release artifacts from the service composition root. The service supplies its own stable identity, version, source commit, endpoint groups, and output root; FuseAPI supplies only deterministic generation mechanics.

from juntai.sdk.fuse_api import OpenAPIArtifactGenerator, ServiceArtifactIdentity

bundle = OpenAPIArtifactGenerator().generate(
    [items],
    identity=ServiceArtifactIdentity(
        service="inventory-service",
        version="1.4.0",
        source_commit="0123456789abcdef0123456789abcdef01234567",
    ),
    title="Inventory Service",
)
bundle.write_to(".")

This writes contracts/openapi/inventory-service.v1.json, its .sha256 file, and contracts/openapi/generation-manifest.json. Serialization is canonical, the manifest contains no wall-clock timestamp, and compatibility checks are available through compare_openapi and assert_openapi_compatible. These files belong to the service repository and are not copied into FuseAPI.

For entity endpoints, implement EntityResolver or wrap an application-owned production lookup with CallableEntityResolver.

Development

uv sync --all-groups --all-extras
uv run pytest
uv run ruff check src tests scripts
uv build

scripts/verify_profile_packaging.py verifies that packaged extras match the versioned profile matrix. scripts/verify_artifacts.py validates wheel and source distribution contents and checksum provenance.

The exact two-repository CI workspace is locked by ci/uv.lock. scripts/bootstrap_ci_workspace.py verifies the pinned Observability checkout and copies that committed lock into the generated workspace before Jumbo runs. The released wheel declares the public juntai-observability-python>=2.0.1,<3.0.0 distribution so clean service environments resolve every runtime dependency from PyPI.

Releases

The canonical version lives in pyproject.toml. A reviewed version change on main runs .github/workflows/publish-python.yml, builds the wheel and source distribution once, publishes those exact files through PyPI Trusted Publishing, and creates the matching immutable v<version> GitHub release. Publication uses the protected pypi GitHub environment and short-lived OIDC credentials; no PyPI API token is stored in GitHub.

Production boundary

Run the repository-wide fail-closed check before dependency setup:

python scripts/check_production_boundary.py

The command scans every path in the Git index. It has no file allowlist or baseline exemption, so source, tests, conformance, integration, examples, documentation commands, container definitions, CI, and acceptance artifacts are all covered whenever present. The test suite includes negative cases proving that every delivery surface is rejected consistently and that an incomplete scan fails closed.