arkhai-kit-site 0.3.0__tar.gz

arkhai_kit_site-0.3.0/.gitignore

@@ -0,0 +1,232 @@
+.vscode/
+
+# Project-local scratch files, private notes, and generated diagnostics.
+.scm-local/
+
+# Visible transfer staging for snap-confined tools such as Multipass.
+scm-clean-room-transfer/
+
+# Legacy local rehearsal params (private keys, RPC URLs, etc.).
+.rehearsal-params.local.md
+.rehearsal-params.local.*
+
+### Python ###
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+*.log.[0-9]*
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.env.*
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+### Python Patch ###
+# Poetry local configuration file - https://python-poetry.org/docs/configuration/#local-configuration
+poetry.toml
+
+# ruff
+.ruff_cache/
+
+# LSP config files
+pyrightconfig.json
+
+# Infra
+infra/*/*.tfvars
+infra/*/*.tfstate
+infra/*/*.tfstate.backup
+infra/*/.terraform*
+infra/*/*.plan
+*.db
+# PufferRL Experiments
+experiments/
+wandb/
+!.env.sample
+!.env.docker-compose
+!.env.*.docker-compose
+!.env.*.docker-compose
+!.env.docker-compose
+.cursor/
+
+# Cloud Function
+node_modules
+
+# Puffer artifacts — ignore any resources/ dir or symlink at any depth
+**/resources
+pr-message-puffer.md
+dev-env/state/state.json
+shared-env/*
+helm/Chart.lock
+helm/charts/*.tgz
+helm/.port-forward.pids
+provisioning-service/settings.local.toml
+provisioning-service/src/config/config-local.yml
+.snapshot/*
+
+# Per-env deployment scratch dirs (carry keys + per-env configs)
+deploy-base-sepolia/
+
+# Claude Code per-project state; shared skills are repository-owned.
+.claude/*
+!.claude/skills/
+!.claude/skills/**
+
+# Local assistant session exports
+omp-session-*.html
+pi-session-*.html
+
+# Local-only mise overrides (machine-specific paths).
+mise.local.toml

arkhai_kit_site-0.3.0/Makefile

@@ -0,0 +1,9 @@
+DIST_DIR ?= ../../.dist
+
+.PHONY: build test
+
+build: ## Build the wheel into the shared .dist/
+	uv build --wheel --out-dir $(DIST_DIR)
+
+test: ## Run the test suite
+	uv run --find-links $(DIST_DIR) pytest tests/unit -q

arkhai_kit_site-0.3.0/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.5
+Name: arkhai-kit-site
+Version: 0.3.0
+Summary: Site-authority scaffold: capacity ledger, tables, and HTTP surface
+License-Expression: MIT
+Requires-Python: >=3.12
+Requires-Dist: arkhai-kit-resource-pools>=0.2.0
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: pydantic>=2.7
+Requires-Dist: sqlalchemy>=2.0

arkhai_kit_site-0.3.0/pyproject.toml

@@ -0,0 +1,32 @@
+[project]
+name = "arkhai-kit-site"
+version = "0.3.0"
+license = "MIT"
+description = "Site-authority scaffold: capacity ledger, tables, and HTTP surface"
+requires-python = ">=3.12"
+dependencies = [
+    "arkhai-kit-resource-pools>=0.2.0",
+    "fastapi>=0.115.0",
+    "pydantic>=2.7",
+    "sqlalchemy>=2.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/market_site"]
+
+[tool.uv]
+find-links = ["../../.dist"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests/unit"]
+
+[dependency-groups]
+dev = [
+    "httpx2",
+    "pytest>=8.3.4,<9.0.0",
+]

arkhai_kit_site-0.3.0/src/market_site/__init__.py

@@ -0,0 +1,36 @@
+"""Site-authority scaffold: capacity ledger, tables, and HTTP surface.
+
+The shared half of a site-authority service
+(docs/development/ARCHITECTURE.md, "Capacity and the Site Authority"):
+the unit-counted resource ledger, reservation holds with their lease
+tail, the anonymous versioned capacity-event feed, and the
+``/capacity`` router mirroring the ``SiteCapacityAuthority`` contract. A
+hosting service (the VM provisioning service; the API-credits service)
+mounts the tables on its engine and the router on its app.
+"""
+
+from .authority import (  # noqa: F401
+    LedgerSiteAuthority,
+    SiteAuthorityLedger,
+    SiteAuthorityPort,
+)
+from .db import (  # noqa: F401
+    HELD_RESERVATION_STATES,
+    ReservationState,
+    Base,
+    CapacityEvent,
+    CapacityReservation,
+)
+from .ledger import (  # noqa: F401
+    CapacityConflictError,
+    EXECUTOR_KIND_CLAIM_KEY,
+    CapacityLedgerService,
+    dict_resource_satisfies_claim,
+    parse_utc,
+    ResourceFeasibilityView,
+    resource_feasibility_view,
+    resource_satisfies_requirement,
+    SettlementAbandonmentHook,
+    UndeclaredOfferingModeError,
+)
+from .router import make_capacity_router  # noqa: F401

arkhai_kit_site-0.3.0/src/market_site/authority.py

@@ -0,0 +1,233 @@
+"""Executor-neutral site authority port and ledger adapter."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any, Protocol
+
+
+class SiteAuthorityPort(Protocol):
+    """Reservation lifecycle facts consumed by compute orchestration."""
+
+    def list_reservations(self, *, state: str | None = None) -> list[dict[str, Any]]: ...
+
+    def list_time_bounded_reservations_due(self, now: datetime) -> list[dict[str, Any]]: ...
+
+    def get_reservation(self, capacity_reservation_id: str) -> dict[str, Any] | None: ...
+
+    def get_reservation_by_escrow(self, escrow_uid: str) -> dict[str, Any] | None: ...
+
+    def attach_lease_reservation(
+        self,
+        *,
+        capacity_reservation_id: str | None = None,
+        escrow_uid: str | None = None,
+        executor_kind: str | None = None,
+        executor_target: str | None = None,
+        executor_ref: dict[str, Any] | None = None,
+        lease_start_utc: str | None = None,
+        lease_end_utc: str | None = None,
+        create_job_id: str | None = None,
+    ) -> dict[str, Any] | None: ...
+
+    def update_reservation_fields(
+        self,
+        capacity_reservation_id: str,
+        *,
+        executor_kind: str | None = None,
+        executor_target: str | None = None,
+        executor_ref: dict[str, Any] | None = None,
+        lease_start_utc: str | None = None,
+        lease_end_utc: str | None = None,
+        release_job_id: str | None = None,
+        create_job_id: str | None = None,
+    ) -> dict[str, Any] | None: ...
+
+    def begin_release(
+        self, capacity_reservation_id: str, *, release_job_id: str
+    ) -> dict[str, Any] | None: ...
+
+    def record_release_failure(
+        self,
+        capacity_reservation_id: str,
+        *,
+        reason: str,
+        message: str | None = None,
+    ) -> dict[str, Any] | None: ...
+
+    def record_release_success(
+        self,
+        capacity_reservation_id: str,
+        *,
+        forced: bool = False,
+        reason: str | None = None,
+        message: str | None = None,
+    ) -> dict[str, Any] | None: ...
+
+    def record_unmanaged(
+        self, capacity_reservation_id: str, *, reason: str, message: str | None = None
+    ) -> dict[str, Any] | None: ...
+
+    def capacity_events_after(
+        self, after_version: int, *, limit: int = 500
+    ) -> tuple[list[dict[str, Any]], int]: ...
+
+
+class SiteAuthorityLedger(Protocol):
+    """Persistence operations supplied by the site ledger."""
+
+    def list_reservations(self, *, state: str | None = None) -> list[dict[str, Any]]: ...
+
+    def list_lease_due(self, now: datetime) -> list[dict[str, Any]]: ...
+
+    def get_reservation(self, capacity_reservation_id: str) -> dict[str, Any] | None: ...
+
+    def get_reservation_by_escrow(self, escrow_uid: str) -> dict[str, Any] | None: ...
+
+    def attach_lease(self, **fields: Any) -> dict[str, Any] | None: ...
+
+    def update_lease_fields(
+        self, capacity_reservation_id: str, **fields: Any
+    ) -> dict[str, Any] | None: ...
+
+    def begin_releasing(
+        self, capacity_reservation_id: str, *, release_job_id: str | None = None
+    ) -> dict[str, Any] | None: ...
+
+    def update_reservation_state(
+        self,
+        capacity_reservation_id: str,
+        *,
+        state: str,
+        failure_reason: str | None = None,
+        failure_message: str | None = None,
+    ) -> dict[str, Any] | None: ...
+
+    def release(
+        self,
+        *,
+        capacity_reservation_id: str,
+        state: str = "released",
+        failure_reason: str | None = None,
+        failure_message: str | None = None,
+    ) -> dict[str, Any] | None: ...
+
+    def events_after(
+        self, after_version: int, *, limit: int = 500
+    ) -> tuple[list[dict[str, Any]], int]: ...
+
+
+class LedgerSiteAuthority:
+    """Adapt the transactional site ledger to :class:`SiteAuthorityPort`."""
+
+    def __init__(self, ledger: SiteAuthorityLedger) -> None:
+        self._ledger = ledger
+
+    def list_reservations(self, *, state: str | None = None) -> list[dict[str, Any]]:
+        return self._ledger.list_reservations(state=state)
+
+    def list_time_bounded_reservations_due(self, now: datetime) -> list[dict[str, Any]]:
+        return self._ledger.list_lease_due(now)
+
+    def get_reservation(self, capacity_reservation_id: str) -> dict[str, Any] | None:
+        return self._ledger.get_reservation(capacity_reservation_id)
+
+    def get_reservation_by_escrow(self, escrow_uid: str) -> dict[str, Any] | None:
+        return self._ledger.get_reservation_by_escrow(escrow_uid)
+
+    def attach_lease_reservation(
+        self,
+        *,
+        capacity_reservation_id: str | None = None,
+        escrow_uid: str | None = None,
+        executor_kind: str | None = None,
+        executor_target: str | None = None,
+        executor_ref: dict[str, Any] | None = None,
+        lease_start_utc: str | None = None,
+        lease_end_utc: str | None = None,
+        create_job_id: str | None = None,
+    ) -> dict[str, Any] | None:
+        return self._ledger.attach_lease(
+            capacity_reservation_id=capacity_reservation_id,
+            escrow_uid=escrow_uid,
+            executor_kind=executor_kind,
+            executor_target=executor_target,
+            executor_ref=executor_ref,
+            lease_start_utc=lease_start_utc,
+            lease_end_utc=lease_end_utc,
+            create_job_id=create_job_id,
+        )
+
+    def update_reservation_fields(
+        self,
+        capacity_reservation_id: str,
+        *,
+        executor_kind: str | None = None,
+        executor_target: str | None = None,
+        executor_ref: dict[str, Any] | None = None,
+        lease_start_utc: str | None = None,
+        lease_end_utc: str | None = None,
+        release_job_id: str | None = None,
+        create_job_id: str | None = None,
+    ) -> dict[str, Any] | None:
+        return self._ledger.update_lease_fields(
+            capacity_reservation_id,
+            executor_kind=executor_kind,
+            executor_target=executor_target,
+            executor_ref=executor_ref,
+            lease_start_utc=lease_start_utc,
+            lease_end_utc=lease_end_utc,
+            release_job_id=release_job_id,
+            create_job_id=create_job_id,
+        )
+
+    def begin_release(
+        self, capacity_reservation_id: str, *, release_job_id: str
+    ) -> dict[str, Any] | None:
+        return self._ledger.begin_releasing(
+            capacity_reservation_id, release_job_id=release_job_id
+        )
+
+    def record_release_failure(
+        self,
+        capacity_reservation_id: str,
+        *,
+        reason: str,
+        message: str | None = None,
+    ) -> dict[str, Any] | None:
+        return self._ledger.update_reservation_state(
+            capacity_reservation_id,
+            state="release_failed",
+            failure_reason=reason,
+            failure_message=message,
+        )
+
+    def record_release_success(
+        self,
+        capacity_reservation_id: str,
+        *,
+        forced: bool = False,
+        reason: str | None = None,
+        message: str | None = None,
+    ) -> dict[str, Any] | None:
+        return self._ledger.release(
+            capacity_reservation_id=capacity_reservation_id,
+            state="force_released" if forced else "released",
+            failure_reason=reason,
+            failure_message=message,
+        )
+
+    def record_unmanaged(
+        self, capacity_reservation_id: str, *, reason: str, message: str | None = None
+    ) -> dict[str, Any] | None:
+        return self._ledger.update_reservation_state(
+            capacity_reservation_id,
+            state="unmanaged",
+            failure_reason=reason,
+            failure_message=message,
+        )
+
+    def capacity_events_after(
+        self, after_version: int, *, limit: int = 500
+    ) -> tuple[list[dict[str, Any]], int]:
+        return self._ledger.events_after(after_version, limit=limit)