usecaseapi 1.0.0__tar.gz

usecaseapi-1.0.0/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.py[cod]
+*$py.class
+
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.coverage
+coverage.*
+htmlcov/
+
+.venv/
+build/
+dist/
+*.egg-info/

usecaseapi-1.0.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,5 @@
+# Code of Conduct
+
+UseCaseAPI follows a simple contributor expectation: be respectful, precise, and constructive.
+
+Harassment, discrimination, personal attacks, and deliberately disruptive behavior are not welcome. Maintainers may remove content or restrict participation to keep the project healthy.

usecaseapi-1.0.0/CONTRIBUTING.md

@@ -0,0 +1,29 @@
+# Contributing
+
+Thank you for helping improve UseCaseAPI.
+
+## Development setup
+
+```bash
+uv sync --extra dev
+uv run pytest
+uv run mypy
+uv run ruff check .
+uv run ruff format .
+```
+
+## Expectations
+
+- Keep the public API small.
+- Preserve the no-DI-container, no-transaction-manager scope.
+- Keep all implementation fully typed and mypy-clean under strict mode.
+- Add tests for behavior changes.
+- Update docs when behavior or public API changes.
+
+## Pull request checklist
+
+- [ ] Tests pass.
+- [ ] Mypy passes.
+- [ ] Ruff passes.
+- [ ] Docs are updated.
+- [ ] New features do not add hidden serialization, hidden DI, or hidden transaction behavior.

usecaseapi-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 UseCaseAPI Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+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. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

usecaseapi-1.0.0/PKG-INFO

@@ -0,0 +1,192 @@
+Metadata-Version: 2.4
+Name: usecaseapi
+Version: 1.0.0
+Summary: FastAPI-style contracts for Python application use cases.
+Project-URL: Homepage, https://github.com/Wisteria30/usecaseapi
+Project-URL: Documentation, https://github.com/Wisteria30/usecaseapi/tree/main/docs
+Project-URL: Repository, https://github.com/Wisteria30/usecaseapi
+Project-URL: Issues, https://github.com/Wisteria30/usecaseapi/issues
+Author: UseCaseAPI Contributors
+Maintainer: UseCaseAPI Contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agents,application-api,contracts,protocol,pydantic,usecase,workflow
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: <3.15,>=3.12
+Requires-Dist: pydantic<3,>=2.12.4
+Provides-Extra: dev
+Requires-Dist: build>=1.3.0; extra == 'dev'
+Requires-Dist: coverage>=7.12.0; extra == 'dev'
+Requires-Dist: mypy>=1.18.2; extra == 'dev'
+Requires-Dist: pytest>=9.0.1; extra == 'dev'
+Requires-Dist: ruff>=0.14.6; extra == 'dev'
+Requires-Dist: twine>=6.2.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# UseCaseAPI
+
+FastAPI-style contracts for Python application use cases.
+
+UseCaseAPI brings code-first contract clarity to same-process Python use cases. Define contracts with Python Protocols, Pydantic models, and domain exceptions, then bind them to implementations without making HTTP the boundary.
+
+Add it when your application has internal use case nodes that need stable names, versions, input/output schemas, declared dependencies, and contract snapshots. It helps teams and AI coding agents see what can be called, what can fail, and whether a change broke an application-layer contract before that break ships.
+
+It is inspired by the developer experience of FastAPI, but it is not a web framework. FastAPI turns Python type hints into a public HTTP API contract. UseCaseAPI turns Python type definitions into public contracts for your application layer, without forcing HTTP, RPC, serialization, or a dependency-injection container into the hot path.
+
+UseCaseAPI is designed for applications with many internal use case nodes: workflow-like systems, ROS-like node composition, AI-agent tool surfaces, batch workers, CLIs, FastAPI/Django backends, and systems where AI-assisted coding makes accidental breaking changes easier than before.
+
+## What it gives you
+
+- Code-first usecase contracts using `Protocol`, `Model`, and normal Python exceptions.
+- Same-process direct calls with no JSON serialization in the hot path.
+- Explicit binding from contract token to implementation factory.
+- Declared usecase dependency graph with strict undeclared-call protection.
+- Versioned contract identity: `name@vN`.
+- Contract snapshots, conservative diffing, Markdown docs, Mermaid graph export, and CLI scaffolding.
+- No DI container, no transaction manager, no HTTP/RPC runtime.
+
+## Install
+
+```bash
+uv add usecaseapi
+```
+
+For local development:
+
+```bash
+uv sync --extra dev
+uv run pytest
+uv run mypy
+uv run ruff check .
+```
+
+Python support: 3.12, 3.13, and 3.14. Pydantic v2 is required.
+
+## Quick example
+
+Define a contract:
+
+```python
+from __future__ import annotations
+
+from typing import ClassVar, Literal, Protocol
+
+from usecaseapi import Contract, Model, UseCase, UseCaseError, UseCaseRef, define_usecase
+
+
+class Input(Model):
+    user_id: str
+    sku_id: str
+    quantity: int
+
+
+class Output(Model):
+    order_id: str
+    status: Literal["accepted"]
+
+
+class PlaceOrderError(UseCaseError):
+    code: ClassVar[str] = "orders.place_order"
+
+
+class InventoryShortage(PlaceOrderError):
+    code: ClassVar[str] = "orders.place_order.inventory_shortage"
+
+    def __init__(self, *, sku_id: str, requested: int, available: int) -> None:
+        self.sku_id = sku_id
+        self.requested = requested
+        self.available = available
+        super().__init__(
+            f"inventory shortage: sku_id={sku_id}, requested={requested}, available={available}"
+        )
+
+
+class PlaceOrder(UseCase[Input, Output], Protocol):
+    async def __call__(self, input: Input, /) -> Output:
+        ...
+
+
+PLACE_ORDER: UseCaseRef[Input, Output] = define_usecase(
+    PlaceOrder,
+    Contract(
+        name="orders.place_order",
+        version=1,
+        input=Input,
+        output=Output,
+        raises=(PlaceOrderError,),
+        known_errors=(InventoryShortage,),
+    ),
+)
+```
+
+Implement it:
+
+```python
+from app.contracts.orders.place_order.v1 import Input, Output, PlaceOrder
+
+
+class PlaceOrderImpl:
+    async def __call__(self, input: Input, /) -> Output:
+        return Output(order_id="ord_123", status="accepted")
+
+
+_impl: PlaceOrder = PlaceOrderImpl()
+```
+
+Bind and call it:
+
+```python
+from dataclasses import dataclass
+
+from usecaseapi import UseCaseAPI
+
+
+@dataclass(frozen=True)
+class AppContext:
+    tenant_id: str
+
+
+usecases = UseCaseAPI[AppContext]()
+usecases.bind(PLACE_ORDER, lambda caller: PlaceOrderImpl())
+
+output = await usecases.caller(AppContext(tenant_id="t1")).call(PLACE_ORDER, input)
+```
+
+## Scaffold
+
+```bash
+usecaseapi scaffold orders.place_order --version 1
+
+# Create the next major contract version by scanning app/contracts/orders/place_order/v*.py
+usecaseapi scaffold orders.place_order --next
+```
+
+This creates:
+
+```text
+app/contracts/orders/place_order/v1.py
+app/usecases/orders/place_order.py
+tests/test_orders_place_order_v1.py
+```
+
+## Why not just write classes yourself?
+
+You can, and for small projects you should. UseCaseAPI becomes useful when you have many internal nodes and you need to know:
+
+- which functions are public application-layer contracts;
+- which version each caller depends on;
+- which usecase dependencies are allowed;
+- which domain exceptions are part of the contract;
+- whether AI-assisted changes silently broke a stable contract;
+- what the application graph looks like.
+
+UseCaseAPI is a small runtime plus guardrails for that problem.

usecaseapi-1.0.0/README.md

@@ -0,0 +1,158 @@
+# UseCaseAPI
+
+FastAPI-style contracts for Python application use cases.
+
+UseCaseAPI brings code-first contract clarity to same-process Python use cases. Define contracts with Python Protocols, Pydantic models, and domain exceptions, then bind them to implementations without making HTTP the boundary.
+
+Add it when your application has internal use case nodes that need stable names, versions, input/output schemas, declared dependencies, and contract snapshots. It helps teams and AI coding agents see what can be called, what can fail, and whether a change broke an application-layer contract before that break ships.
+
+It is inspired by the developer experience of FastAPI, but it is not a web framework. FastAPI turns Python type hints into a public HTTP API contract. UseCaseAPI turns Python type definitions into public contracts for your application layer, without forcing HTTP, RPC, serialization, or a dependency-injection container into the hot path.
+
+UseCaseAPI is designed for applications with many internal use case nodes: workflow-like systems, ROS-like node composition, AI-agent tool surfaces, batch workers, CLIs, FastAPI/Django backends, and systems where AI-assisted coding makes accidental breaking changes easier than before.
+
+## What it gives you
+
+- Code-first usecase contracts using `Protocol`, `Model`, and normal Python exceptions.
+- Same-process direct calls with no JSON serialization in the hot path.
+- Explicit binding from contract token to implementation factory.
+- Declared usecase dependency graph with strict undeclared-call protection.
+- Versioned contract identity: `name@vN`.
+- Contract snapshots, conservative diffing, Markdown docs, Mermaid graph export, and CLI scaffolding.
+- No DI container, no transaction manager, no HTTP/RPC runtime.
+
+## Install
+
+```bash
+uv add usecaseapi
+```
+
+For local development:
+
+```bash
+uv sync --extra dev
+uv run pytest
+uv run mypy
+uv run ruff check .
+```
+
+Python support: 3.12, 3.13, and 3.14. Pydantic v2 is required.
+
+## Quick example
+
+Define a contract:
+
+```python
+from __future__ import annotations
+
+from typing import ClassVar, Literal, Protocol
+
+from usecaseapi import Contract, Model, UseCase, UseCaseError, UseCaseRef, define_usecase
+
+
+class Input(Model):
+    user_id: str
+    sku_id: str
+    quantity: int
+
+
+class Output(Model):
+    order_id: str
+    status: Literal["accepted"]
+
+
+class PlaceOrderError(UseCaseError):
+    code: ClassVar[str] = "orders.place_order"
+
+
+class InventoryShortage(PlaceOrderError):
+    code: ClassVar[str] = "orders.place_order.inventory_shortage"
+
+    def __init__(self, *, sku_id: str, requested: int, available: int) -> None:
+        self.sku_id = sku_id
+        self.requested = requested
+        self.available = available
+        super().__init__(
+            f"inventory shortage: sku_id={sku_id}, requested={requested}, available={available}"
+        )
+
+
+class PlaceOrder(UseCase[Input, Output], Protocol):
+    async def __call__(self, input: Input, /) -> Output:
+        ...
+
+
+PLACE_ORDER: UseCaseRef[Input, Output] = define_usecase(
+    PlaceOrder,
+    Contract(
+        name="orders.place_order",
+        version=1,
+        input=Input,
+        output=Output,
+        raises=(PlaceOrderError,),
+        known_errors=(InventoryShortage,),
+    ),
+)
+```
+
+Implement it:
+
+```python
+from app.contracts.orders.place_order.v1 import Input, Output, PlaceOrder
+
+
+class PlaceOrderImpl:
+    async def __call__(self, input: Input, /) -> Output:
+        return Output(order_id="ord_123", status="accepted")
+
+
+_impl: PlaceOrder = PlaceOrderImpl()
+```
+
+Bind and call it:
+
+```python
+from dataclasses import dataclass
+
+from usecaseapi import UseCaseAPI
+
+
+@dataclass(frozen=True)
+class AppContext:
+    tenant_id: str
+
+
+usecases = UseCaseAPI[AppContext]()
+usecases.bind(PLACE_ORDER, lambda caller: PlaceOrderImpl())
+
+output = await usecases.caller(AppContext(tenant_id="t1")).call(PLACE_ORDER, input)
+```
+
+## Scaffold
+
+```bash
+usecaseapi scaffold orders.place_order --version 1
+
+# Create the next major contract version by scanning app/contracts/orders/place_order/v*.py
+usecaseapi scaffold orders.place_order --next
+```
+
+This creates:
+
+```text
+app/contracts/orders/place_order/v1.py
+app/usecases/orders/place_order.py
+tests/test_orders_place_order_v1.py
+```
+
+## Why not just write classes yourself?
+
+You can, and for small projects you should. UseCaseAPI becomes useful when you have many internal nodes and you need to know:
+
+- which functions are public application-layer contracts;
+- which version each caller depends on;
+- which usecase dependencies are allowed;
+- which domain exceptions are part of the contract;
+- whether AI-assisted changes silently broke a stable contract;
+- what the application graph looks like.
+
+UseCaseAPI is a small runtime plus guardrails for that problem.

usecaseapi-1.0.0/RELEASE.md

@@ -0,0 +1,59 @@
+# Release Process
+
+UseCaseAPI uses uv for packaging and GitHub Actions for publishing to PyPI.
+
+## Local release validation
+
+Run the same checks the release workflow runs before creating a tag:
+
+```bash
+uv sync --extra dev
+uv run coverage run -m pytest
+uv run coverage report -m
+uv run mypy
+uv run ruff check .
+uv build
+uv run twine check dist/*
+uv run --isolated --no-project --with dist/*.whl scripts/verify_distribution.py
+uv run --isolated --no-project --with dist/*.tar.gz scripts/verify_distribution.py
+```
+
+The distribution verification script imports the installed package, calls a real usecase, and checks that the `usecaseapi` CLI can create a versioned scaffold.
+
+## Versioning
+
+Version numbers follow semantic versioning. Contract-runtime behavior changes require careful release notes because downstream applications may rely on strict guardrail behavior.
+
+`pyproject.toml` `[project].version` is the release source of truth.
+
+The `src/usecaseapi/__init__.py` module intentionally does not define
+`__version__`; installed package metadata is the source for published versions.
+
+## Publishing
+
+Publishing is handled by `.github/workflows/release.yml`.
+
+On `main`, the workflow detects changes to `pyproject.toml` `[project].version`,
+validates the package, creates the annotated `v{version}` tag, and publishes to
+PyPI. Pushing a matching `v*` tag or running the workflow manually also publishes
+the current package version.
+
+The workflow expects PyPI Trusted Publishing:
+
+- GitHub environment: `pypi`
+- Repository owner: `Wisteria30`
+- Repository name: `usecaseapi`
+- Workflow filename: `release.yml`
+
+The workflow uses GitHub OIDC and `uv publish`; no PyPI API token should be stored in repository secrets.
+
+## Human release checklist
+
+1. Confirm the package name `usecaseapi` is still available on PyPI and TestPyPI.
+2. Create or log in to the PyPI account that will own the project.
+3. Configure PyPI Trusted Publishing for this repository and workflow.
+4. Create the `pypi` GitHub environment and require approval if desired.
+5. Review the generated package metadata and README rendering locally.
+6. Update `pyproject.toml` `[project].version` and changelog or GitHub release notes.
+7. Merge the version bump to `main`; GitHub Actions creates the annotated tag and publishes.
+8. Confirm the GitHub Actions release workflow completed and the PyPI project page is correct.

usecaseapi-1.0.0/SECURITY.md

@@ -0,0 +1,7 @@
+# Security Policy
+
+UseCaseAPI is a local contract runtime. It does not expose a network listener or authentication system.
+
+Please report security issues privately to the maintainers before public disclosure. Include reproduction steps, affected versions, and potential impact.
+
+Do not use public issues for vulnerabilities until a fix or mitigation is available.

usecaseapi-1.0.0/docs/agent-tools.md

@@ -0,0 +1,15 @@
+# AI Agent Tool Catalogs
+
+UseCaseAPI can describe internal tools without turning them into HTTP endpoints.
+
+Use `snapshot_from_api(api)` to list:
+
+- contract name and version;
+- input and output model schema;
+- public error boundary;
+- known leaf errors;
+- declared graph edges.
+
+This is useful for agent runtimes that need a tool surface. The runtime can map selected tools back to same-process `caller.call(USECASE_REF, input)` calls.
+
+UseCaseAPI does not directly integrate with any LLM vendor. It provides a stable contract catalog that an adapter can consume.

usecaseapi-1.0.0/docs/api-reference.md

@@ -0,0 +1,79 @@
+# API Reference
+
+## `Model`
+
+Base class for contract input and output objects. It extends Pydantic v2 `BaseModel` with `extra="forbid"` and `frozen=True`.
+
+## `UseCaseError`
+
+Base class for domain errors that are part of public usecase contracts. Subclasses should define a stable `code: ClassVar[str]`.
+
+```python
+class PlaceOrderError(UseCaseError):
+    code: ClassVar[str] = "orders.place_order"
+```
+
+## `UseCase[InputT, OutputT]`
+
+Structural Protocol for async callable usecase implementations.
+
+```python
+class PlaceOrder(UseCase[Input, Output], Protocol):
+    async def __call__(self, input: Input, /) -> Output:
+        ...
+```
+
+## `Contract`
+
+Runtime metadata for a contract.
+
+Important fields:
+
+- `name`: stable dotted name.
+- `version`: major version integer.
+- `input`: input model class.
+- `output`: output model class.
+- `raises`: public exception handling boundary.
+- `known_errors`: documented leaf errors.
+- `stable`: whether the contract is stable.
+- `deprecated`: whether new code should avoid it.
+- `superseded_by`: replacement key, if any.
+
+## `define_usecase(protocol, contract)`
+
+Creates a typed `UseCaseRef` token.
+
+## `UseCaseAPI[ContextT]`
+
+Registry and runtime.
+
+```python
+api = UseCaseAPI[AppContext]()
+api.register(PLACE_ORDER)
+api.bind(PLACE_ORDER, lambda caller: PlaceOrderImpl())
+api.validate()
+caller = api.caller(context)
+```
+
+## `Caller[ContextT]`
+
+Context-bound call surface.
+
+```python
+output = await caller.call(PLACE_ORDER, input)
+results = await caller.gather(caller.call(A, a), caller.call(B, b))
+```
+
+`Caller.gather` uses `asyncio.TaskGroup`, so multiple failures preserve Python `ExceptionGroup` behavior.
+
+## `snapshot_from_api(api)`
+
+Creates a JSON-serializable snapshot for CI and docs.
+
+## `diff_snapshots(old, new)`
+
+Performs conservative breaking-change detection.
+
+## `render_markdown(api)` / `render_mermaid(api)`
+
+Renders human-readable docs and graph diagrams.

usecaseapi-1.0.0/docs/design.md

@@ -0,0 +1,53 @@
+# Design
+
+UseCaseAPI is built around one idea: a usecase should be treated as a versioned application API even when it is only called inside the same process.
+
+## Core principles
+
+1. **Python code is the source of truth.** Contracts are ordinary Python modules. No external IDL is required.
+2. **Protocol-first.** The callable shape is represented by `typing.Protocol`, not by decorators or subclassing requirements.
+3. **Exceptions are exceptions.** Domain errors are real `Exception` subclasses, so stack traces, inheritance, `except`, `except*`, and `ExceptionGroup` remain useful.
+4. **No DI container.** Host frameworks decide where request context, database sessions, transactions, tenants, actors, and credentials are created.
+5. **Same-process direct calls.** UseCaseAPI does not introduce HTTP, RPC, queues, or JSON serialization into the hot path.
+6. **Graph-aware.** Large systems need declared usecase dependencies, graph export, snapshots, and breaking-change detection.
+
+## The contract shape
+
+A contract module contains:
+
+- `Input`: a Pydantic v2 model.
+- `Output`: a Pydantic v2 model.
+- a base domain exception derived from `UseCaseError`.
+- optional leaf domain exceptions.
+- a `Protocol` derived from `UseCase[Input, Output]`.
+- a `UseCaseRef` token created by `define_usecase`.
+
+The `UseCaseRef` is used for binding and calling. It carries runtime metadata while preserving type information.
+
+## Why not store metadata on the Protocol?
+
+Putting metadata directly on the Protocol would make structural implementations appear to require those metadata attributes. UseCaseAPI keeps the Protocol pure and attaches runtime metadata to the `UseCaseRef` token instead.
+
+## Dependency composition
+
+UseCaseAPI does not construct dependency graphs. A binding is a function:
+
+```python
+Callable[[Caller[ContextT]], UseCase[InputT, OutputT]]
+```
+
+The host application controls the `ContextT` object. A FastAPI app may put request-scoped state there. A Django app may use middleware-created state. A worker may use job context. An AI agent runtime may use agent session context.
+
+## Declared usecase graph
+
+A usecase binding can declare which other usecases it may call:
+
+```python
+usecases.bind(CHECKOUT, lambda caller: CheckoutImpl(caller), uses=(PLACE_ORDER,))
+```
+
+In strict mode, calling an undeclared usecase from inside a handler raises `UndeclaredUseCaseDependencyError`.
+
+## Version identity
+
+A contract identity is `name@vN`, for example `orders.place_order@v1`. There is no implicit `latest`. Callers import the version they use.

usecaseapi-1.0.0/docs/integrations.md

@@ -0,0 +1,33 @@
+# Integrations
+
+UseCaseAPI is intentionally runtime-agnostic.
+
+## FastAPI
+
+```python
+@app.post("/orders")
+async def endpoint(input: Input, request: Request) -> Output:
+    ctx = AppContext(session=request.state.session, actor=request.state.actor)
+    return await usecases.caller(ctx).call(PLACE_ORDER, input)
+```
+
+FastAPI remains responsible for request lifecycle, dependency injection, authentication, and transaction setup.
+
+## Django
+
+```python
+async def view(request: HttpRequest) -> JsonResponse:
+    ctx = AppContext(request=request)
+    output = await usecases.caller(ctx).call(PLACE_ORDER, input)
+    return JsonResponse(output.model_dump())
+```
+
+Django middleware and transaction management remain outside UseCaseAPI.
+
+## Workers and CLIs
+
+Create a context at job or command start, then call usecases through the caller.
+
+## AI agents
+
+UseCaseAPI contracts can be exported as a catalog for an agent runtime. The catalog is documentation and selection metadata; it is not the source of truth.