kranth 0.2.0__py3-none-any.whl

kranth/__init__.py

@@ -0,0 +1,98 @@
+"""Kranth — stress-test ideas with hundreds of AI personas.
+
+The whole surface is two clients:
+
+  >>> from kranth import Kranth
+  >>> client = Kranth(api_key="kr_live_…")
+  >>> sim = client.sims.create(
+  ...     idea_text="Launch a paid Rust newsletter.",
+  ...     persona_count=50,
+  ...     model_id="claude-sonnet-4-6",
+  ... )
+  >>> for event in client.sims.stream(sim.sim_id):
+  ...     print(event.kind, event.data)
+
+  >>> from kranth import AsyncKranth
+  >>> async with AsyncKranth(api_key="kr_live_…") as client:
+  ...     models = await client.models.list()
+"""
+
+from kranth._async import AsyncKranth
+from kranth._client import Kranth
+from kranth._errors import (
+    KranthAPIError,
+    KranthAuthError,
+    KranthError,
+    KranthPaymentRequired,
+    KranthRateLimited,
+    KranthValidationError,
+)
+from kranth._models import (
+    ApiKey,
+    AudienceReaction,
+    CreateApiKeyResponse,
+    CreateReconResponse,
+    CreateSimResponse,
+    Debate,
+    DebateDetail,
+    DebateEvent,
+    DebateSynthesis,
+    DebateTurn,
+    ListDebatesResponse,
+    ListSimsResponse,
+    Me,
+    ModelInfo,
+    ReconDetail,
+    ReconEvent,
+    ReconFinding,
+    ReconRun,
+    ReconSource,
+    ReconSummary,
+    ReconTier,
+    SimEvent,
+    SimSummary,
+    SpeakerPreview,
+    Usage,
+    VerdictReport,
+)
+
+__all__ = [
+    "Kranth",
+    "AsyncKranth",
+    "KranthError",
+    "KranthAPIError",
+    "KranthAuthError",
+    "KranthValidationError",
+    "KranthPaymentRequired",
+    "KranthRateLimited",
+    "ApiKey",
+    "CreateApiKeyResponse",
+    "CreateSimResponse",
+    "ListSimsResponse",
+    "Me",
+    "ModelInfo",
+    "SimEvent",
+    "SimSummary",
+    "Usage",
+    "VerdictReport",
+    # Recon
+    "CreateReconResponse",
+    "ReconSummary",
+    "ReconDetail",
+    "ReconRun",
+    "ReconFinding",
+    "ReconSource",
+    "ReconTier",
+    "ReconEvent",
+    # Debate
+    "Debate",
+    "DebateDetail",
+    "DebateTurn",
+    "DebateSynthesis",
+    "AudienceReaction",
+    "SpeakerPreview",
+    "ListDebatesResponse",
+    "DebateEvent",
+]
+
+__version__ = "0.2.0"

kranth/_async.py

@@ -0,0 +1,416 @@
+"""Async client.
+
+  >>> async with AsyncKranth(api_key="kr_live_…") as client:
+  ...     models = await client.models.list()
+  ...     sim = await client.sims.create(idea_text="…", persona_count=50, model_id="claude-sonnet-4-6")
+  ...     async for ev in client.sims.stream(sim.sim_id):
+  ...         ...
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, AsyncIterator
+
+import httpx
+
+from kranth._models import (
+    ApiKey,
+    AudienceReaction,
+    CreateApiKeyResponse,
+    CreateReconResponse,
+    CreateSimResponse,
+    Debate,
+    DebateDetail,
+    DebateEvent,
+    DebateSynthesis,
+    DebateTurn,
+    ListDebatesResponse,
+    ListSimsResponse,
+    Me,
+    ModelInfo,
+    ReconDetail,
+    ReconEvent,
+    ReconFinding,
+    ReconSource,
+    ReconSummary,
+    ReconRun,
+    ReconTier,
+    SimEvent,
+    SimSummary,
+    SpeakerPreview,
+    Usage,
+)
+from kranth._transport import DEFAULT_BASE_URL, build_headers, raise_for_status
+
+
+class AsyncKranth:
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str | None = None,
+        timeout: float = 30.0,
+        client: httpx.AsyncClient | None = None,
+    ):
+        if not api_key:
+            raise ValueError("api_key is required")
+        self.api_key = api_key
+        self.base_url = (base_url or DEFAULT_BASE_URL).rstrip("/")
+        self._owns_client = client is None
+        self._http = client or httpx.AsyncClient(timeout=timeout)
+        self.sims = _AsyncSims(self)
+        self.recon = _AsyncRecon(self)
+        self.debates = _AsyncDebates(self)
+        self.api_keys = _AsyncApiKeys(self)
+        self.models = _AsyncModels(self)
+        self.billing = _AsyncBilling(self)
+
+    async def __aenter__(self) -> "AsyncKranth":
+        return self
+
+    async def __aexit__(self, *exc: Any) -> None:
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        if self._owns_client:
+            await self._http.aclose()
+
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json_body: Any | None = None,
+        params: dict[str, Any] | None = None,
+        idempotency_key: str | None = None,
+    ) -> Any:
+        resp = await self._http.request(
+            method,
+            f"{self.base_url}{path}",
+            headers=build_headers(self.api_key, idempotency_key),
+            json=json_body,
+            params=params,
+        )
+        raise_for_status(resp)
+        if resp.status_code == 204 or not resp.content:
+            return None
+        return resp.json()
+
+    async def me(self) -> Me:
+        return Me(**await self._request("GET", "/v1/me"))
+
+
+class _AsyncSims:
+    def __init__(self, parent: AsyncKranth):
+        self._p = parent
+
+    async def create(
+        self,
+        *,
+        idea_text: str,
+        persona_count: int,
+        model_id: str,
+        training_opt_in: bool | None = None,
+        idempotency_key: str | None = None,
+    ) -> CreateSimResponse:
+        body: dict[str, Any] = {
+            "idea_text": idea_text,
+            "persona_count": persona_count,
+            "model_id": model_id,
+        }
+        if training_opt_in is not None:
+            body["training_opt_in"] = training_opt_in
+        data = await self._p._request("POST", "/v1/sims", json_body=body, idempotency_key=idempotency_key)
+        return CreateSimResponse(**data)
+
+    async def get(self, sim_id: str) -> SimSummary:
+        return SimSummary(**await self._p._request("GET", f"/v1/sims/{sim_id}"))
+
+    async def list(
+        self,
+        *,
+        status: str | None = None,
+        cursor: str | None = None,
+        limit: int | None = None,
+    ) -> ListSimsResponse:
+        params: dict[str, Any] = {}
+        if status is not None:
+            params["status"] = status
+        if cursor is not None:
+            params["cursor"] = cursor
+        if limit is not None:
+            params["limit"] = limit
+        data = await self._p._request("GET", "/v1/sims", params=params)
+        return ListSimsResponse(
+            sims=[SimSummary(**s) for s in data["sims"]],
+            next_cursor=data.get("next_cursor"),
+        )
+
+    async def cancel(self, sim_id: str) -> dict[str, Any]:
+        return await self._p._request("POST", f"/v1/sims/{sim_id}/cancel")
+
+    async def export(self, sim_id: str) -> dict[str, Any]:
+        return await self._p._request("GET", f"/v1/sims/{sim_id}/export")
+
+    async def stream(self, sim_id: str) -> AsyncIterator[SimEvent]:
+        token_resp = await self._p._request("POST", f"/v1/sims/{sim_id}/stream-token")
+        token = token_resp["token"]
+        url = f"{self._p.base_url}/v1/sims/{sim_id}/events"
+        async with self._p._http.stream(
+            "GET",
+            url,
+            params={"token": token},
+            headers={"accept": "text/event-stream"},
+        ) as resp:
+            raise_for_status(resp)
+            buf: list[str] = []
+            async for raw in resp.aiter_lines():
+                if raw == "":
+                    payload = "\n".join(l[5:].lstrip() for l in buf if l.startswith("data:"))
+                    buf = []
+                    if not payload:
+                        continue
+                    try:
+                        obj = json.loads(payload)
+                    except json.JSONDecodeError:
+                        continue
+                    yield SimEvent(
+                        kind=obj.get("kind", ""),
+                        sim_id=obj.get("sim_id", sim_id),
+                        data=obj.get("data") or {},
+                    )
+                else:
+                    buf.append(raw)
+
+
+class _AsyncRecon:
+    """Recon — web-grounded research mode (async)."""
+
+    def __init__(self, parent: AsyncKranth):
+        self._p = parent
+
+    async def create(
+        self,
+        *,
+        idea_text: str,
+        tier: str,
+        worker_model: str | None = None,
+        synth_model: str | None = None,
+        audience: str | None = None,
+        company_url: str | None = None,
+        idempotency_key: str | None = None,
+    ) -> CreateReconResponse:
+        body: dict[str, Any] = {"idea_text": idea_text, "tier": tier}
+        if worker_model is not None:
+            body["worker_model"] = worker_model
+        if synth_model is not None:
+            body["synth_model"] = synth_model
+        if audience is not None:
+            body["audience"] = audience
+        if company_url is not None:
+            body["company_url"] = company_url
+        data = await self._p._request("POST", "/v1/recon", json_body=body, idempotency_key=idempotency_key)
+        return CreateReconResponse(**data)
+
+    async def get(self, recon_id: str) -> ReconDetail:
+        data = await self._p._request("GET", f"/v1/recon/{recon_id}")
+        return ReconDetail(
+            run=ReconRun(**data["run"]),
+            findings=[ReconFinding(**f) for f in data.get("findings", [])],
+            sources=[ReconSource(**s) for s in data.get("sources", [])],
+        )
+
+    async def list(self) -> list[ReconSummary]:
+        data = await self._p._request("GET", "/v1/recon")
+        return [ReconSummary(**r) for r in data["recons"]]
+
+    async def tiers(self) -> list[ReconTier]:
+        data = await self._p._request("GET", "/v1/recon/tiers")
+        return [ReconTier(**t) for t in data["tiers"]]
+
+    async def export(self, recon_id: str) -> dict[str, Any]:
+        return await self._p._request("GET", f"/v1/recon/{recon_id}/export")
+
+    async def stream(self, recon_id: str) -> AsyncIterator[ReconEvent]:
+        token = (await self._p._request("POST", f"/v1/recon/{recon_id}/stream-token"))["token"]
+        url = f"{self._p.base_url}/v1/recon/{recon_id}/events"
+        async with self._p._http.stream(
+            "GET", url, params={"token": token}, headers={"accept": "text/event-stream"}
+        ) as resp:
+            raise_for_status(resp)
+            buf: list[str] = []
+            async for raw in resp.aiter_lines():
+                if raw == "":
+                    payload = "\n".join(l[5:].lstrip() for l in buf if l.startswith("data:"))
+                    buf = []
+                    if not payload:
+                        continue
+                    try:
+                        obj = json.loads(payload)
+                    except json.JSONDecodeError:
+                        continue
+                    yield ReconEvent(
+                        kind=obj.get("kind", ""),
+                        recon_id=obj.get("recon_id", recon_id),
+                        data=obj.get("data") or {},
+                    )
+                else:
+                    buf.append(raw)
+
+
+def _parse_debate_detail(data: dict[str, Any]) -> DebateDetail:
+    data = dict(data)
+    synth = data.pop("synthesis", None)
+    audience = data.pop("audience", None) or []
+    return DebateDetail(
+        debate=Debate(**data),
+        synthesis=DebateSynthesis(**synth) if synth else None,
+        audience=[AudienceReaction(**a) for a in audience],
+    )
+
+
+class _AsyncDebates:
+    """Debates — adversarial multi-persona panel mode (async)."""
+
+    def __init__(self, parent: AsyncKranth):
+        self._p = parent
+
+    async def create(
+        self,
+        *,
+        topic: str,
+        mode: str,
+        participants: int | None = None,
+        model_id: str | None = None,
+        training_opt_in: bool | None = None,
+        public: bool | None = None,
+        voice_enabled: bool | None = None,
+        archetype_slugs: list[str] | None = None,
+        idempotency_key: str | None = None,
+    ) -> Debate:
+        body: dict[str, Any] = {"topic": topic, "mode": mode}
+        if participants is not None:
+            body["participants"] = participants
+        if model_id is not None:
+            body["model_id"] = model_id
+        if training_opt_in is not None:
+            body["training_opt_in"] = training_opt_in
+        if public is not None:
+            body["public"] = public
+        if voice_enabled is not None:
+            body["voice_enabled"] = voice_enabled
+        if archetype_slugs is not None:
+            body["archetype_slugs"] = archetype_slugs
+        data = await self._p._request("POST", "/v1/debates", json_body=body, idempotency_key=idempotency_key)
+        return Debate(**data)
+
+    async def get(self, debate_id: str) -> DebateDetail:
+        return _parse_debate_detail(await self._p._request("GET", f"/v1/debates/{debate_id}"))
+
+    async def list(self) -> ListDebatesResponse:
+        data = await self._p._request("GET", "/v1/debates")
+        return ListDebatesResponse(
+            debates=[Debate(**d) for d in data["debates"]],
+            speakers={
+                k: [SpeakerPreview(**s) for s in v]
+                for k, v in (data.get("speakers") or {}).items()
+            },
+        )
+
+    async def turns(self, debate_id: str) -> list[DebateTurn]:
+        data = await self._p._request("GET", f"/v1/debates/{debate_id}/turns")
+        return [DebateTurn(**t) for t in data["turns"]]
+
+    async def set_public(self, debate_id: str, public: bool) -> DebateDetail:
+        return _parse_debate_detail(
+            await self._p._request("PATCH", f"/v1/debates/{debate_id}", json_body={"public": public})
+        )
+
+    async def cancel(self, debate_id: str) -> dict[str, Any]:
+        return await self._p._request("POST", f"/v1/debates/{debate_id}/cancel")
+
+    async def export(self, debate_id: str) -> dict[str, Any]:
+        return await self._p._request("GET", f"/v1/debates/{debate_id}/export")
+
+    async def stream(self, debate_id: str) -> AsyncIterator[DebateEvent]:
+        token = (await self._p._request("POST", f"/v1/debates/{debate_id}/stream-token"))["token"]
+        url = f"{self._p.base_url}/v1/debates/{debate_id}/events"
+        async with self._p._http.stream(
+            "GET", url, params={"token": token}, headers={"accept": "text/event-stream"}
+        ) as resp:
+            raise_for_status(resp)
+            buf: list[str] = []
+            async for raw in resp.aiter_lines():
+                if raw == "":
+                    payload = "\n".join(l[5:].lstrip() for l in buf if l.startswith("data:"))
+                    buf = []
+                    if not payload:
+                        continue
+                    try:
+                        obj = json.loads(payload)
+                    except json.JSONDecodeError:
+                        continue
+                    yield DebateEvent(
+                        kind=obj.get("kind", ""),
+                        debate_id=obj.get("debate_id", debate_id),
+                        data=obj.get("data") or {},
+                    )
+                else:
+                    buf.append(raw)
+
+
+class _AsyncApiKeys:
+    def __init__(self, parent: AsyncKranth):
+        self._p = parent
+
+    async def create(self, name: str, *, env: str = "live") -> CreateApiKeyResponse:
+        data = await self._p._request("POST", "/v1/api-keys", json_body={"name": name, "env": env})
+        return CreateApiKeyResponse(**data)
+
+    async def list(self) -> list[ApiKey]:
+        data = await self._p._request("GET", "/v1/api-keys")
+        return [ApiKey(**k) for k in data["keys"]]
+
+    async def revoke(self, key_id: str) -> None:
+        await self._p._request("DELETE", f"/v1/api-keys/{key_id}")
+
+
+class _AsyncModels:
+    def __init__(self, parent: AsyncKranth):
+        self._p = parent
+
+    async def list(self) -> list[ModelInfo]:
+        data = await self._p._request("GET", "/v1/models")
+        return [ModelInfo(**m) for m in data["models"]]
+
+
+class _AsyncBilling:
+    def __init__(self, parent: AsyncKranth):
+        self._p = parent
+
+    async def usage(self) -> Usage:
+        return Usage(**await self._p._request("GET", "/v1/usage"))
+
+    async def checkout_url(
+        self,
+        plan: str,
+        *,
+        billing_period: str = "monthly",
+        success_url: str | None = None,
+        cancel_url: str | None = None,
+    ) -> str:
+        body: dict[str, Any] = {"plan": plan, "billing_period": billing_period}
+        if success_url:
+            body["success_url"] = success_url
+        if cancel_url:
+            body["cancel_url"] = cancel_url
+        data = await self._p._request("POST", "/v1/billing/checkout", json_body=body)
+        return data["url"]
+
+    async def portal_url(self, return_url: str | None = None) -> str:
+        body: dict[str, Any] = {}
+        if return_url:
+            body["return_url"] = return_url
+        data = await self._p._request("POST", "/v1/billing/portal", json_body=body)
+        return data["url"]