diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 357c740..550bd37 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -24,8 +24,12 @@ jobs: with: python-version: "3.13" enable-cache: false + - run: python3 -m unittest discover -s tests + env: + PYTHONDONTWRITEBYTECODE: "1" - run: python3 scripts/check_evidence.py - run: python3 scripts/export_compatibility.py --check + - run: python3 scripts/export_profile.py --check - run: python3 scripts/check_links.py - run: bash scripts/check_start.sh diff --git a/data/ecosystem.toml b/data/ecosystem.toml index 0b8f0dd..907fbb3 100644 --- a/data/ecosystem.toml +++ b/data/ecosystem.toml @@ -4,6 +4,13 @@ mcp_revision = "2025-11-25" openapi_revision = "3.1.1" minimum_python = "3.12" +[profile_evidence] +as_of = "2026-07-28" +commit = "9e27b0191c7fa9f920ad6fe5b126e190268afba2" +benchmark_path = "benchmarks/competitive/results/2026-07-28-hayate-0.15.1-macos-arm64.json" +benchmark_result_commit = "561bcf01874e7777b04917ff84e683afff264180" +capabilities_path = "benchmarks/competitive/capabilities.json" + [sources.golden_app] label = "golden-app main CI" url = "https://github.com/hayatepy/golden-app/actions/runs/30315193937" diff --git a/profile/README.md b/profile/README.md index 57732f7..e1a02ce 100644 --- a/profile/README.md +++ b/profile/README.md @@ -1,3 +1,5 @@ + + # hayatepy **Web-standards-first Python for applications that run across ASGI, Cloudflare @@ -11,7 +13,8 @@ logic on a conventional Python server or directly inside Cloudflare workerd. 1. Follow the [single quickstart](https://github.com/hayatepy/.github/blob/main/docs/START.md). 2. Use the [executable production golden app](https://github.com/hayatepy/golden-app) - for Cloudflare Access, OpenAPI, MCP, checked SQL, SQLite/D1, and deployment. + for Cloudflare Access, OpenAPI, MCP, checked SQL, operational administration, + SQLite/D1, and deployment. 3. Check the [generated compatibility evidence](https://github.com/hayatepy/.github/blob/main/docs/COMPATIBILITY.md) before selecting versions or runtimes. @@ -22,35 +25,53 @@ contract through the bounded ## Why Hayate Hayate is strongest when one Python application must combine typed HTTP, -MCP, authorization, and checked data access across conventional ASGI servers -and native Cloudflare Workers. +MCP, authorization, and checked data access across conventional ASGI servers, +native Cloudflare Workers, and AWS Lambda. -The recorded 2026-07-27 same-workload HTTP baseline measured: +The recorded 2026-07-28 same-workload HTTP baseline measured: -| Boundary | Hayate 0.12.1 | FastAPI 0.140.0 | Django 6.0.7 | Hono 4.12.32 | +| Boundary | Hayate 0.15.1 | FastAPI 0.140.0 | Django 6.0.7 | Hono 4.12.32 | |---|---:|---:|---:|---:| -| Cold start | 130.3 ms | 220.5 ms | 155.5 ms | **55.0 ms** | +| Cold start | 149.0 ms | 471.4 ms | 392.6 ms | **61.3 ms** | | Production packages | 5 | 13 | 6 | **2** | -| gzip payload | 287.5 KiB | 2,802.1 KiB | 5,147.1 KiB | **281.5 KiB** | -| Throughput | 13,995 req/s | 10,161 req/s | 2,719 req/s | **63,198 req/s** | +| gzip payload | 298.1 KiB | 2,802.2 KiB | 5,147.2 KiB | **281.5 KiB** | +| Throughput | 14,906 req/s | 10,086 req/s | 2,557 req/s | **59,187 req/s** | | Common HTTP contract | **14/14** | 12/14 | 12/14 | 12/14 | -On this workload Hayate delivered 1.38x FastAPI's and 5.15x Django's -throughput. Hono delivered 4.52x Hayate's throughput and retained the best -startup result. The 14-point contract is a shared-workload result, not a -universal standards score. - -Feature breadth is evaluated separately and without a weighted winner. Hayate -is advantaged for a portable Python agent API; FastAPI remains competitive for -conventional typed Python APIs; Django retains integrated admin, ORM, -migrations, forms, and templates; Hono retains broad JavaScript-runtime -portability and route-inferred TypeScript RPC. +On this workload Hayate delivered 1.48x FastAPI's and 5.83x Django's throughput. Hono +delivered 3.97x Hayate's throughput and retained the best startup, dependency-count, and +deployment-payload results. + +The 14-point contract is a shared-workload result, not a universal standards +score. Feature breadth is evaluated separately and without a weighted winner: + +- **Portable Python agent API — Hayate advantaged.** Hayate has the clearest first-party + path when one Python application must run on ASGI, native Cloudflare Workers, and + buffered or response-streaming AWS Lambda HTTP payload v2 while combining typed HTTP + contracts, cached dependency graphs, MCP 2025-11-25, authorization, and checked + SQLite/D1 access. +- **Conventional typed Python API — competitive.** Hayate now meets FastAPI's central + typed request/response, OpenAPI, dependency-graph, direct-test, realtime, lifecycle, + and sub-application composition capabilities. FastAPI retains a much larger adoption + ecosystem; that is a material adoption advantage, not a missing Hayate endpoint + feature. +- **Traditional database-backed full stack — competitor advantaged.** Django remains + functionally ahead for its model-driven ORM/migrations, integrated forms/templates, + bundled localization breadth, and mature extension ecosystem. Hayate now has a + first-party explicit operational admin with bounded CRUD, bulk actions, redacted + history, searchable relationships, inline editing, saved views, keyset continuations, + bounded CSV export, application-scoped localization, constrained branding, and a + real-browser accessibility audit on SQLite and native Workers/D1, while retaining a + Django admin/ORM application under an ASGI prefix during incremental migration. +- **JavaScript and TypeScript edge application — competitor advantaged.** Hono remains + functionally ahead for multi-JavaScript-runtime reach and route-inferred TypeScript + RPC, and its JavaScript Workers runtime has materially better startup, memory, CPU, + and upload size than Python Workers. Read the -[reproducible benchmark](https://github.com/hayatepy/hayate/blob/main/docs/benchmarks.md) -and the dated, source-backed -[capability matrix](https://github.com/hayatepy/hayate/blob/main/docs/capabilities.md) -for methodology, raw artifacts, profile verdicts, and limitations. +[immutable benchmark publication](https://github.com/hayatepy/hayate/blob/9e27b0191c7fa9f920ad6fe5b126e190268afba2/benchmarks/competitive/results/2026-07-28-hayate-0.15.1-macos-arm64.md) and the dated, source-backed +[capability matrix](https://github.com/hayatepy/hayate/blob/9e27b0191c7fa9f920ad6fe5b126e190268afba2/docs/capabilities.md) for methodology, raw artifacts, +profile verdicts, and limitations. ## Choose by outcome @@ -67,7 +88,8 @@ for methodology, raw artifacts, profile verdicts, and limitations. ## Evidence, not platform claims - The golden app runs direct tests, a real Uvicorn/SQLite flow, and a real - workerd/D1 flow. HTTP, identity, OpenAPI, and MCP share one application core. + workerd/D1 flow. HTTP, identity, OpenAPI, MCP, and operational admin share + one application core. - The core compatibility gate installs an unpublished Hayate wheel into auth, fetch, MCP, OpenAPI, and generated application repositories before release. - The feature-complete Workers default is a `WorkerEntrypoint` class. The diff --git a/profile/README.md.in b/profile/README.md.in new file mode 100644 index 0000000..a72117a --- /dev/null +++ b/profile/README.md.in @@ -0,0 +1,76 @@ +# hayatepy + +**Web-standards-first Python for applications that run across ASGI, Cloudflare +Workers, and AWS Lambda.** + +Hayate keeps one WHATWG `Request`/`Response` application core while runtime +adapters and optional features are mounted around it. Use the same application +logic on a conventional Python server or directly inside Cloudflare workerd. + +## Start here + +1. Follow the [single quickstart](https://github.com/hayatepy/.github/blob/main/docs/START.md). +2. Use the [executable production golden app](https://github.com/hayatepy/golden-app) + for Cloudflare Access, OpenAPI, MCP, checked SQL, operational administration, + SQLite/D1, and deployment. +3. Check the [generated compatibility evidence](https://github.com/hayatepy/.github/blob/main/docs/COMPATIBILITY.md) + before selecting versions or runtimes. + +Building a real API, MCP backend, or Workers application? Help shape the v1 +contract through the bounded +[design-partner program](https://github.com/hayatepy/.github/blob/main/docs/DESIGN_PARTNERS.md). + +## Why Hayate + +Hayate is strongest when one Python application must combine typed HTTP, +MCP, authorization, and checked data access across conventional ASGI servers, +native Cloudflare Workers, and AWS Lambda. + +The recorded ${benchmark_date} same-workload HTTP baseline measured: + +${benchmark_table} + +${benchmark_summary} + +The 14-point contract is a shared-workload result, not a universal standards +score. Feature breadth is evaluated separately and without a weighted winner: + +${profile_verdicts} + +Read the +[immutable benchmark publication](${benchmark_url}) and the dated, source-backed +[capability matrix](${capabilities_url}) for methodology, raw artifacts, +profile verdicts, and limitations. + +## Choose by outcome + +| I want to… | Start with | +|---|---| +| Build a web API on ASGI, Workers, or Lambda | [`hayate`](https://github.com/hayatepy/hayate) | +| Generate OpenAPI 3.1 and typed clients | [`hayate-openapi`](https://github.com/hayatepy/hayate-openapi) | +| Expose MCP 2025-11-25 tools | [`hayate-mcp`](https://github.com/hayatepy/hayate-mcp) | +| Add sessions, API keys, OAuth, or an authorization server | [`hayate-auth`](https://github.com/hayatepy/hayate-auth) | +| Use checked SQL with PostgreSQL, SQLite, or D1 | [`hayate-sql`](https://github.com/hayatepy/hayate-sql) | +| Make portable outbound requests | [`hayate-fetch`](https://github.com/hayatepy/hayate-fetch) | +| Generate an integrated application | [`create-hayate`](https://github.com/hayatepy/create-hayate) | + +## Evidence, not platform claims + +- The golden app runs direct tests, a real Uvicorn/SQLite flow, and a real + workerd/D1 flow. HTTP, identity, OpenAPI, MCP, and operational admin share + one application core. +- The core compatibility gate installs an unpublished Hayate wheel into auth, + fetch, MCP, OpenAPI, and generated application repositories before release. +- The feature-complete Workers default is a `WorkerEntrypoint` class. The + optional global handler is an explicitly HTTP-only compatibility mode. +- Public releases include locked inputs, SPDX SBOMs, and GitHub attestations. + +All packages are pre-1.0. Use the compatibility page for the exact evidence +snapshot rather than assuming every pre-1.0 line can be mixed freely. + +## Contributing and security + +See the organization-wide +[contributing guide](https://github.com/hayatepy/.github/blob/main/CONTRIBUTING.md). +Report vulnerabilities privately through the affected repository's +**Security → Report a vulnerability** flow. diff --git a/scripts/export_profile.py b/scripts/export_profile.py new file mode 100644 index 0000000..13f5afc --- /dev/null +++ b/scripts/export_profile.py @@ -0,0 +1,296 @@ +"""Generate the organization profile from immutable competitive evidence.""" + +from __future__ import annotations + +import argparse +import json +import textwrap +from pathlib import Path +from string import Template +from typing import Any +from urllib.request import urlopen + +import tomllib + +ROOT = Path(__file__).resolve().parents[1] +MANIFEST = ROOT / "data" / "ecosystem.toml" +TEMPLATE = ROOT / "profile" / "README.md.in" +OUTPUT = ROOT / "profile" / "README.md" + +FRAMEWORK_ORDER = ("hayate", "fastapi", "django", "hono") +FRAMEWORK_NAMES = { + "hayate": "Hayate", + "fastapi": "FastAPI", + "django": "Django", + "hono": "Hono", +} +PROFILE_ORDER = ( + "portable_agent_api", + "typed_python_api", + "traditional_full_stack", + "javascript_edge", +) +PROFILE_POSITIONS = { + "portable_agent_api": "advantaged", + "typed_python_api": "competitive", + "traditional_full_stack": "competitor_advantaged", + "javascript_edge": "competitor_advantaged", +} +POSITION_LABELS = { + "advantaged": "Hayate advantaged", + "competitive": "competitive", + "competitor_advantaged": "competitor advantaged", +} + + +def _fetch_json(url: str) -> dict[str, Any]: + with urlopen(url, timeout=30) as response: + value = json.load(response) + if not isinstance(value, dict): + raise ValueError(f"expected a JSON object from {url}") + return value + + +def _source_url(commit: str, path: str, *, raw: bool) -> str: + host = "raw.githubusercontent.com" if raw else "github.com" + middle = "" if raw else "blob/" + return f"https://{host}/hayatepy/hayate/{middle}{commit}/{path}" + + +def _load() -> tuple[dict[str, Any], dict[str, Any], dict[str, str]]: + manifest = tomllib.loads(MANIFEST.read_text(encoding="utf-8")) + source = manifest["profile_evidence"] + commit = source["commit"] + benchmark_path = source["benchmark_path"] + capabilities_path = source["capabilities_path"] + benchmark = _fetch_json(_source_url(commit, benchmark_path, raw=True)) + capabilities = _fetch_json(_source_url(commit, capabilities_path, raw=True)) + _validate(benchmark, capabilities, source) + links = { + "benchmark_url": _source_url( + commit, + str(Path(benchmark_path).with_suffix(".md")), + raw=False, + ), + "capabilities_url": _source_url( + commit, + "docs/capabilities.md", + raw=False, + ), + } + return benchmark, capabilities, links + + +def _validate( + benchmark: dict[str, Any], + capabilities: dict[str, Any], + source: dict[str, Any], +) -> None: + if benchmark.get("schema_version") != 2: + raise ValueError("unsupported competitive benchmark schema") + if benchmark.get("git_commit") != source["benchmark_result_commit"]: + raise ValueError("competitive benchmark result commit does not match manifest") + frameworks = benchmark.get("frameworks") + if not isinstance(frameworks, dict) or set(frameworks) != set(FRAMEWORK_ORDER): + raise ValueError("competitive benchmark must contain exactly four frameworks") + + for framework_id in FRAMEWORK_ORDER: + row = frameworks[framework_id] + required = ( + row.get("payload", {}).get("framework_version"), + row.get("payload", {}).get("production_packages"), + row.get("payload", {}).get("production_payload_gzip_bytes"), + row.get("startup", {}).get("cold_start_ms"), + row.get("throughput", {}).get("geometric_mean_requests_per_second"), + row.get("http_contract", {}).get("passed"), + row.get("http_contract", {}).get("total"), + ) + if any(value is None for value in required): + raise ValueError(f"incomplete benchmark row for {framework_id}") + + if capabilities.get("schema_version") != 1: + raise ValueError("unsupported capability schema") + if capabilities.get("as_of") != source["as_of"]: + raise ValueError("capability evidence date does not match manifest") + if capabilities.get("universal_winner") is not None: + raise ValueError("organization profile must not publish a universal winner") + profiles = { + profile["id"]: profile + for profile in capabilities.get("profiles", []) + if isinstance(profile, dict) and "id" in profile + } + if set(profiles) != set(PROFILE_ORDER): + raise ValueError("capability evidence must contain exactly four profiles") + for profile_id, expected_position in PROFILE_POSITIONS.items(): + profile = profiles[profile_id] + if profile.get("position") != expected_position: + raise ValueError(f"unexpected position for profile {profile_id}") + if not profile.get("title") or not profile.get("summary"): + raise ValueError(f"incomplete capability profile {profile_id}") + + +def _best(values: dict[str, float], *, higher: bool) -> set[str]: + target = (max if higher else min)(values.values()) + return {key for key, value in values.items() if value == target} + + +def _emphasize(value: str, framework_id: str, best: set[str]) -> str: + return f"**{value}**" if framework_id in best else value + + +def _benchmark_table(benchmark: dict[str, Any]) -> str: + frameworks = benchmark["frameworks"] + cold = { + key: float(frameworks[key]["startup"]["cold_start_ms"]) + for key in FRAMEWORK_ORDER + } + packages = { + key: float(frameworks[key]["payload"]["production_packages"]) + for key in FRAMEWORK_ORDER + } + gzip = { + key: float(frameworks[key]["payload"]["production_payload_gzip_bytes"]) + for key in FRAMEWORK_ORDER + } + throughput = { + key: float(frameworks[key]["throughput"]["geometric_mean_requests_per_second"]) + for key in FRAMEWORK_ORDER + } + contract = { + key: ( + float(frameworks[key]["http_contract"]["passed"]) + / float(frameworks[key]["http_contract"]["total"]) + ) + for key in FRAMEWORK_ORDER + } + best = { + "cold": _best(cold, higher=False), + "packages": _best(packages, higher=False), + "gzip": _best(gzip, higher=False), + "throughput": _best(throughput, higher=True), + "contract": _best(contract, higher=True), + } + headers = " | ".join( + f"{FRAMEWORK_NAMES[key]} {frameworks[key]['payload']['framework_version']}" + for key in FRAMEWORK_ORDER + ) + + def cells(metric: str, render: Any) -> str: + values = { + "cold": cold, + "packages": packages, + "gzip": gzip, + "throughput": throughput, + }[metric] + return " | ".join( + _emphasize(render(values[key]), key, best[metric]) + for key in FRAMEWORK_ORDER + ) + + contract_cells = " | ".join( + _emphasize( + f"{frameworks[key]['http_contract']['passed']}/" + f"{frameworks[key]['http_contract']['total']}", + key, + best["contract"], + ) + for key in FRAMEWORK_ORDER + ) + return "\n".join( + [ + f"| Boundary | {headers} |", + "|---|---:|---:|---:|---:|", + f"| Cold start | {cells('cold', lambda value: f'{value:.1f} ms')} |", + f"| Production packages | {cells('packages', lambda value: f'{value:.0f}')} |", + f"| gzip payload | {cells('gzip', lambda value: f'{value / 1024:,.1f} KiB')} |", + f"| Throughput | {cells('throughput', lambda value: f'{value:,.0f} req/s')} |", + f"| Common HTTP contract | {contract_cells} |", + ] + ) + + +def _benchmark_summary(benchmark: dict[str, Any]) -> str: + frameworks = benchmark["frameworks"] + + def throughput(framework_id: str) -> float: + return float( + frameworks[framework_id]["throughput"]["geometric_mean_requests_per_second"] + ) + + hayate = throughput("hayate") + fastapi = throughput("fastapi") + django = throughput("django") + hono = throughput("hono") + return textwrap.fill( + f"On this workload Hayate delivered {hayate / fastapi:.2f}x FastAPI's " + f"and {hayate / django:.2f}x Django's throughput. Hono delivered " + f"{hono / hayate:.2f}x Hayate's throughput and retained the best " + "startup, dependency-count, and deployment-payload results.", + width=88, + break_long_words=False, + break_on_hyphens=False, + ) + + +def _profile_verdicts(capabilities: dict[str, Any]) -> str: + profiles = {profile["id"]: profile for profile in capabilities["profiles"]} + return "\n".join( + textwrap.fill( + f"**{profiles[profile_id]['title']} — " + f"{POSITION_LABELS[profiles[profile_id]['position']]}.** " + f"{profiles[profile_id]['summary']}", + width=88, + initial_indent="- ", + subsequent_indent=" ", + break_long_words=False, + break_on_hyphens=False, + ) + for profile_id in PROFILE_ORDER + ) + + +def _render( + benchmark: dict[str, Any], + capabilities: dict[str, Any], + links: dict[str, str], + *, + benchmark_date: str, +) -> str: + template = Template(TEMPLATE.read_text(encoding="utf-8")) + body = template.substitute( + benchmark_date=benchmark_date, + benchmark_table=_benchmark_table(benchmark), + benchmark_summary=_benchmark_summary(benchmark), + profile_verdicts=_profile_verdicts(capabilities), + **links, + ) + return ( + "\n\n" + f"{body.rstrip()}\n" + ) + + +def main() -> int: + parser = argparse.ArgumentParser() + parser.add_argument("--check", action="store_true") + args = parser.parse_args() + manifest = tomllib.loads(MANIFEST.read_text(encoding="utf-8")) + benchmark, capabilities, links = _load() + expected = _render( + benchmark, + capabilities, + links, + benchmark_date=manifest["profile_evidence"]["as_of"], + ) + if args.check: + if not OUTPUT.exists() or OUTPUT.read_text(encoding="utf-8") != expected: + parser.error( + "profile/README.md is stale; run python3 scripts/export_profile.py" + ) + return 0 + OUTPUT.write_text(expected, encoding="utf-8", newline="\n") + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/tests/test_export_profile.py b/tests/test_export_profile.py new file mode 100644 index 0000000..643c017 --- /dev/null +++ b/tests/test_export_profile.py @@ -0,0 +1,122 @@ +from __future__ import annotations + +import copy +import sys +import unittest +from pathlib import Path + +sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "scripts")) + +import export_profile + + +def benchmark() -> dict[str, object]: + frameworks: dict[str, object] = {} + values = { + "hayate": ("0.15.1", 149.0, 5, 305273, 14906.4, 14), + "fastapi": ("0.140.0", 471.4, 13, 2869443, 10086.4, 12), + "django": ("6.0.7", 392.6, 6, 5270712, 2557.4, 12), + "hono": ("4.12.32", 61.3, 2, 288207, 59187.4, 12), + } + for name, ( + version, + cold_start, + packages, + gzip_bytes, + throughput, + passed, + ) in values.items(): + frameworks[name] = { + "payload": { + "framework_version": version, + "production_packages": packages, + "production_payload_gzip_bytes": gzip_bytes, + }, + "startup": {"cold_start_ms": cold_start}, + "throughput": {"geometric_mean_requests_per_second": throughput}, + "http_contract": {"passed": passed, "total": 14}, + } + return { + "schema_version": 2, + "git_commit": "result", + "frameworks": frameworks, + } + + +def capabilities() -> dict[str, object]: + positions = { + "portable_agent_api": "advantaged", + "typed_python_api": "competitive", + "traditional_full_stack": "competitor_advantaged", + "javascript_edge": "competitor_advantaged", + } + return { + "schema_version": 1, + "as_of": "2026-07-28", + "universal_winner": None, + "profiles": [ + { + "id": profile_id, + "title": profile_id.replace("_", " ").title(), + "position": position, + "summary": f"{profile_id} evidence.", + } + for profile_id, position in positions.items() + ], + } + + +def source() -> dict[str, str]: + return { + "as_of": "2026-07-28", + "benchmark_result_commit": "result", + } + + +class ExportProfileTests(unittest.TestCase): + def test_renders_current_values_and_computed_ratios(self) -> None: + table = export_profile._benchmark_table(benchmark()) + summary = export_profile._benchmark_summary(benchmark()) + + self.assertIn("Hayate 0.15.1", table) + self.assertIn("**14/14**", table) + self.assertIn("**59,187 req/s**", table) + self.assertIn("1.48x FastAPI", summary) + self.assertIn("5.83x Django", summary) + self.assertIn("3.97x Hayate", summary) + + def test_uses_source_backed_profile_summaries(self) -> None: + rendered = export_profile._profile_verdicts(capabilities()) + + self.assertIn("Hayate advantaged", rendered) + self.assertIn("competitor advantaged", rendered) + self.assertIn("javascript_edge evidence.", rendered) + + def test_rejects_a_missing_framework(self) -> None: + value = benchmark() + del value["frameworks"]["hono"] # type: ignore[index] + + with self.assertRaisesRegex(ValueError, "exactly four frameworks"): + export_profile._validate(value, capabilities(), source()) + + def test_rejects_a_universal_winner(self) -> None: + value = capabilities() + value["universal_winner"] = "hayate" + + with self.assertRaisesRegex(ValueError, "universal winner"): + export_profile._validate(benchmark(), value, source()) + + def test_rejects_profile_position_drift(self) -> None: + value = capabilities() + profiles = value["profiles"] + assert isinstance(profiles, list) + changed = copy.deepcopy(profiles[0]) + changed["position"] = "competitive" + profiles[0] = changed + + with self.assertRaisesRegex(ValueError, "unexpected position"): + export_profile._validate(benchmark(), value, source()) + + +if __name__ == "__main__": + unittest.main()