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;
• deterministic OpenAPI and service-owned Protobuf artifact 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.

Service-owned Protobuf and generated-gRPC artifacts

Internal gRPC services own their versioned .proto source files. FuseAPI does not derive published messages, fields, field numbers, RPC names, packages, or status semantics from endpoint decorators. Compile the owning service's exact source set with the sole production profile juntai.fuse.profile.grpc-generated:

from pathlib import Path

from juntai.sdk.fuse_api import (
    ProtobufArtifactGenerator,
    ProtobufArtifactIdentity,
)

source_path = "example/capability/v1/capability.proto"
bundle = ProtobufArtifactGenerator().generate(
    {source_path: Path(source_path).read_text(encoding="utf-8")},
    identity=ProtobufArtifactIdentity(
        service="capability-service",
        version="1.4.0",
        source_repository="example/capability-service",
        source_commit="0123456789abcdef0123456789abcdef01234567",
    ),
)
bundle.write_to(".")
bundle.assert_matches(".")

The output under contracts/protobuf/ contains the normalized source set, Python message bindings, a generated module containing both server bindings and Python client stubs, an import-complete descriptor set, SHA-256 checksums, and a canonical generation manifest. The manifest pins the service/release identity, source repository and commit, FuseAPI version, exact profile and profile version, grpcio-tools and protobuf versions, every artifact digest, and the aggregate bundle digest. It contains no timestamp or workspace path.

CI must regenerate in a clean temporary directory with the exact locked toolchain and call assert_matches against the checked-in artifact tree. A published contract is immutable; correcting it requires a new service release. Registry services must not use RPCAdapter.export_spec() or ProtobufSpecGenerator to create their contracts. They must not emit or expose a REST/JSON adapter, OpenAPI artifact, browser transport, gateway transcode, TypeScript generator, or runtime service-registration surface.

Generated Python clients create secure gRPC channels with injected TLS/mTLS or workload-identity credentials, set explicit deadlines, propagate correlation metadata, and preserve cancellation. Service implementations own canonical gRPC status semantics and health behavior; the generated bindings preserve those statuses over the real Python gRPC transport.

Corrected downstream client handoff

The high-level client repositories and standard Python dependencies are:

Those distribution and import names are packaging metadata only. They are not written into Registry .proto sources or descriptor sets, and they do not change the service-owned Protobuf packages or services. Downstream clean regeneration is pinned by tests/conformance/fixtures/grpc_generated_downstream.json: FuseAPI 1.1.1, profile juntai.fuse.profile.grpc-generated version 1.0.0, grpcio-tools==1.81.1, and protobuf==6.33.6. The immutable FuseAPI release source repository is exactly zephytiju/JuntaiFuseAPI; downstream provenance must use that name and must not rely on a repository redirect.

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 CI workspace is locked by ci/uv.lock. scripts/bootstrap_ci_workspace.py copies that committed lock into the generated workspace before Jumbo runs. The released wheel declares the canonical public juntai-observability>=2.0.5,<3.0.0 distribution so clean and editable service environments resolve a PEP 420-compatible shared juntai namespace from PyPI. CI installs the built FuseAPI wheel beside the committed Hatch editable juntai.configuration fixture and verifies that both packages import from separate namespace paths. FuseAPI and sibling distributions must not install a competing juntai/__init__.py.

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.