brussle 1.0.0__tar.gz

brussle-1.0.0/.gitignore

@@ -0,0 +1,7 @@
+node_modules/
+dist/
+.venv/
+__pycache__/
+.mypy_cache/
+.pytest_cache/
+*.egg-info/

brussle-1.0.0/PKG-INFO

@@ -0,0 +1,29 @@
+Metadata-Version: 2.5
+Name: brussle
+Version: 1.0.0
+Summary: Python SDK for the Brussle API
+License-Expression: LicenseRef-Proprietary
+Requires-Python: >=3.9
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: typing-extensions>=4.7
+Description-Content-Type: text/markdown
+
+# brussle (Python)
+
+```python
+from brussle import And, Client
+
+db = Client(api_key="...")
+ns = db.namespace("acme/prod/tenant_123")
+ns.write(upsert=[{"id": "t_123", "attributes": {"plan": "pro"}, "state": {"subject": "Refund"}}])
+page = ns.query(filters=And(("attributes.plan", "Eq", "pro"), ("answers.needs_escalation.p", "Gte", 0.85)), top_k=10)
+```
+
+To load many documents, `import_documents` takes any iterable and writes it in batches, 4 at a time on a thread pool, with retries:
+
+```python
+summary = ns.import_documents(records(), concurrency=4)
+print(summary.documents, summary.failures)
+```
+
+Methods mirror the API's routes. Every route that changes something takes `idempotency_key=`. Reads, writes and calls with a key are retried after network errors, timeouts and 5xx, 2 times by default (`max_retries`). Requests and responses are plain JSON, typed in `brussle.types`. Filters and `rank_by` are tuples. Errors raise `ApiError` with the API's `code` and `details`, or `unknown` for an error response that is not the API's JSON (such as a proxy's error page), or a success whose body is not JSON. A call your organization's plan doesn't include raises `plan_required` (402), and `details["required_plan"]` names the plan that does. See [the SDK overview](../README.md).

brussle-1.0.0/README.md

@@ -0,0 +1,19 @@
+# brussle (Python)
+
+```python
+from brussle import And, Client
+
+db = Client(api_key="...")
+ns = db.namespace("acme/prod/tenant_123")
+ns.write(upsert=[{"id": "t_123", "attributes": {"plan": "pro"}, "state": {"subject": "Refund"}}])
+page = ns.query(filters=And(("attributes.plan", "Eq", "pro"), ("answers.needs_escalation.p", "Gte", 0.85)), top_k=10)
+```
+
+To load many documents, `import_documents` takes any iterable and writes it in batches, 4 at a time on a thread pool, with retries:
+
+```python
+summary = ns.import_documents(records(), concurrency=4)
+print(summary.documents, summary.failures)
+```
+
+Methods mirror the API's routes. Every route that changes something takes `idempotency_key=`. Reads, writes and calls with a key are retried after network errors, timeouts and 5xx, 2 times by default (`max_retries`). Requests and responses are plain JSON, typed in `brussle.types`. Filters and `rank_by` are tuples. Errors raise `ApiError` with the API's `code` and `details`, or `unknown` for an error response that is not the API's JSON (such as a proxy's error page), or a success whose body is not JSON. A call your organization's plan doesn't include raises `plan_required` (402), and `details["required_plan"]` names the plan that does. See [the SDK overview](../README.md).

brussle-1.0.0/examples/spec_6_13.py

@@ -0,0 +1,95 @@
+"""The main spec §6.13 example, made concrete: every call in the order the spec lists them.
+
+Run it against staging or a local node with BRUSSLE_API_KEY and BRUSSLE_BASE_URL set:
+
+    .venv/bin/python examples/spec_6_13.py
+
+The tests run it against the mock server.
+"""
+
+import json
+import os
+from typing import Any, Dict
+
+from brussle import DEFAULT_BASE_URL, And, Client
+
+
+def example(db: Client, *, serves_v15: bool) -> Dict[str, Any]:
+    """`serves_v15`: outcomes and job confirmation are v1.5 flows (§6.9, §6.10); v1 has no job awaiting confirmation."""
+    ns = db.namespace("acme/prod/tenant_123")
+
+    created = ns.judgments.create(
+        name="needs_escalation",
+        type="bool",
+        question="Does this ticket require a human to take over from the automated flow?",
+        criteria="Escalate when the customer is at risk of leaving, mentions legal action, or the automation has failed twice.",
+        context={"fields": ["state.subject", "state.body", "attributes.plan"], "last_n": {"state.messages": 3}, "max_tokens": 4000},
+        engine={"name": "jev", "version": "current"},
+        thresholds={"escalate": 0.85},
+        freshness={"policy": "on_change"},
+        activate=True,
+    )
+
+    ns.write(
+        upsert=[
+            {"id": "t_123", "attributes": {"plan": "pro"}, "state": {"subject": "Refund", "body": "Charged twice.", "messages": []}},
+            {"id": "t_124", "attributes": {"plan": "free"}, "state": {"subject": "Login", "body": "Password reset loops."}},
+            {"id": "t_125", "attributes": {"plan": "pro"}, "state": {"subject": "Spam", "body": "Buy now."}},
+        ],
+        patch=[{"id": "t_124", "attributes": {"plan": "enterprise"}, "state": {"status": "open"}}],
+        append=[{"id": "t_123", "path": "state.messages", "values": [{"role": "customer", "text": "Third time asking."}]}],
+        delete=["t_125"],
+        wait_for=["needs_escalation"],
+    )
+
+    page = ns.query(
+        filters=And(
+            ("attributes.plan", "In", ["pro", "enterprise"]),
+            ("answers.needs_escalation.p", "Gte", 0),
+        ),
+        rank_by=("answers.needs_escalation.p", "desc"),
+        top_k=10,
+        include={"attributes": ["plan"], "answers": ["needs_escalation"]},
+        answers="fresh_only",
+    )
+
+    document = ns.get("t_123", include_history=True)
+
+    ns.judgments.update("needs_escalation", freshness={"policy": "on_change", "debounce_ms": 2000}, confirm=True)
+
+    next_version = ns.judgments.create(
+        name="needs_escalation",
+        type="bool",
+        question="Does this ticket require a human to take over from the automated flow?",
+        criteria="Escalate on churn risk, legal threats, two automation failures, or a repeated complaint.",
+        context={"fields": ["state.subject", "state.body", "attributes.plan"], "last_n": {"state.messages": 3}},
+        engine={"name": "jev", "version": "current"},
+        thresholds={"escalate": 0.85},
+    )
+    if "replay" in next_version:
+        raise RuntimeError("only an entity judgment's create returns a replay estimate")
+    ns.judgments.activate("needs_escalation", version=next_version["version"], force=True)
+
+    estimate = ns.judgments.backfill("needs_escalation", confirm=False)
+    started = ns.judgments.backfill("needs_escalation", confirm=True)
+    if "job_id" not in started:
+        raise RuntimeError("a confirmed backfill starts a job")
+    job_id = started["job_id"]
+
+    if serves_v15:
+        ns.outcomes.append([
+            {"document_id": "t_123", "judgment": "needs_escalation", "value": True, "observed_at": "2026-09-23T12:00:00Z"},
+        ])
+
+    db.jobs.get(job_id); db.jobs.pause(job_id); db.jobs.resume(job_id); db.jobs.cancel(job_id)  # noqa: E702
+    if serves_v15:
+        db.jobs.confirm(job_id)
+
+    return {"created": created, "rows": page["rows"], "document": document, "estimate": estimate}
+
+
+if __name__ == "__main__":
+    base_url = os.environ.get("BRUSSLE_BASE_URL", DEFAULT_BASE_URL)
+    with Client(api_key=os.environ["BRUSSLE_API_KEY"], base_url=base_url) as db:
+        result = example(db, serves_v15=os.environ.get("JDB_SERVES_V15") == "1")
+    print(json.dumps(result, indent=2))

brussle-1.0.0/pyproject.toml

@@ -0,0 +1,33 @@
+[project]
+name = "brussle"
+version = "1.0.0"
+description = "Python SDK for the Brussle API"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "LicenseRef-Proprietary"
+dependencies = ["httpx>=0.27,<1", "typing_extensions>=4.7"]
+
+[dependency-groups]
+dev = ["mypy==1.19.1", "pytest>=8", "pyyaml>=6", "types-PyYAML"]
+
+[build-system]
+requires = ["hatchling>=1.26"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/brussle"]
+
+[tool.mypy]
+python_version = "3.9"
+strict = true
+files = ["src", "tests", "examples", "scripts"]
+
+# Each method returns the parsed JSON (`Any`) under the type the contract gives
+# it. Nothing is validated at runtime (D-surface-2), so there is nothing to cast.
+[[tool.mypy.overrides]]
+module = "brussle._client"
+warn_return_any = false
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src", "."]

brussle-1.0.0/scripts/generate_types.py

@@ -0,0 +1,306 @@
+"""Generates `src/brussle/types.py` from `api/openapi.yaml`, and `_brand.py` from `docs/brand.json`.
+
+`docs/brand.json` is the one place the product name and domain are set (D-surface-41).
+
+Every component schema becomes a `TypedDict` or a type alias. They are static
+types over the JSON the API sends and receives: nothing is converted or
+validated at runtime, so fields and enum values the API adds later never break
+a client (decision D-surface-2).
+
+The generator covers the JSON Schema subset the contract uses. It fails loudly
+on anything else, so a contract change that needs new handling cannot slip
+through as a wrong type.
+
+    .venv/bin/python scripts/generate_types.py          # write the file
+    .venv/bin/python scripts/generate_types.py --check  # exit 1 if it is stale
+"""
+
+from __future__ import annotations
+
+import json
+import keyword
+import re
+import sys
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+import yaml
+
+ROOT = Path(__file__).resolve().parents[1]
+OPENAPI = ROOT.parents[1] / "api" / "openapi.yaml"
+OUTPUT = ROOT / "src" / "brussle" / "types.py"
+BRAND = ROOT.parents[1] / "docs" / "brand.json"
+BRAND_OUTPUT = ROOT / "src" / "brussle" / "_brand.py"
+
+Schema = Dict[str, Any]
+
+# Keywords that only constrain values or help other generators. Types ignore them.
+IGNORED = {
+    "description", "examples", "default", "format", "pattern", "minLength", "maxLength",
+    "minimum", "maximum", "exclusiveMinimum", "exclusiveMaximum", "minItems", "maxItems", "uniqueItems", "minProperties",
+    "maxProperties", "propertyNames", "discriminator", "if", "then", "not",
+    "unevaluatedProperties", "anyOf", "deprecated", "dependentRequired",
+}
+HANDLED = {
+    "$ref", "type", "enum", "const", "properties", "required", "additionalProperties",
+    "items", "prefixItems", "oneOf", "allOf",
+}
+
+
+def ref_name(schema: Schema) -> str:
+    return str(schema["$ref"]).rsplit("/", 1)[1]
+
+
+def typed_all_of(schema: Schema) -> List[Schema]:
+    """`allOf` members that add a type. Members that only constrain (`if`/`then`/`else`) are ignored like `if` is."""
+    return [
+        member for member in schema.get("allOf", [])
+        if not set(member) <= {"description", "if", "then", "else"}
+    ]
+
+
+def pascal(name: str) -> str:
+    return "".join(part[:1].upper() + part[1:] for part in re.split(r"[_\W]+", name) if part)
+
+
+class Generator:
+    def __init__(self, schemas: Dict[str, Schema]) -> None:
+        self.schemas = schemas
+        # name -> emitted source; TypedDict classes and aliases.
+        self.blocks: Dict[str, str] = {}
+        # TypedDict base classes must exist before their subclasses at runtime.
+        self.bases: Dict[str, List[str]] = {}
+        # Schemas other schemas extend with allOf (a union base's variants included); every other TypedDict is final.
+        self.base_names: set[str] = set()
+        for schema in schemas.values():
+            for ref in typed_all_of(schema):
+                base = ref_name(ref)
+                self.base_names.add(base)
+                self.base_names.update(ref_name(variant) for variant in schemas[base].get("oneOf", []))
+
+    def check_keywords(self, schema: Schema, where: str) -> None:
+        unknown = set(schema) - IGNORED - HANDLED
+        if unknown:
+            raise SystemExit(f"{where}: unsupported schema keywords {sorted(unknown)}")
+
+    # --- type expressions -------------------------------------------------
+
+    def expr(self, schema: Schema, where: str) -> str:
+        """A type expression for `schema`. References are quoted, so order never matters."""
+        self.check_keywords(schema, where)
+        if "$ref" in schema:
+            return f'"{ref_name(schema)}"'
+        if "const" in schema:
+            return f"Literal[{schema['const']!r}]"
+        if "enum" in schema:
+            return f"Literal[{', '.join(repr(v) for v in schema['enum'])}]"
+        if "oneOf" in schema:
+            return self.union([self.expr(s, where) for s in schema["oneOf"]])
+        if "allOf" in schema:
+            raise SystemExit(f"{where}: allOf is only supported on named schemas")
+        types = schema.get("type")
+        if isinstance(types, list):
+            return self.union([self.expr({**schema, "type": t}, where) for t in types])
+        if types == "string":
+            return "str"
+        if types == "integer":
+            return "int"
+        if types == "number":
+            return "float"
+        if types == "boolean":
+            return "bool"
+        if types == "null":
+            return "None"
+        if types == "array":
+            if "prefixItems" in schema:
+                if schema.get("items") is not False:
+                    raise SystemExit(f"{where}: tuples must close with items: false")
+                items = [self.expr(s, where) for s in schema["prefixItems"]]
+                return f"Tuple[{', '.join(items)}]"
+            if "items" in schema:
+                return f"Sequence[{self.expr(schema['items'], where)}]"
+            return "Sequence[Any]"
+        if types == "object" or "properties" in schema:
+            if "properties" in schema:
+                name = pascal(where)
+                self.typed_dict(name, schema)
+                return f'"{name}"'
+            extra = schema.get("additionalProperties")
+            if isinstance(extra, dict):
+                # An inline object value gets its own name, or it would take the map's.
+                return f"Mapping[str, {self.expr(extra, where + ' entry')}]"
+            return "Mapping[str, Any]"
+        if types is None:
+            # Any JSON value, such as an evaluation's raw engine response.
+            return "Any"
+        raise SystemExit(f"{where}: unsupported type {types!r}")
+
+    @staticmethod
+    def union(members: List[str]) -> str:
+        unique = list(dict.fromkeys(members))
+        if "None" in unique and len(unique) == 2:
+            other = next(m for m in unique if m != "None")
+            return f"Optional[{other}]"
+        return unique[0] if len(unique) == 1 else f"Union[{', '.join(unique)}]"
+
+    # --- named schemas ------------------------------------------------------
+
+    def named(self, name: str, schema: Schema) -> None:
+        self.check_keywords(schema, name)
+        all_of = typed_all_of(schema)
+        if all_of:
+            if len(all_of) != 1 or "$ref" not in all_of[0]:
+                raise SystemExit(f"{name}: allOf must be a single $ref")
+            base = ref_name(all_of[0])
+            base_schema = self.schemas[base]
+            if "oneOf" in base_schema:
+                # A union base: extend each variant, then union the results.
+                variants = []
+                for ref in base_schema["oneOf"]:
+                    variant = ref_name(ref)
+                    const = self.schemas[variant]["properties"]["type"]["const"]
+                    variant_name = f"{name}{pascal(const)}"
+                    self.typed_dict(variant_name, schema, base=variant, doc=schema.get("description"))
+                    variants.append(f'"{variant_name}"')
+                self.alias(name, self.union(variants), schema.get("description"))
+                return
+            self.typed_dict(name, schema, base=base)
+            return
+        if "properties" in schema:
+            self.typed_dict(name, schema)
+            return
+        self.alias(name, self.expr(schema, name), schema.get("description"))
+
+    def alias(self, name: str, expr: str, doc: Optional[str]) -> None:
+        self.blocks[name] = f"{comment(doc)}{name} = {expr}\n"
+
+    def typed_dict(self, name: str, schema: Schema, base: Optional[str] = None, doc: Optional[str] = None) -> None:
+        # `required` only ever names the schema's own properties in this contract.
+        required = set(schema.get("required", []))
+        fields = []
+        for field, field_schema in schema.get("properties", {}).items():
+            field_doc = field_schema.get("description")
+            # `{$ref, description}` and `{$ref, type: object, minProperties}` are still the ref.
+            if "$ref" in field_schema:
+                field_schema = {"$ref": field_schema["$ref"]}
+            annotation = self.expr(field_schema, f"{name}_{field}")
+            if field not in required:
+                annotation = f"NotRequired[{annotation}]"
+            fields.append((field, annotation, field_doc))
+
+        doc = doc if doc is not None else schema.get("description")
+        self.bases[name] = [base] if base else []
+        if any(keyword.iskeyword(f) for f, _, _ in fields):
+            if base:
+                raise SystemExit(f"{name}: keyword field names need the functional syntax, which cannot inherit")
+            body = ", ".join(f"{f!r}: {a}" for f, a, _ in fields)
+            self.blocks[name] = f'{comment(doc)}{name} = TypedDict("{name}", {{{body}}})\n'
+            return
+        lines = [f"class {name}({base or 'TypedDict'}):"]
+        if name not in self.base_names:
+            # Final, so type checkers narrow a union such as `BackfillEstimate | JobStarted` with `"job_id" in r`.
+            lines.insert(0, "@final")
+        if doc:
+            body = "\n".join(f"    {line}".rstrip() for line in doc.strip().splitlines())
+            lines.append(f'    """{body.lstrip()}"""')
+            lines.append("")
+        for field, annotation, field_doc in fields:
+            if field_doc:
+                lines.extend(f"    # {line}" for line in field_doc.strip().splitlines())
+            lines.append(f"    {field}: {annotation}")
+        if not fields and not doc:
+            lines.append("    pass")
+        self.blocks[name] = "\n".join(lines) + "\n"
+
+    def render(self) -> str:
+        for name, schema in self.schemas.items():
+            self.named(name, schema)
+        emitted: List[str] = []
+        done: set[str] = set()
+
+        def emit(name: str) -> None:
+            if name in done:
+                return
+            for base in self.bases.get(name, []):
+                emit(base)
+            done.add(name)
+            emitted.append(self.blocks[name])
+
+        for name in self.blocks:
+            emit(name)
+        return HEADER + "\n\n".join(emitted)
+
+
+def comment(doc: Optional[str]) -> str:
+    if not doc:
+        return ""
+    return "".join(f"# {line}".rstrip() + "\n" for line in doc.strip().splitlines())
+
+
+HEADER = '''"""Types for every schema in the API contract (`api/openapi.yaml`).
+
+Generated by `scripts/generate_types.py`. Do not edit by hand.
+
+Request and response bodies are plain JSON: these types describe it for type
+checkers and do nothing at runtime. Filters and `rank_by` are tuples.
+"""
+
+# ruff: noqa
+from typing import Any, Mapping, Optional, Sequence, Tuple, Union
+
+from typing_extensions import Literal, NotRequired, TypedDict, final
+
+
+'''
+
+
+# References to the private main spec (`§7.2.8`, `§9 Plans`) and decision log (`D-v15-611`), which the
+# package's comments never carry. The same patterns as docs/scripts/refs.ts.
+REF = r"(?:§\d+(?:\.\d+)*(?: Plans)?|D-[a-z][a-z0-9]*(?:-[a-z][a-z0-9]*)*-\d+)"
+REFS = rf"{REF}(?:\s*(?:,|;|\band\b|\bto\b)\s*{REF})*"
+
+
+def strip_internal_refs(value: Any) -> Any:
+    """Every string in `value` without spec or decision references, as the docs' API reference strips them."""
+    if isinstance(value, dict):
+        return {key: strip_internal_refs(item) for key, item in value.items()}
+    if isinstance(value, list):
+        return [strip_internal_refs(item) for item in value]
+    if not isinstance(value, str):
+        return value
+    value = re.sub(rf"\s*\({REFS}\)", "", value)
+    value = re.sub(rf",\s*{REFS}(?=\s*[,)])", "", value)
+    value = re.sub(rf"\({REFS}\s*,\s*", "(", value)
+    return re.sub(rf"\s*\bSee {REF}\.", "", value)
+
+
+def render_brand(brand: Dict[str, str]) -> str:
+    """`_brand.py`: the product name and the default base URL, from `docs/brand.json`."""
+    name, domain = brand["productName"], brand["domain"]
+    return f'''"""The product name and the API's default base URL.
+
+Generated from docs/brand.json by scripts/generate_types.py. Do not edit by hand. docs/brand.json is
+the one place the product name and domain are set: edit it, then run this script, and `pnpm generate`
+in sdks/typescript and in docs/.
+"""
+
+PRODUCT_NAME = {json.dumps(name)}
+DEFAULT_BASE_URL = {json.dumps(f"https://api.{domain}/v1")}
+'''
+
+
+def main() -> None:
+    document = strip_internal_refs(yaml.safe_load(OPENAPI.read_text()))
+    outputs = {
+        OUTPUT: Generator(document["components"]["schemas"]).render(),
+        BRAND_OUTPUT: render_brand(json.loads(BRAND.read_text())),
+    }
+    for path, source in outputs.items():
+        if "--check" not in sys.argv:
+            path.write_text(source)
+        elif path.read_text() != source:
+            raise SystemExit(f"{path} is stale: run scripts/generate_types.py")
+
+
+if __name__ == "__main__":
+    main()

brussle-1.0.0/src/brussle/__init__.py

@@ -0,0 +1,72 @@
+"""Python SDK for the Brussle API.
+
+    from brussle import Client
+
+    db = Client(api_key=...)
+    ns = db.namespace("acme/prod/tenant_123")
+    ns.query(filters=And(("attributes.plan", "Eq", "pro"), ("answers.needs_escalation.p", "Gte", 0.85)), top_k=10)
+
+Request and response bodies are the JSON of `api/openapi.yaml`, typed by
+`brussle.types`. Filters and `rank_by` are tuples. A pushed event is checked
+with `verify_webhook`, which returns it as `brussle.types.WebhookEvent`.
+"""
+
+from . import types
+from ._brand import DEFAULT_BASE_URL, PRODUCT_NAME
+from .filters import And, Not, Or
+from ._import import MAX_WRITE_BYTES, MAX_WRITE_DOCUMENTS, ImportFailure, ImportSummary
+from ._client import (
+    MAX_RETRY_AFTER_SECONDS,
+    ApiError,
+    Client,
+    EnginesClient,
+    EventsClient,
+    GroupsClient,
+    JobsClient,
+    JudgmentsClient,
+    NamespaceClient,
+    NamespacesClient,
+    NonProductionPrefixesClient,
+    OutcomesClient,
+    StartersClient,
+    SubscriptionsClient,
+    TemplatesClient,
+    TenantSummaryClient,
+    WebhookEndpointsClient,
+)
+from ._version import __version__
+from .webhooks import WebhookHeaders, WebhookVerificationError, verify_webhook
+
+__all__ = [
+    "DEFAULT_BASE_URL",
+    "MAX_RETRY_AFTER_SECONDS",
+    "MAX_WRITE_BYTES",
+    "MAX_WRITE_DOCUMENTS",
+    "PRODUCT_NAME",
+    "And",
+    "ApiError",
+    "Client",
+    "EnginesClient",
+    "EventsClient",
+    "GroupsClient",
+    "ImportFailure",
+    "ImportSummary",
+    "JobsClient",
+    "JudgmentsClient",
+    "NamespaceClient",
+    "NamespacesClient",
+    "NonProductionPrefixesClient",
+    "Not",
+    "Or",
+    "OutcomesClient",
+    "StartersClient",
+    "SubscriptionsClient",
+    "TemplatesClient",
+    "TenantSummaryClient",
+    "WebhookEndpointsClient",
+    "WebhookHeaders",
+    "WebhookVerificationError",
+    "__version__",
+    "types",
+    "verify_webhook",
+]

brussle-1.0.0/src/brussle/_brand.py

@@ -0,0 +1,9 @@
+"""The product name and the API's default base URL.
+
+Generated from docs/brand.json by scripts/generate_types.py. Do not edit by hand. docs/brand.json is
+the one place the product name and domain are set: edit it, then run this script, and `pnpm generate`
+in sdks/typescript and in docs/.
+"""
+
+PRODUCT_NAME = "Brussle"
+DEFAULT_BASE_URL = "https://api.brussle.com/v1"