Metadata-Version: 2.4
Name: juntai-fuse-api
Version: 1.0.0
Summary: Juntai Fuse API - Unified API framework supporting HTTP, RPC, and MCP protocols through a single registration interface.
Project-URL: Homepage, https://github.com/zephytiju/JuntaiFuseAPI
Project-URL: Repository, https://github.com/zephytiju/JuntaiFuseAPI.git
Project-URL: Documentation, https://github.com/zephytiju/JuntaiFuseAPI#readme
Author-email: Juntai Team <dev@juntai.com>
License: PROPRIETARY SOFTWARE LICENSE AGREEMENT
        
        Copyright (c) 2024-2026 Juntai Team. All rights reserved.
        
        IMPORTANT NOTICE: This software and associated documentation files (the
        "Software") are proprietary and confidential products of Juntai Team (the
        "Licensor"). By accessing, copying, installing, or otherwise using this
        Software, you agree to be bound by the terms of this Agreement. If you do
        not agree to these terms, do not access or use the Software.
        
        1. OWNERSHIP
        
        The Software is owned by the Licensor and is protected by copyright laws
        and international copyright treaties, as well as other intellectual
        property laws and treaties. The Software is licensed, not sold. All rights
        not expressly granted herein are reserved by the Licensor.
        
        2. LICENSE GRANT
        
        Subject to the terms and conditions of this Agreement, the Licensor grants
        you a limited, non-exclusive, non-transferable, revocable license to use
        the Software solely for internal business purposes within your organization,
        and only to the extent authorized by a separate written agreement with the
        Licensor.
        
        3. RESTRICTIONS
        
        You shall NOT, and shall not permit any third party to:
        
          (a) copy, reproduce, distribute, sublicense, lease, rent, lend, or
              otherwise transfer the Software or any portion thereof to any
              third party;
        
          (b) modify, adapt, translate, reverse engineer, decompile, disassemble,
              or otherwise attempt to derive the source code of the Software,
              except to the extent expressly permitted by applicable law
              notwithstanding this limitation;
        
          (c) create derivative works based on the Software;
        
          (d) remove, alter, or obscure any proprietary notices, labels, or marks
              on the Software;
        
          (e) use the Software for any purpose other than as expressly permitted
              under this Agreement;
        
          (f) use the Software to develop a competing product or service;
        
          (g) publicly display, perform, or transmit the Software or any portion
              thereof;
        
          (h) make the Software available for external use, including but not
              limited to use as a service provider, time-sharing, or service
              bureau arrangement.
        
        4. CONFIDENTIALITY
        
        You acknowledge that the Software contains valuable trade secrets and
        confidential information of the Licensor. You agree to maintain the
        confidentiality of the Software and to use at least the same degree of
        care to prevent the unauthorized disclosure of the Software as you use to
        protect your own confidential information, but in no event less than
        reasonable care.
        
        5. NO WARRANTY
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
        OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. THE ENTIRE RISK AS
        TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU.
        
        6. LIMITATION OF LIABILITY
        
        IN NO EVENT SHALL THE LICENSOR BE LIABLE TO YOU OR ANY THIRD PARTY FOR
        ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
        DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
        OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
        HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
        STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
        IN ANY WAY OUT OF THE USE OF OR INABILITY TO USE THIS SOFTWARE, EVEN
        IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
        
        7. TERM AND TERMINATION
        
        This Agreement is effective until terminated. The Licensor may terminate
        this Agreement at any time if you fail to comply with any term of this
        Agreement. Upon termination, you must cease all use of the Software and
        destroy all copies, full or partial, of the Software.
        
        8. EXPORT COMPLIANCE
        
        You shall comply with all applicable export laws and regulations and
        shall not export, re-export, or transfer the Software in violation of
        any such laws or regulations.
        
        9. GOVERNING LAW
        
        This Agreement shall be governed by and construed in accordance with
        the laws of the People's Republic of China, without regard to its
        conflict of law principles.
        
        10. ENTIRE AGREEMENT
        
        This Agreement constitutes the entire agreement between the parties
        concerning the subject matter hereof and supersedes all prior and
        contemporaneous agreements and understandings, whether written or oral.
        
        For licensing inquiries, please contact: dev@juntai.com
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: juntai-observability-python<3.0.0,>=2.0.1
Requires-Dist: pydantic<3.0.0,>=2.10.0
Provides-Extra: grpc-generated
Requires-Dist: grpcio-tools<2.0.0,>=1.60.0; extra == 'grpc-generated'
Requires-Dist: grpcio<2.0.0,>=1.60.0; extra == 'grpc-generated'
Requires-Dist: protobuf<7.0.0,>=5.0.0; extra == 'grpc-generated'
Provides-Extra: http
Requires-Dist: fastapi<1.0.0,>=0.115.0; extra == 'http'
Requires-Dist: uvicorn[standard]<1.0.0,>=0.30.0; extra == 'http'
Provides-Extra: mcp-v2
Requires-Dist: mcp-types<3.0.0,>=2.0.0; extra == 'mcp-v2'
Requires-Dist: mcp<3.0.0,>=2.0.0; extra == 'mcp-v2'
Description-Content-Type: text/markdown

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

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

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

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

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

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