kaether 0.1.0__py3-none-any.whl

aether_sdk/__init__.py

@@ -0,0 +1,18 @@
+from aether_sdk.client import Aether, AsyncAether
+from aether_sdk.exceptions import AetherError, AetherHTTPError, AetherJobError
+from aether_sdk.models import Forecast, GhostResult, IngestResult, TimelineFrame
+from aether_sdk.pressure import pressure_band, pressure_color
+
+__all__ = [
+    "Aether",
+    "AetherError",
+    "AetherHTTPError",
+    "AetherJobError",
+    "AsyncAether",
+    "Forecast",
+    "GhostResult",
+    "IngestResult",
+    "TimelineFrame",
+    "pressure_band",
+    "pressure_color",
+]

aether_sdk/client.py

@@ -0,0 +1,277 @@
+from __future__ import annotations
+
+import time
+from collections.abc import Callable
+from typing import Any
+
+import httpx
+
+from aether_sdk.exceptions import AetherHTTPError, AetherJobError
+from aether_sdk.models import (
+    ChangeSet,
+    Forecast,
+    GraphSlice,
+    IngestResult,
+    JobAccepted,
+    JobStatus,
+    UniverseSummary,
+)
+
+ProgressFn = Callable[[int, str], None]
+
+
+def _raise_for_status(response: httpx.Response) -> None:
+    if response.is_success:
+        return
+    detail = response.text
+    try:
+        payload = response.json()
+        if isinstance(payload, dict):
+            detail = str(payload.get("detail", payload))
+    except ValueError:
+        pass
+    raise AetherHTTPError(response.status_code, detail)
+
+
+class Aether:
+    """Sync client for the Aether engine HTTP API."""
+
+    def __init__(
+        self,
+        base_url: str = "http://127.0.0.1:8000",
+        *,
+        timeout: float = 60.0,
+        headers: dict[str, str] | None = None,
+        transport: httpx.BaseTransport | None = None,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self._client = httpx.Client(
+            base_url=self.base_url,
+            timeout=timeout,
+            headers=headers,
+            transport=transport,
+        )
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> Aether:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    def health(self) -> dict[str, Any]:
+        return self._get("/health")
+
+    def universes(self) -> list[UniverseSummary]:
+        rows = self._get("/v1/universes")
+        return [UniverseSummary.model_validate(row) for row in rows]
+
+    def ingest(
+        self,
+        *,
+        path: str = "",
+        url: str = "",
+        pr_ref: str = "",
+        velocity: float | None = None,
+        wait: bool = True,
+        poll_interval: float = 0.35,
+        on_progress: ProgressFn | None = None,
+    ) -> IngestResult | JobAccepted:
+        """Start an ingest job. By default waits until the forecast is ready."""
+        body = {
+            "path": path,
+            "url": url,
+            "pr_ref": pr_ref,
+            "velocity_override": velocity,
+        }
+        accepted = JobAccepted.model_validate(self._post("/v1/jobs", body))
+        if not wait:
+            return accepted
+        return self.wait_job(accepted.job_id, poll_interval=poll_interval, on_progress=on_progress)
+
+    def ingest_now(
+        self,
+        *,
+        path: str = "",
+        url: str = "",
+        pr_ref: str = "",
+        velocity: float | None = None,
+    ) -> IngestResult:
+        """Blocking ingest on the request thread (small repos)."""
+        return IngestResult.model_validate(
+            self._post(
+                "/v1/universes",
+                {
+                    "path": path,
+                    "url": url,
+                    "pr_ref": pr_ref,
+                    "velocity_override": velocity,
+                },
+            )
+        )
+
+    def job(self, job_id: str) -> JobStatus:
+        return JobStatus.model_validate(self._get(f"/v1/jobs/{job_id}"))
+
+    def wait_job(
+        self,
+        job_id: str,
+        *,
+        poll_interval: float = 0.35,
+        on_progress: ProgressFn | None = None,
+    ) -> IngestResult:
+        while True:
+            status = self.job(job_id)
+            if on_progress:
+                on_progress(status.percent, status.stage)
+            if status.failed:
+                raise AetherJobError(job_id, status.error or "ingest failed")
+            if status.done and status.result:
+                return status.result
+            time.sleep(poll_interval)
+
+    def forecast(self, universe_id: str, horizon_months: int = 24) -> Forecast:
+        return Forecast.model_validate(
+            self._get(f"/v1/universes/{universe_id}/forecast", {"horizon_months": horizon_months})
+        )
+
+    def graph(self, universe_id: str, t: int = 0) -> GraphSlice:
+        return GraphSlice.model_validate(self._get(f"/v1/universes/{universe_id}/graph", {"t": t}))
+
+    def attach_changeset(self, universe_id: str, changeset: ChangeSet | dict[str, Any]) -> ChangeSet:
+        payload = changeset.model_dump() if isinstance(changeset, ChangeSet) else changeset
+        return ChangeSet.model_validate(self._post(f"/v1/universes/{universe_id}/changesets", payload))
+
+    def _get(self, path: str, params: dict[str, Any] | None = None) -> Any:
+        response = self._client.get(path, params=params)
+        _raise_for_status(response)
+        return response.json()
+
+    def _post(self, path: str, body: dict[str, Any]) -> Any:
+        response = self._client.post(path, json=body)
+        _raise_for_status(response)
+        return response.json()
+
+
+class AsyncAether:
+    """Async client for the Aether engine HTTP API."""
+
+    def __init__(
+        self,
+        base_url: str = "http://127.0.0.1:8000",
+        *,
+        timeout: float = 60.0,
+        headers: dict[str, str] | None = None,
+        transport: httpx.AsyncBaseTransport | None = None,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self._client = httpx.AsyncClient(
+            base_url=self.base_url,
+            timeout=timeout,
+            headers=headers,
+            transport=transport,
+        )
+
+    async def aclose(self) -> None:
+        await self._client.aclose()
+
+    async def __aenter__(self) -> AsyncAether:
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.aclose()
+
+    async def health(self) -> dict[str, Any]:
+        return await self._get("/health")
+
+    async def universes(self) -> list[UniverseSummary]:
+        rows = await self._get("/v1/universes")
+        return [UniverseSummary.model_validate(row) for row in rows]
+
+    async def ingest(
+        self,
+        *,
+        path: str = "",
+        url: str = "",
+        pr_ref: str = "",
+        velocity: float | None = None,
+        wait: bool = True,
+        poll_interval: float = 0.35,
+        on_progress: ProgressFn | None = None,
+    ) -> IngestResult | JobAccepted:
+        body = {
+            "path": path,
+            "url": url,
+            "pr_ref": pr_ref,
+            "velocity_override": velocity,
+        }
+        accepted = JobAccepted.model_validate(await self._post("/v1/jobs", body))
+        if not wait:
+            return accepted
+        return await self.wait_job(accepted.job_id, poll_interval=poll_interval, on_progress=on_progress)
+
+    async def ingest_now(
+        self,
+        *,
+        path: str = "",
+        url: str = "",
+        pr_ref: str = "",
+        velocity: float | None = None,
+    ) -> IngestResult:
+        return IngestResult.model_validate(
+            await self._post(
+                "/v1/universes",
+                {
+                    "path": path,
+                    "url": url,
+                    "pr_ref": pr_ref,
+                    "velocity_override": velocity,
+                },
+            )
+        )
+
+    async def job(self, job_id: str) -> JobStatus:
+        return JobStatus.model_validate(await self._get(f"/v1/jobs/{job_id}"))
+
+    async def wait_job(
+        self,
+        job_id: str,
+        *,
+        poll_interval: float = 0.35,
+        on_progress: ProgressFn | None = None,
+    ) -> IngestResult:
+        import asyncio
+
+        while True:
+            status = await self.job(job_id)
+            if on_progress:
+                on_progress(status.percent, status.stage)
+            if status.failed:
+                raise AetherJobError(job_id, status.error or "ingest failed")
+            if status.done and status.result:
+                return status.result
+            await asyncio.sleep(poll_interval)
+
+    async def forecast(self, universe_id: str, horizon_months: int = 24) -> Forecast:
+        return Forecast.model_validate(
+            await self._get(f"/v1/universes/{universe_id}/forecast", {"horizon_months": horizon_months})
+        )
+
+    async def graph(self, universe_id: str, t: int = 0) -> GraphSlice:
+        return GraphSlice.model_validate(await self._get(f"/v1/universes/{universe_id}/graph", {"t": t}))
+
+    async def attach_changeset(self, universe_id: str, changeset: ChangeSet | dict[str, Any]) -> ChangeSet:
+        payload = changeset.model_dump() if isinstance(changeset, ChangeSet) else changeset
+        return ChangeSet.model_validate(await self._post(f"/v1/universes/{universe_id}/changesets", payload))
+
+    async def _get(self, path: str, params: dict[str, Any] | None = None) -> Any:
+        response = await self._client.get(path, params=params)
+        _raise_for_status(response)
+        return response.json()
+
+    async def _post(self, path: str, body: dict[str, Any]) -> Any:
+        response = await self._client.post(path, json=body)
+        _raise_for_status(response)
+        return response.json()

aether_sdk/exceptions.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+
+class AetherError(Exception):
+    """Base SDK error."""
+
+
+class AetherHTTPError(AetherError):
+    def __init__(self, status_code: int, detail: str) -> None:
+        self.status_code = status_code
+        self.detail = detail
+        super().__init__(f"{status_code}: {detail}")
+
+
+class AetherJobError(AetherError):
+    def __init__(self, job_id: str, error: str) -> None:
+        self.job_id = job_id
+        self.error = error
+        super().__init__(f"job {job_id} failed: {error}")

aether_sdk/models.py

@@ -0,0 +1,177 @@
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field
+
+from aether_sdk.pressure import Band, pressure_band
+
+
+class IngestResult(BaseModel):
+    universe_id: str
+    repo_path: str
+    license: str = ""
+    snapshots: int = 0
+    velocity_commits_per_week: float = 1.0
+    warnings: list[str] = Field(default_factory=list)
+
+
+class JobAccepted(BaseModel):
+    job_id: str
+    status: str
+    percent: int = 0
+    stage: str = "queued"
+
+
+class JobStatus(BaseModel):
+    job_id: str
+    status: str
+    percent: int = 0
+    stage: str = ""
+    error: str = ""
+    result: IngestResult | None = None
+
+    @property
+    def done(self) -> bool:
+        return self.status == "done"
+
+    @property
+    def failed(self) -> bool:
+        return self.status == "error"
+
+
+class UniverseSummary(BaseModel):
+    id: str
+    repo_path: str
+    license: str = ""
+    velocity: float = 1.0
+
+
+class NodeMetrics(BaseModel):
+    node_id: str
+    kind: str
+    label: str
+    path: str = ""
+    lang: str = ""
+    mass: float
+    velocity: float
+    momentum: float
+    pressure: float
+    dependents: int = 0
+
+    @property
+    def band(self) -> Band:
+        return pressure_band(self.pressure)
+
+
+class Collision(BaseModel):
+    a: str
+    b: str
+    reason: str
+    intensity: float
+
+
+class TimelineFrame(BaseModel):
+    t_index: int
+    months_ahead: float
+    label: str
+    cells: list[NodeMetrics] = Field(default_factory=list)
+    collisions: list[Collision] = Field(default_factory=list)
+    narrative: str = ""
+    narrative_kind: Literal["rising_pressure", "bottleneck", "stable"] = "stable"
+
+    def hottest(self, n: int = 8) -> list[NodeMetrics]:
+        return sorted(self.cells, key=lambda c: c.pressure, reverse=True)[:n]
+
+    def by_band(self) -> dict[Band, list[NodeMetrics]]:
+        out: dict[Band, list[NodeMetrics]] = {"calm": [], "watch": [], "high-pressure": []}
+        for cell in self.cells:
+            out[cell.band].append(cell)
+        return out
+
+
+class ImpactedNode(BaseModel):
+    node_id: str
+    label: str
+    kind: str
+    intensity: float
+    path_type: str = ""
+
+
+class ButterflyFrame(BaseModel):
+    months: float
+    origin_ids: list[str] = Field(default_factory=list)
+    impacted: list[ImpactedNode] = Field(default_factory=list)
+
+
+class GhostResult(BaseModel):
+    intent: str
+    title: str
+    verdict: Literal["pass", "warn", "fail"]
+    extensibility: float
+    files_touched: list[str] = Field(default_factory=list)
+    core_mass_hits: list[str] = Field(default_factory=list)
+    new_cycles: int = 0
+    contract_breaks: list[str] = Field(default_factory=list)
+    note: str = ""
+
+
+class CostBand(BaseModel):
+    month: int
+    compute: float
+    storage: float
+    egress: float
+    drivers: list[str] = Field(default_factory=list)
+
+
+class Forecast(BaseModel):
+    universe_id: str
+    repo_path: str
+    ir_version: int = 1
+    horizon_months: int = 24
+    velocity_commits_per_week: float = 1.0
+    timeline: list[TimelineFrame] = Field(default_factory=list)
+    butterflies: list[ButterflyFrame] = Field(default_factory=list)
+    ghosts: list[GhostResult] = Field(default_factory=list)
+    costs: list[CostBand] = Field(default_factory=list)
+    warnings: list[str] = Field(default_factory=list)
+    heuristic: bool = True
+    license: str = ""
+
+    def frame(self, months: float = 8) -> TimelineFrame | None:
+        if not self.timeline:
+            return None
+        return min(self.timeline, key=lambda f: abs(f.months_ahead - months))
+
+    def hottest(self, n: int = 8, months: float = 8) -> list[NodeMetrics]:
+        frame = self.frame(months)
+        return frame.hottest(n) if frame else []
+
+    def storms(self, months: float = 8) -> list[Collision]:
+        frame = self.frame(months)
+        return list(frame.collisions) if frame else []
+
+
+class Mutation(BaseModel):
+    op: Literal["add", "remove", "retarget"]
+    node: dict[str, Any] | None = None
+    edge: dict[str, Any] | None = None
+    retarget_src: str = ""
+    retarget_dst: str = ""
+
+
+class ChangeSet(BaseModel):
+    id: str = ""
+    universe_id: str = ""
+    label: str = "changeset"
+    summary: str = ""
+    mutations: list[Mutation] = Field(default_factory=list)
+    touched_paths: list[str] = Field(default_factory=list)
+
+
+class GraphSlice(BaseModel):
+    commit_sha: str = ""
+    authored_at: str = ""
+    nodes: list[dict[str, Any]] = Field(default_factory=list)
+    edges: list[dict[str, Any]] = Field(default_factory=list)
+    contracts: list[dict[str, Any]] = Field(default_factory=list)

aether_sdk/pressure.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+from typing import Literal
+
+Band = Literal["calm", "watch", "high-pressure"]
+
+
+def pressure_band(pressure: float) -> Band:
+    if pressure < 0.6:
+        return "calm"
+    if pressure < 1.2:
+        return "watch"
+    return "high-pressure"
+
+
+def pressure_color(pressure: float) -> str:
+    if pressure < 0.6:
+        return "#3d9ee0"
+    if pressure < 1.2:
+        return "#d4a017"
+    return "#e05a4f"

kaether-0.1.0.dist-info/METADATA

@@ -0,0 +1,9 @@
+Metadata-Version: 2.4
+Name: kaether
+Version: 0.1.0
+Summary: Python SDK for the Aether software physics engine
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.9.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.3.0; extra == "dev"

kaether-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+aether_sdk/__init__.py,sha256=E4T8HK5w607wBmzOjXKIpac0fh70SNpMGZDwFTGS4DA,503
+aether_sdk/client.py,sha256=_vVZvFjqMam6gHtwEdxY_nwd3e0H32KBJ7KLDxUwC5w,8852
+aether_sdk/exceptions.py,sha256=SQa4x1O5XRfb6YVRGvO0YDA5rY1PHRM0-X9lTKZ_PbE,523
+aether_sdk/models.py,sha256=a7c4jIkXFz0hDt8Wi9MTvoE-_eKi6wgwBcCrTwKvvXc,4560
+aether_sdk/pressure.py,sha256=_7b2GKc-6imJ13gF3WtY7_S4TCyD4Z4Mzy1Un0rVTyw,440
+kaether-0.1.0.dist-info/METADATA,sha256=7EfUfo9X4ueiybkv77pjwzUTJnn5D1A1LpbqKTLNx4s,259
+kaether-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+kaether-0.1.0.dist-info/top_level.txt,sha256=uov1M5b-1qQVZ7HLAXfNaJ58ZlW1nAfz_rjidGiRVSY,11
+kaether-0.1.0.dist-info/RECORD,,

kaether-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

kaether-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+aether_sdk