krenzo 0.1.0__tar.gz

krenzo-0.1.0/.gitignore

@@ -0,0 +1,49 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.*
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/versions
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# env files (can opt-in for committing if needed)
+.env*
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts
+
+# Owned by its own repository (report_program/.git), not by this one.
+report_program/
+
+# Python SDK build artifacts
+sdk/python/dist/
+sdk/python/**/__pycache__/
+sdk/python/*.egg-info/

krenzo-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Krenzo
+
+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.

krenzo-0.1.0/PKG-INFO

@@ -0,0 +1,178 @@
+Metadata-Version: 2.5
+Name: krenzo
+Version: 0.1.0
+Summary: Search and extract API for LLM agents — clean, token-efficient web context.
+Project-URL: Homepage, https://krenzo.in
+Project-URL: Documentation, https://krenzo.in/docs
+License: MIT
+License-File: LICENSE
+Keywords: agents,llm,rag,scraping,search,web-extraction
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Internet :: WWW/HTTP :: Indexing/Search
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# krenzo
+
+Search and extract API for LLM agents. One endpoint for live web search, one
+for turning any URL into clean markdown — returned as token-efficient context
+rather than raw HTML.
+
+No runtime dependencies.
+
+```bash
+pip install krenzo
+```
+
+## Quickstart
+
+Get a key at [krenzo.in/dashboard/keys](https://krenzo.in/dashboard/keys), then:
+
+```bash
+export KRENZO_API_KEY=krz_live_...
+```
+
+```python
+from krenzo import Krenzo
+
+client = Krenzo()
+
+for hit in client.search("nvidia q3 earnings", max_results=5):
+    print(hit.source, "—", hit.title)
+```
+
+## Search
+
+```python
+results = client.search(
+    "western digital analyst price target",
+    depth="deep",              # also returns page contents for the top results
+    max_results=10,
+    include_domains=["stockanalysis.com"],
+    freshness="week",
+)
+
+for r in results:
+    print(r.title, r.url)
+    if r.content:              # populated when depth="deep"
+        print(r.content[:500])
+```
+
+`depth="deep"` fetches and extracts the top results in the same call, which
+saves a round trip per result when you were going to read them anyway.
+
+## Extract
+
+```python
+pages = client.extract([
+    "https://example.com/a",
+    "https://example.com/b",
+])
+
+for p in pages:
+    if p.ok:
+        print(p.title, p.word_count)
+        print(p.content)
+    else:
+        print("failed:", p.url, p.error_type, p.error_message)
+```
+
+Each URL carries its own `ok`/`error`, so one dead link does not discard the
+rest of the batch. Pass `format="text"` for plain text instead of markdown, and
+`render=True` for pages that block plain clients or build their content in the
+browser.
+
+### When an empty page is not an empty page
+
+A site that blocks you and a site with nothing on it look identical downstream
+— and only one of them is a bug in your parser. `extract_one` makes the
+difference explicit:
+
+```python
+from krenzo import Krenzo, BlockedError
+
+client = Krenzo()
+
+try:
+    text = client.extract_one("https://www.tipranks.com/stocks/wdc/forecast")
+except BlockedError as e:
+    print("needs a browser or was refused:", e)
+```
+
+Batch `extract()` reports the same thing without raising: check
+`p.needs_rendering` and `p.error_type`.
+
+## Answer
+
+A grounded answer in one call, with every quote checked against the page it
+came from.
+
+```python
+res = client.answer("What did the RBI decide on the repo rate?", max_sources=4)
+
+print(res.answer)
+for c in res.citations:
+    print(f"  — {c.quote}\n    {c.url}")
+```
+
+The model proposes quotes; the service verifies each one against the fetched
+source and drops anything it cannot find. A fabricated citation therefore
+cannot reach you. Two fields are worth reading every time:
+
+- `res.unverified` — quotes that were dropped. Empty means every claim was
+  grounded; non-empty means the answer drifted from its sources.
+- `res.skipped` — pages found but not readable, with a reason. An answer built
+  on one of four sources is weaker than one built on four.
+
+If the sources do not contain the answer, it says so and returns no citations
+rather than guessing. Pass `render=True` to retry unreadable sources through a
+browser; it is billed at the rendered rate, so it is off by default.
+
+## Errors
+
+| Exception | When |
+|---|---|
+| `AuthenticationError` | missing, malformed, or revoked key |
+| `InsufficientCredits` | balance cannot cover the call — top up |
+| `RateLimited` | too many requests; carries `retry_after` |
+| `UpstreamError` | search index or origin failed; usually transient |
+| `BlockedError` | page refused, or needs a browser (`extract_one` only) |
+| `KrenzoError` | base class for all of the above |
+
+Rate limits and upstream failures are retried automatically with backoff.
+Authentication and credit errors are not — they fail identically on a retry.
+
+## Usage and billing
+
+Every call records what it cost:
+
+```python
+client.search("anything")
+print(client.last_usage.balance_usd, client.last_usage.free_calls_remaining)
+```
+
+Calls are billed per call; `extract` is billed per URL, so a 20-URL batch is 20
+calls. Failed requests are not billed, and a call that fails upstream is
+refunded.
+
+## Configuration
+
+| | |
+|---|---|
+| `KRENZO_API_KEY` | your API key (or pass `api_key=`) |
+| `KRENZO_API_URL` | override the base URL, for testing against a local server |
+
+```python
+client = Krenzo(api_key="krz_live_...", timeout=30, max_retries=3)
+```
+
+**Never hard-code a key in published source.** A key committed to a repository
+is a key anyone can spend, and keys cannot be un-published. Read it from the
+environment or a secret manager.
+
+## License
+
+MIT

krenzo-0.1.0/README.md

@@ -0,0 +1,161 @@
+# krenzo
+
+Search and extract API for LLM agents. One endpoint for live web search, one
+for turning any URL into clean markdown — returned as token-efficient context
+rather than raw HTML.
+
+No runtime dependencies.
+
+```bash
+pip install krenzo
+```
+
+## Quickstart
+
+Get a key at [krenzo.in/dashboard/keys](https://krenzo.in/dashboard/keys), then:
+
+```bash
+export KRENZO_API_KEY=krz_live_...
+```
+
+```python
+from krenzo import Krenzo
+
+client = Krenzo()
+
+for hit in client.search("nvidia q3 earnings", max_results=5):
+    print(hit.source, "—", hit.title)
+```
+
+## Search
+
+```python
+results = client.search(
+    "western digital analyst price target",
+    depth="deep",              # also returns page contents for the top results
+    max_results=10,
+    include_domains=["stockanalysis.com"],
+    freshness="week",
+)
+
+for r in results:
+    print(r.title, r.url)
+    if r.content:              # populated when depth="deep"
+        print(r.content[:500])
+```
+
+`depth="deep"` fetches and extracts the top results in the same call, which
+saves a round trip per result when you were going to read them anyway.
+
+## Extract
+
+```python
+pages = client.extract([
+    "https://example.com/a",
+    "https://example.com/b",
+])
+
+for p in pages:
+    if p.ok:
+        print(p.title, p.word_count)
+        print(p.content)
+    else:
+        print("failed:", p.url, p.error_type, p.error_message)
+```
+
+Each URL carries its own `ok`/`error`, so one dead link does not discard the
+rest of the batch. Pass `format="text"` for plain text instead of markdown, and
+`render=True` for pages that block plain clients or build their content in the
+browser.
+
+### When an empty page is not an empty page
+
+A site that blocks you and a site with nothing on it look identical downstream
+— and only one of them is a bug in your parser. `extract_one` makes the
+difference explicit:
+
+```python
+from krenzo import Krenzo, BlockedError
+
+client = Krenzo()
+
+try:
+    text = client.extract_one("https://www.tipranks.com/stocks/wdc/forecast")
+except BlockedError as e:
+    print("needs a browser or was refused:", e)
+```
+
+Batch `extract()` reports the same thing without raising: check
+`p.needs_rendering` and `p.error_type`.
+
+## Answer
+
+A grounded answer in one call, with every quote checked against the page it
+came from.
+
+```python
+res = client.answer("What did the RBI decide on the repo rate?", max_sources=4)
+
+print(res.answer)
+for c in res.citations:
+    print(f"  — {c.quote}\n    {c.url}")
+```
+
+The model proposes quotes; the service verifies each one against the fetched
+source and drops anything it cannot find. A fabricated citation therefore
+cannot reach you. Two fields are worth reading every time:
+
+- `res.unverified` — quotes that were dropped. Empty means every claim was
+  grounded; non-empty means the answer drifted from its sources.
+- `res.skipped` — pages found but not readable, with a reason. An answer built
+  on one of four sources is weaker than one built on four.
+
+If the sources do not contain the answer, it says so and returns no citations
+rather than guessing. Pass `render=True` to retry unreadable sources through a
+browser; it is billed at the rendered rate, so it is off by default.
+
+## Errors
+
+| Exception | When |
+|---|---|
+| `AuthenticationError` | missing, malformed, or revoked key |
+| `InsufficientCredits` | balance cannot cover the call — top up |
+| `RateLimited` | too many requests; carries `retry_after` |
+| `UpstreamError` | search index or origin failed; usually transient |
+| `BlockedError` | page refused, or needs a browser (`extract_one` only) |
+| `KrenzoError` | base class for all of the above |
+
+Rate limits and upstream failures are retried automatically with backoff.
+Authentication and credit errors are not — they fail identically on a retry.
+
+## Usage and billing
+
+Every call records what it cost:
+
+```python
+client.search("anything")
+print(client.last_usage.balance_usd, client.last_usage.free_calls_remaining)
+```
+
+Calls are billed per call; `extract` is billed per URL, so a 20-URL batch is 20
+calls. Failed requests are not billed, and a call that fails upstream is
+refunded.
+
+## Configuration
+
+| | |
+|---|---|
+| `KRENZO_API_KEY` | your API key (or pass `api_key=`) |
+| `KRENZO_API_URL` | override the base URL, for testing against a local server |
+
+```python
+client = Krenzo(api_key="krz_live_...", timeout=30, max_retries=3)
+```
+
+**Never hard-code a key in published source.** A key committed to a repository
+is a key anyone can spend, and keys cannot be un-published. Read it from the
+environment or a secret manager.
+
+## License
+
+MIT

krenzo-0.1.0/krenzo/__init__.py

@@ -0,0 +1,34 @@
+"""Krenzo — search and extract API for LLM agents."""
+
+from .client import (
+    Answer,
+    AuthenticationError,
+    BlockedError,
+    Citation,
+    ExtractResult,
+    InsufficientCredits,
+    Krenzo,
+    KrenzoError,
+    RateLimited,
+    SearchResult,
+    UpstreamError,
+    Usage,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Krenzo",
+    "Answer",
+    "Citation",
+    "KrenzoError",
+    "AuthenticationError",
+    "InsufficientCredits",
+    "RateLimited",
+    "UpstreamError",
+    "BlockedError",
+    "SearchResult",
+    "ExtractResult",
+    "Usage",
+    "__version__",
+]

krenzo-0.1.0/krenzo/client.py

@@ -0,0 +1,467 @@
+"""
+Krenzo API client.
+
+Stdlib only, on purpose. An SDK that pulls in `requests` forces its version on
+every project that installs it, and this one does nothing `urllib` can't.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from dataclasses import dataclass, field
+from typing import Any, Iterable, Literal
+
+__all__ = [
+    "Krenzo",
+    "Answer",
+    "Citation",
+    "KrenzoError",
+    "AuthenticationError",
+    "InsufficientCredits",
+    "RateLimited",
+    "UpstreamError",
+    "BlockedError",
+    "SearchResult",
+    "ExtractResult",
+    "Usage",
+]
+
+DEFAULT_BASE_URL = "https://krenzo.in/api/v1"
+DEFAULT_TIMEOUT = 60.0
+USER_AGENT = "krenzo-python/0.1.0"
+
+
+# --------------------------------------------------------------- exceptions
+
+
+class KrenzoError(Exception):
+    """Base for every error this client raises."""
+
+    def __init__(self, message: str, *, status: int | None = None, type: str | None = None):
+        super().__init__(message)
+        self.message = message
+        self.status = status
+        self.type = type
+
+
+class AuthenticationError(KrenzoError):
+    """Missing, malformed, or revoked API key."""
+
+
+class InsufficientCredits(KrenzoError):
+    """
+    The account balance cannot cover the call.
+
+    Separate from other 4xx because it is the one error a caller can usually
+    resolve without a code change — by topping up.
+    """
+
+
+class RateLimited(KrenzoError):
+    """Too many requests. `retry_after` is seconds, when the server says."""
+
+    def __init__(self, message: str, *, retry_after: float | None = None, **kw: Any):
+        super().__init__(message, **kw)
+        self.retry_after = retry_after
+
+
+class UpstreamError(KrenzoError):
+    """The search index or an origin failed. Usually transient."""
+
+
+class BlockedError(KrenzoError):
+    """
+    A page was refused, or came back needing a browser to render.
+
+    Raised only by `extract_one`. It exists so that "the origin blocked us" is
+    never silently indistinguishable from "the page had nothing on it" — the
+    two call for completely different responses, and only one is a bug.
+    """
+
+
+# ------------------------------------------------------------------ models
+
+
+@dataclass(frozen=True)
+class Usage:
+    charged_paise: int
+    free_call: bool
+    free_calls_remaining: int
+    balance_paise: int
+    balance_inr: str
+    balance_usd: str
+    #: Calls this balance can still pay for, at the current rate.
+    calls_remaining: int = 0
+    #: True once the balance is nearly spent — act before calls start failing.
+    low_balance: bool = False
+
+    @classmethod
+    def _from(cls, d: dict[str, Any]) -> "Usage":
+        return cls(
+            charged_paise=int(d.get("charged_paise", 0)),
+            free_call=bool(d.get("free_call", False)),
+            free_calls_remaining=int(d.get("free_calls_remaining", 0)),
+            balance_paise=int(d.get("balance_paise", 0)),
+            balance_inr=str(d.get("balance_inr", "")),
+            balance_usd=str(d.get("balance_usd", "")),
+            calls_remaining=int(d.get("calls_remaining", 0)),
+            low_balance=bool(d.get("low_balance", False)),
+        )
+
+
+@dataclass(frozen=True)
+class SearchResult:
+    title: str
+    url: str
+    snippet: str
+    source: str
+    published: str | None = None
+    #: Present only for depth="deep".
+    content: str | None = None
+    word_count: int | None = None
+    needs_rendering: bool | None = None
+    content_error: str | None = None
+
+    @classmethod
+    def _from(cls, d: dict[str, Any]) -> "SearchResult":
+        return cls(
+            title=d.get("title", ""),
+            url=d.get("url", ""),
+            snippet=d.get("snippet", ""),
+            source=d.get("source", ""),
+            published=d.get("published"),
+            content=d.get("content"),
+            word_count=d.get("word_count"),
+            needs_rendering=d.get("needs_rendering"),
+            content_error=d.get("content_error"),
+        )
+
+
+@dataclass(frozen=True)
+class Citation:
+    """A quote that was verified against the source it is attributed to."""
+
+    #: The supporting text, exactly as it appears in the source — not as the
+    #: model wrote it.
+    quote: str
+    url: str
+    title: str | None = None
+    #: Character offsets into the fetched document.
+    start: int | None = None
+    end: int | None = None
+
+    @classmethod
+    def _from(cls, d: dict[str, Any]) -> "Citation":
+        return cls(
+            quote=d.get("quote", ""),
+            url=d.get("url", ""),
+            title=d.get("title"),
+            start=d.get("start"),
+            end=d.get("end"),
+        )
+
+
+@dataclass(frozen=True)
+class Answer:
+    answer: str
+    citations: list[Citation] = field(default_factory=list)
+    sources: list[dict[str, Any]] = field(default_factory=list)
+    #: Pages found but not readable, with a reason. An answer built on one of
+    #: four sources is weaker than one built on four, and this is how you tell.
+    skipped: list[dict[str, Any]] = field(default_factory=list)
+    #: Quotes the model claimed that could NOT be found in any source. Empty
+    #: means every claim was grounded; non-empty means the answer drifted.
+    unverified: list[dict[str, Any]] = field(default_factory=list)
+    rendered: int = 0
+    model: str = ""
+
+    @classmethod
+    def _from(cls, d: dict[str, Any]) -> "Answer":
+        return cls(
+            answer=d.get("answer", ""),
+            citations=[Citation._from(c) for c in d.get("citations", [])],
+            sources=d.get("sources") or [],
+            skipped=d.get("skipped") or [],
+            unverified=d.get("unverified") or [],
+            rendered=int(d.get("rendered", 0)),
+            model=d.get("model", ""),
+        )
+
+
+@dataclass(frozen=True)
+class ExtractResult:
+    url: str
+    ok: bool
+    title: str | None = None
+    description: str | None = None
+    content: str | None = None
+    word_count: int | None = None
+    #: True when the page was fetched through a real browser.
+    rendered: bool = False
+    #: True when the page returned almost no text for its size — the signature
+    #: of a client-rendered app. Treating this as an empty page is a bug.
+    needs_rendering: bool = False
+    status: int | None = None
+    error_type: str | None = None
+    error_message: str | None = None
+    links: list[dict[str, str]] = field(default_factory=list)
+
+    @classmethod
+    def _from(cls, d: dict[str, Any]) -> "ExtractResult":
+        err = d.get("error") or {}
+        return cls(
+            url=d.get("url", ""),
+            ok=bool(d.get("ok")),
+            title=d.get("title"),
+            description=d.get("description"),
+            content=d.get("content"),
+            word_count=d.get("word_count"),
+            rendered=bool(d.get("rendered", False)),
+            needs_rendering=bool(d.get("needs_rendering", False)),
+            status=d.get("status"),
+            error_type=err.get("type"),
+            error_message=err.get("message"),
+            links=d.get("links") or [],
+        )
+
+
+# ------------------------------------------------------------------ client
+
+
+class Krenzo:
+    """
+    Client for the Krenzo search and extract API.
+
+        from krenzo import Krenzo
+
+        client = Krenzo()                      # reads KRENZO_API_KEY
+        for hit in client.search("nvidia earnings date"):
+            print(hit.source, hit.title)
+
+    The key is read from the environment by default. Do not hard-code one in
+    source you publish — a key in a repository is a key anyone can spend.
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str | None = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = 2,
+    ):
+        self.api_key = api_key or os.environ.get("KRENZO_API_KEY", "").strip()
+        if not self.api_key:
+            raise AuthenticationError(
+                "No API key. Pass api_key= or set KRENZO_API_KEY. "
+                "Create one at https://krenzo.in/dashboard/keys"
+            )
+        self.base_url = (base_url or os.environ.get("KRENZO_API_URL") or DEFAULT_BASE_URL).rstrip("/")
+        self.timeout = timeout
+        self.max_retries = max_retries
+
+    # -- transport ---------------------------------------------------------
+
+    def _post(self, path: str, payload: dict[str, Any]) -> dict[str, Any]:
+        body = json.dumps(payload).encode()
+        last: Exception | None = None
+
+        for attempt in range(self.max_retries + 1):
+            req = urllib.request.Request(
+                f"{self.base_url}{path}",
+                data=body,
+                headers={
+                    "Authorization": f"Bearer {self.api_key}",
+                    "Content-Type": "application/json",
+                    "User-Agent": USER_AGENT,
+                },
+                method="POST",
+            )
+            try:
+                with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+                    return json.loads(resp.read().decode())
+            except urllib.error.HTTPError as exc:
+                err = self._error_from(exc)
+                # Only retry what retrying can fix. A 402 or 401 will fail
+                # identically forever, and retrying a 429 without honouring
+                # Retry-After just deepens the hole.
+                if isinstance(err, (RateLimited, UpstreamError)) and attempt < self.max_retries:
+                    delay = getattr(err, "retry_after", None) or (2 ** attempt)
+                    time.sleep(min(delay, 30))
+                    last = err
+                    continue
+                raise err from exc
+            except urllib.error.URLError as exc:
+                last = KrenzoError(f"Could not reach {self.base_url}: {exc.reason}")
+                if attempt < self.max_retries:
+                    time.sleep(2 ** attempt)
+                    continue
+                raise last from exc
+
+        raise last or KrenzoError("Request failed.")
+
+    @staticmethod
+    def _error_from(exc: urllib.error.HTTPError) -> KrenzoError:
+        raw = exc.read().decode(errors="replace")
+        message, kind = raw, None
+        try:
+            err = json.loads(raw).get("error") or {}
+            message = err.get("message") or raw
+            kind = err.get("type")
+        except (ValueError, AttributeError):
+            pass
+
+        if exc.code == 401:
+            return AuthenticationError(message, status=401, type=kind)
+        if exc.code == 402:
+            return InsufficientCredits(message, status=402, type=kind)
+        if exc.code == 429:
+            retry = exc.headers.get("Retry-After") if exc.headers else None
+            return RateLimited(
+                message,
+                retry_after=float(retry) if retry and retry.isdigit() else None,
+                status=429,
+                type=kind,
+            )
+        if exc.code in (502, 503, 504):
+            return UpstreamError(message, status=exc.code, type=kind)
+        return KrenzoError(message, status=exc.code, type=kind)
+
+    # -- endpoints ---------------------------------------------------------
+
+    def search(
+        self,
+        query: str,
+        *,
+        depth: Literal["quick", "deep"] = "quick",
+        max_results: int = 10,
+        include_domains: Iterable[str] | None = None,
+        exclude_domains: Iterable[str] | None = None,
+        freshness: Literal["day", "week", "month", "year"] | None = None,
+    ) -> list[SearchResult]:
+        """
+        Web search.
+
+        `depth="deep"` also returns the extracted contents of the top results,
+        which saves a round trip per result when you were going to fetch them
+        anyway.
+        """
+        payload: dict[str, Any] = {
+            "query": query,
+            "depth": depth,
+            "max_results": max_results,
+        }
+        if include_domains:
+            payload["include_domains"] = list(include_domains)
+        if exclude_domains:
+            payload["exclude_domains"] = list(exclude_domains)
+        if freshness:
+            payload["freshness"] = freshness
+
+        body = self._post("/search", payload)
+        self.last_usage = Usage._from(body.get("usage") or {})
+        return [SearchResult._from(r) for r in body.get("results", [])]
+
+    def extract(
+        self,
+        urls: str | Iterable[str],
+        *,
+        format: Literal["markdown", "text"] = "markdown",
+        render: bool = False,
+        respect_robots: bool = True,
+        include_links: bool = False,
+    ) -> list[ExtractResult]:
+        """
+        Fetch and clean one or more URLs.
+
+        Returns one result per URL, each with its own ok/error — a dead link
+        among ten does not discard the nine that worked.
+        """
+        if isinstance(urls, str):
+            urls = [urls]
+        body = self._post(
+            "/extract",
+            {
+                "urls": list(urls),
+                "format": format,
+                "render": render,
+                "respect_robots": respect_robots,
+                "include_links": include_links,
+            },
+        )
+        self.last_usage = Usage._from(body.get("usage") or {})
+        return [ExtractResult._from(r) for r in body.get("results", [])]
+
+    def answer(
+        self,
+        query: str,
+        *,
+        max_sources: int = 4,
+        urls: Iterable[str] | None = None,
+        render: bool = False,
+        include_domains: Iterable[str] | None = None,
+        exclude_domains: Iterable[str] | None = None,
+        freshness: Literal["day", "week", "month", "year"] | None = None,
+    ) -> Answer:
+        """
+        A grounded answer, with every quote verified against its source.
+
+        The model proposes quotes; the service checks each one against the page
+        it was fetched from and drops anything not found. A fabricated citation
+        therefore cannot reach you — but read `unverified`, which lists what was
+        dropped, and `skipped`, which lists pages that could not be read.
+
+        `render=True` retries unreadable sources through a browser; it is billed
+        at the rendered rate, so it is off by default.
+        """
+        payload: dict[str, Any] = {
+            "query": query,
+            "max_sources": max_sources,
+            "render": render,
+        }
+        if urls:
+            payload["urls"] = list(urls)
+        if include_domains:
+            payload["include_domains"] = list(include_domains)
+        if exclude_domains:
+            payload["exclude_domains"] = list(exclude_domains)
+        if freshness:
+            payload["freshness"] = freshness
+
+        body = self._post("/answer", payload)
+        self.last_usage = Usage._from(body.get("usage") or {})
+        return Answer._from(body)
+
+    def extract_one(self, url: str, **kw: Any) -> str:
+        """
+        Content for a single URL, or an exception.
+
+        Raises `BlockedError` when the origin refused the fetch or returned a
+        page that needs a browser. Use this when an empty result would be
+        indistinguishable from a real absence and that distinction matters.
+        """
+        results = self.extract(url, **kw)
+        if not results:
+            raise KrenzoError(f"No result returned for {url}")
+
+        r = results[0]
+        if not r.ok:
+            message = f"{r.error_type} for {url}: {r.error_message}"
+            if r.error_type in ("http_error", "robots_disallowed", "timeout"):
+                raise BlockedError(message, type=r.error_type, status=r.status)
+            raise KrenzoError(message, type=r.error_type, status=r.status)
+
+        if r.needs_rendering:
+            hint = "" if kw.get("render") else " Retry with render=True."
+            raise BlockedError(
+                f"{url} returned {r.word_count} words — the page renders its "
+                f"content with JavaScript.{hint}",
+                type="needs_rendering",
+            )
+
+        return r.content or ""

krenzo-0.1.0/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "krenzo"
+version = "0.1.0"
+description = "Search and extract API for LLM agents — clean, token-efficient web context."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+keywords = ["search", "scraping", "llm", "agents", "rag", "web-extraction"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Topic :: Internet :: WWW/HTTP :: Indexing/Search",
+]
+# No runtime dependencies on purpose: an SDK that pulls in `requests` forces
+# its version onto every project that installs it, and urllib is sufficient.
+dependencies = []
+
+[project.urls]
+Homepage = "https://krenzo.in"
+Documentation = "https://krenzo.in/docs"
+
+[tool.hatch.build.targets.wheel]
+packages = ["krenzo"]

krenzo-0.1.0/tests/test_client.py

@@ -0,0 +1,143 @@
+"""
+Offline tests. No network, no API key, no credits spent.
+
+Everything here exercises the parts that are easy to get wrong without
+noticing: error mapping by status code, and the parsing that turns a response
+into the objects callers actually touch.
+"""
+
+import json
+import sys
+import unittest
+import urllib.error
+from io import BytesIO
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+
+from krenzo import (  # noqa: E402
+    AuthenticationError,
+    BlockedError,
+    ExtractResult,
+    InsufficientCredits,
+    Krenzo,
+    KrenzoError,
+    RateLimited,
+    SearchResult,
+    UpstreamError,
+)
+
+
+def http_error(code: int, payload: dict, headers: dict | None = None):
+    body = BytesIO(json.dumps(payload).encode())
+    return urllib.error.HTTPError(
+        "https://krenzo.in/api/v1/search", code, "err", headers or {}, body
+    )
+
+
+class ErrorMapping(unittest.TestCase):
+    def map(self, code, type_="x", headers=None):
+        exc = http_error(code, {"error": {"type": type_, "message": "boom"}}, headers)
+        return Krenzo._error_from(exc)
+
+    def test_401_is_authentication(self):
+        self.assertIsInstance(self.map(401), AuthenticationError)
+
+    def test_402_is_insufficient_credits(self):
+        err = self.map(402, "insufficient_credits")
+        self.assertIsInstance(err, InsufficientCredits)
+        self.assertEqual(err.status, 402)
+
+    def test_429_carries_retry_after(self):
+        err = self.map(429, headers={"Retry-After": "7"})
+        self.assertIsInstance(err, RateLimited)
+        self.assertEqual(err.retry_after, 7.0)
+
+    def test_5xx_is_upstream(self):
+        for code in (502, 503, 504):
+            self.assertIsInstance(self.map(code), UpstreamError)
+
+    def test_unknown_code_falls_back_to_base(self):
+        err = self.map(418)
+        self.assertIsInstance(err, KrenzoError)
+        self.assertNotIsInstance(err, UpstreamError)
+
+    def test_non_json_body_still_produces_a_message(self):
+        exc = urllib.error.HTTPError("u", 500, "e", {}, BytesIO(b"<html>502</html>"))
+        self.assertIn("502", Krenzo._error_from(exc).message)
+
+
+class Parsing(unittest.TestCase):
+    def test_search_result_tolerates_missing_fields(self):
+        r = SearchResult._from({"url": "https://a.test"})
+        self.assertEqual(r.url, "https://a.test")
+        self.assertEqual(r.title, "")
+        self.assertIsNone(r.content)
+
+    def test_extract_result_lifts_nested_error(self):
+        r = ExtractResult._from(
+            {"url": "u", "ok": False, "error": {"type": "http_error", "message": "403"}}
+        )
+        self.assertFalse(r.ok)
+        self.assertEqual(r.error_type, "http_error")
+        self.assertEqual(r.error_message, "403")
+
+    def test_extract_result_defaults_are_safe(self):
+        r = ExtractResult._from({"url": "u", "ok": True})
+        self.assertFalse(r.needs_rendering)
+        self.assertFalse(r.rendered)
+        self.assertEqual(r.links, [])
+
+
+class ExtractOneContract(unittest.TestCase):
+    """The distinction this SDK exists to preserve: blocked != empty."""
+
+    def client(self, results):
+        c = Krenzo.__new__(Krenzo)          # bypass __init__'s key requirement
+        c.extract = lambda *a, **k: [ExtractResult._from(r) for r in results]
+        return c
+
+    def test_returns_content_when_ok(self):
+        c = self.client([{"url": "u", "ok": True, "content": "hello"}])
+        self.assertEqual(c.extract_one("u"), "hello")
+
+    def test_raises_blocked_on_http_error(self):
+        c = self.client(
+            [{"url": "u", "ok": False, "error": {"type": "http_error", "message": "403"}}]
+        )
+        with self.assertRaises(BlockedError):
+            c.extract_one("u")
+
+    def test_raises_blocked_on_needs_rendering(self):
+        # The important one: a 200 with almost no text must not look like a
+        # page that genuinely had nothing on it.
+        c = self.client(
+            [{"url": "u", "ok": True, "content": "", "word_count": 12,
+              "needs_rendering": True}]
+        )
+        with self.assertRaises(BlockedError) as ctx:
+            c.extract_one("u")
+        self.assertIn("render=True", str(ctx.exception))
+
+    def test_non_blocking_failure_is_plain_error(self):
+        c = self.client(
+            [{"url": "u", "ok": False, "error": {"type": "invalid_url", "message": "bad"}}]
+        )
+        with self.assertRaises(KrenzoError) as ctx:
+            c.extract_one("u")
+        self.assertNotIsInstance(ctx.exception, BlockedError)
+
+
+class Construction(unittest.TestCase):
+    def test_missing_key_raises_with_a_useful_message(self):
+        with self.assertRaises(AuthenticationError) as ctx:
+            Krenzo(api_key="")
+        self.assertIn("KRENZO_API_KEY", str(ctx.exception))
+
+    def test_base_url_trailing_slash_is_normalised(self):
+        c = Krenzo(api_key="k", base_url="https://example.test/api/v1/")
+        self.assertEqual(c.base_url, "https://example.test/api/v1")
+
+
+if __name__ == "__main__":
+    unittest.main(verbosity=2)