cortexdb-sdk 0.2.0b2__py3-none-any.whl

_cortexdb_client/model_types/search.py

@@ -0,0 +1,165 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(frozen=True)
+class AnnSearchReport:
+    path: str
+    fallback_reason: str | None
+    fallback_performed: bool
+    requested_limit: int
+    allowed_candidates: int
+    graph_nodes: int
+    returned_candidates: int
+    visited_candidates: int
+    max_visited_candidates: int | None
+    recall_q16: int | None
+    min_recall_q16: int | None
+    hnsw_max_neighbors: int
+    hnsw_ef_search: int
+    hnsw_ef_construction: int
+    hnsw_layer_count: int
+    upper_graph_edges: int
+    require_slo: bool
+    production_safe: bool
+    slo_violations: tuple[str, ...]
+
+    @classmethod
+    def from_json(cls, value: dict[str, Any]) -> "AnnSearchReport":
+        reason = value.get("fallback_reason")
+        recall = value.get("recall_q16")
+        minimum = value.get("min_recall_q16")
+        return cls(
+            path=str(value["path"]),
+            fallback_reason=str(reason) if reason is not None else None,
+            fallback_performed=bool(value.get("fallback_performed", False)),
+            requested_limit=int(value["requested_limit"]),
+            allowed_candidates=int(value["allowed_candidates"]),
+            graph_nodes=int(value["graph_nodes"]),
+            returned_candidates=int(value["returned_candidates"]),
+            visited_candidates=int(value.get("visited_candidates", 0)),
+            max_visited_candidates=(
+                int(value["max_visited_candidates"])
+                if value.get("max_visited_candidates") is not None
+                else None
+            ),
+            recall_q16=int(recall) if recall is not None else None,
+            min_recall_q16=int(minimum) if minimum is not None else None,
+            hnsw_max_neighbors=int(value.get("hnsw_max_neighbors", 0)),
+            hnsw_ef_search=int(value.get("hnsw_ef_search", 0)),
+            hnsw_ef_construction=int(value.get("hnsw_ef_construction", 0)),
+            hnsw_layer_count=int(value.get("hnsw_layer_count", 0)),
+            upper_graph_edges=int(value.get("upper_graph_edges", 0)),
+            require_slo=bool(value.get("require_slo", False)),
+            production_safe=bool(value.get("production_safe", True)),
+            slo_violations=tuple(str(item) for item in value.get("slo_violations", [])),
+        )
+
+
+@dataclass(frozen=True)
+class AnnNoFallbackDecision:
+    allowed: bool
+    reasons: tuple[str, ...]
+
+    @classmethod
+    def from_json(cls, value: dict[str, Any]) -> "AnnNoFallbackDecision":
+        return cls(
+            allowed=bool(value["allowed"]),
+            reasons=tuple(str(item) for item in value.get("reasons", [])),
+        )
+
+
+@dataclass(frozen=True)
+class SearchRoutingDecision:
+    requested_mode: str
+    selected_strategy: str
+    reason: str
+    text_available: bool
+    vector_available: bool
+
+    @classmethod
+    def from_json(cls, value: dict[str, Any]) -> "SearchRoutingDecision":
+        return cls(
+            requested_mode=str(value["requested_mode"]),
+            selected_strategy=str(value["selected_strategy"]),
+            reason=str(value["reason"]),
+            text_available=bool(value["text_available"]),
+            vector_available=bool(value["vector_available"]),
+        )
+
+
+@dataclass(frozen=True)
+class SearchResult:
+    cell_id: int
+    score: int
+    lexical_score: int
+    vector_score: int
+    payload: str
+
+    @classmethod
+    def from_json(cls, value: dict[str, Any]) -> "SearchResult":
+        return cls(
+            cell_id=int(value["cell_id"]),
+            score=int(value["score"]),
+            lexical_score=int(value["lexical_score"]),
+            vector_score=int(value["vector_score"]),
+            payload=str(value["payload"]),
+        )
+
+
+@dataclass(frozen=True)
+class SearchResponse:
+    search_mode: str
+    routing: SearchRoutingDecision | None
+    rerank: str | None
+    ann_report: AnnSearchReport | None
+    no_fallback_decision: AnnNoFallbackDecision | None
+    results: tuple[SearchResult, ...]
+
+    @classmethod
+    def from_json(cls, value: dict[str, Any]) -> "SearchResponse":
+        report = value.get("ann_report")
+        routing = value.get("routing")
+        decision = value.get("no_fallback_decision")
+        return cls(
+            search_mode=str(value["search_mode"]),
+            routing=SearchRoutingDecision.from_json(routing) if routing else None,
+            rerank=str(value["rerank"]) if value.get("rerank") is not None else None,
+            ann_report=AnnSearchReport.from_json(report) if report else None,
+            no_fallback_decision=(
+                AnnNoFallbackDecision.from_json(decision) if decision else None
+            ),
+            results=tuple(SearchResult.from_json(row) for row in value["results"]),
+        )
+
+
+@dataclass(frozen=True)
+class AnnEvaluationResponse:
+    available: bool
+    reason: str | None
+    ann_report: AnnSearchReport | None
+    no_fallback_decision: AnnNoFallbackDecision | None
+    exact_top_k: tuple[int, ...]
+    ann_top_k: tuple[int, ...]
+    overlap_count: int
+    recall_q16: int
+
+    @classmethod
+    def from_json(cls, value: dict[str, Any]) -> "AnnEvaluationResponse":
+        report = value.get("ann_report")
+        decision = value.get("no_fallback_decision")
+        reason = value.get("reason")
+        return cls(
+            available=bool(value["available"]),
+            reason=str(reason) if reason is not None else None,
+            ann_report=AnnSearchReport.from_json(report) if report else None,
+            no_fallback_decision=(
+                AnnNoFallbackDecision.from_json(decision) if decision else None
+            ),
+            exact_top_k=tuple(int(row) for row in value["exact_top_k"]),
+            ann_top_k=tuple(int(row) for row in value["ann_top_k"]),
+            overlap_count=int(value["overlap_count"]),
+            recall_q16=int(value["recall_q16"]),
+        )

_cortexdb_client/model_types/verification.py

@@ -0,0 +1,88 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(frozen=True)
+class EvidenceResponse:
+    cell_id: int
+    matched_terms: int
+    match_score_q16: int
+    match_kind: str
+    source_trust_q16: int
+    source_trust_category: str
+    citation: str | None
+    payload_text: str
+
+    @classmethod
+    def from_json(cls, value: dict[str, Any]) -> "EvidenceResponse":
+        return cls(
+            cell_id=int(value["cell_id"]),
+            matched_terms=int(value["matched_terms"]),
+            match_score_q16=int(value.get("match_score_q16", 0)),
+            match_kind=str(value.get("match_kind", "")),
+            source_trust_q16=int(value["source_trust_q16"]),
+            source_trust_category=str(value.get("source_trust_category", "")),
+            citation=str(value["citation"]) if value.get("citation") is not None else None,
+            payload_text=str(value["payload_text"]),
+        )
+
+
+@dataclass(frozen=True)
+class GuardResponse:
+    cell_id: int | None
+    code: str
+    message: str
+
+    @classmethod
+    def from_json(cls, value: dict[str, Any]) -> "GuardResponse":
+        return cls(
+            cell_id=int(value["cell_id"]) if value.get("cell_id") is not None else None,
+            code=str(value["code"]),
+            message=str(value["message"]),
+        )
+
+
+@dataclass(frozen=True)
+class NumericConflictResponse:
+    metric: str
+    left: str
+    right: str
+
+    @classmethod
+    def from_json(cls, value: dict[str, Any]) -> "NumericConflictResponse":
+        return cls(
+            metric=str(value["metric"]),
+            left=str(value["left"]),
+            right=str(value["right"]),
+        )
+
+
+@dataclass(frozen=True)
+class VerificationReportResponse:
+    fact: str
+    status: str
+    verdict: str
+    confidence_q16: int
+    evidence: tuple[EvidenceResponse, ...]
+    contradicting_evidence: tuple[EvidenceResponse, ...]
+    guards: tuple[GuardResponse, ...]
+    supporting: tuple[EvidenceResponse, ...]
+    contradicting: tuple[EvidenceResponse, ...]
+    numeric_conflicts: tuple[NumericConflictResponse, ...]
+
+    @classmethod
+    def from_json(cls, value: dict[str, Any]) -> "VerificationReportResponse":
+        return cls(
+            fact=str(value["fact"]),
+            status=str(value["status"]),
+            verdict=str(value["verdict"]),
+            confidence_q16=int(value.get("confidence_q16", 0)),
+            evidence=tuple(EvidenceResponse.from_json(row) for row in value["evidence"]),
+            contradicting_evidence=tuple(EvidenceResponse.from_json(row) for row in value["contradicting_evidence"]),
+            guards=tuple(GuardResponse.from_json(row) for row in value["guards"]),
+            supporting=tuple(EvidenceResponse.from_json(row) for row in value["supporting"]),
+            contradicting=tuple(EvidenceResponse.from_json(row) for row in value["contradicting"]),
+            numeric_conflicts=tuple(NumericConflictResponse.from_json(row) for row in value["numeric_conflicts"]),
+        )

_cortexdb_client/models.py

@@ -0,0 +1,73 @@
+"""Public response models for the Python client.
+
+This module remains the stable import surface and re-exports the domain-split
+model implementations from ``_cortexdb_client.model_types``.
+"""
+
+from .model_types import (
+    AnnEvaluationResponse,
+    AnnNoFallbackDecision,
+    AnnSearchReport,
+    AnswerGroundingReportResponse,
+    AnswerGroundingSpanResponse,
+    AqlCellResponse,
+    AqlQueryCacheStatsResponse,
+    AqlResponse,
+    CellLookupResponse,
+    CellResponse,
+    ContextPackAnomalyResponse,
+    ContextPackCellResponse,
+    ContextPackResponse,
+    DeleteJobResponse,
+    EvidenceResponse,
+    ExplainResponse,
+    GroundedAnswerResponse,
+    GuardResponse,
+    HealthResponse,
+    IngestResponse,
+    IngestionJobResponse,
+    NumericConflictResponse,
+    PutCellResponse,
+    RememberResponse,
+    SearchResponse,
+    SearchResult,
+    SearchRoutingDecision,
+    SourceRefResponse,
+    StatsResponse,
+    ValidationResponse,
+    VerificationReportResponse,
+)
+
+__all__ = [
+    "AnnEvaluationResponse",
+    "AnnNoFallbackDecision",
+    "AnnSearchReport",
+    "AnswerGroundingReportResponse",
+    "AnswerGroundingSpanResponse",
+    "AqlCellResponse",
+    "AqlQueryCacheStatsResponse",
+    "AqlResponse",
+    "CellLookupResponse",
+    "CellResponse",
+    "ContextPackAnomalyResponse",
+    "ContextPackCellResponse",
+    "ContextPackResponse",
+    "DeleteJobResponse",
+    "EvidenceResponse",
+    "ExplainResponse",
+    "GroundedAnswerResponse",
+    "GuardResponse",
+    "HealthResponse",
+    "IngestResponse",
+    "IngestionJobResponse",
+    "NumericConflictResponse",
+    "PutCellResponse",
+    "RememberResponse",
+    "SearchResponse",
+    "SearchResult",
+    "SearchRoutingDecision",
+    "SourceRefResponse",
+    "StatsResponse",
+    "ValidationResponse",
+    "VerificationReportResponse",
+]

_cortexdb_client/py.typed

@@ -0,0 +1 @@
+

_cortexdb_client/transport.py

@@ -0,0 +1,94 @@
+from __future__ import annotations
+
+import json
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any
+
+from .errors import CortexDBError
+
+
+def request_json(
+    *,
+    base_url: str,
+    tenant: str | None,
+    token: str | None,
+    timeout_seconds: float,
+    max_retries: int,
+    retry_delay_seconds: float,
+    opener: Any | None,
+    method: str,
+    path: str,
+    body: bytes,
+) -> dict[str, Any]:
+    headers = {"content-type": "application/json"}
+    if token:
+        headers["authorization"] = f"Bearer {token}"
+    url = f"{base_url}{scoped_path(path, tenant)}"
+    attempt = 0
+    while True:
+        request = urllib.request.Request(url, data=body or None, headers=headers, method=method)
+        try:
+            with open_request(opener, request, timeout_seconds) as response:
+                return json.loads(response.read().decode())
+        except urllib.error.HTTPError as error:
+            body_text = error.read().decode()
+            if attempt < max_retries and is_retryable(error.code, body_text):
+                attempt += 1
+                sleep_before_retry(retry_delay_seconds, attempt)
+                continue
+            raise CortexDBError.from_response(error.code, body_text) from None
+        except urllib.error.URLError as error:
+            if attempt < max_retries:
+                attempt += 1
+                sleep_before_retry(retry_delay_seconds, attempt)
+                continue
+            reason = str(error.reason)
+            raise CortexDBError(reason, code=None, status=None, body=reason) from None
+
+
+def build_opener() -> Any:
+    return urllib.request.build_opener()
+
+
+def close_opener(opener: Any | None) -> None:
+    if opener is None:
+        return
+    for handler in getattr(opener, "handlers", ()):
+        close = getattr(handler, "close", None)
+        if callable(close):
+            close()
+
+
+def open_request(opener: Any | None, request: urllib.request.Request, timeout_seconds: float) -> Any:
+    if opener is not None:
+        return opener.open(request, timeout=timeout_seconds)
+    return urllib.request.urlopen(request, timeout=timeout_seconds)
+
+
+def scoped_path(path: str, tenant: str | None) -> str:
+    if not tenant or tenant == "default":
+        return path
+    separator = "&" if "?" in path else "?"
+    encoded = urllib.parse.urlencode({"tenant": tenant})
+    return f"{path}{separator}{encoded}"
+
+
+def is_retryable(status: int, body_text: str) -> bool:
+    if status in (502, 504):
+        return True
+    if status != 503:
+        return False
+    try:
+        code = json.loads(body_text).get("code")
+    except json.JSONDecodeError:
+        return True
+    return code in ("database_busy", "service_unavailable")
+
+
+def sleep_before_retry(delay_seconds: float, attempt: int) -> None:
+    if delay_seconds <= 0:
+        return
+    time.sleep(delay_seconds * attempt)

cortexdb_client.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+from _cortexdb_client import (
+    AnnEvaluationResponse,
+    AnnSearchReport,
+    AnswerGroundingReportResponse,
+    AnswerGroundingSpanResponse,
+    AqlCellResponse,
+    AqlResponse,
+    CellLookupResponse,
+    CellResponse,
+    ContextPackAnomalyResponse,
+    ContextPackCellResponse,
+    ContextPackResponse,
+    CortexDBClient,
+    CortexDBError,
+    DeleteJobResponse,
+    EvidenceResponse,
+    ExplainResponse,
+    GroundedAnswerResponse,
+    GuardResponse,
+    HealthResponse,
+    IngestResponse,
+    IngestionJobResponse,
+    NumericConflictResponse,
+    PutCellResponse,
+    RememberResponse,
+    SearchResponse,
+    SearchResult,
+    SourceRefResponse,
+    StatsResponse,
+    ValidationResponse,
+    VerificationReportResponse,
+    build_remember_aql,
+    build_retrieve_context_aql,
+    build_verify_fact_aql,
+    openapi_types,
+)
+
+__all__ = [
+    "AnnEvaluationResponse",
+    "AnnSearchReport",
+    "AnswerGroundingReportResponse",
+    "AnswerGroundingSpanResponse",
+    "AqlCellResponse",
+    "AqlResponse",
+    "CellLookupResponse",
+    "CellResponse",
+    "ContextPackAnomalyResponse",
+    "ContextPackCellResponse",
+    "ContextPackResponse",
+    "CortexDBClient",
+    "CortexDBError",
+    "DeleteJobResponse",
+    "EvidenceResponse",
+    "ExplainResponse",
+    "GroundedAnswerResponse",
+    "GuardResponse",
+    "HealthResponse",
+    "IngestResponse",
+    "IngestionJobResponse",
+    "NumericConflictResponse",
+    "PutCellResponse",
+    "RememberResponse",
+    "SearchResponse",
+    "SearchResult",
+    "SourceRefResponse",
+    "StatsResponse",
+    "ValidationResponse",
+    "VerificationReportResponse",
+    "build_remember_aql",
+    "build_retrieve_context_aql",
+    "build_verify_fact_aql",
+    "openapi_types",
+]

cortexdb_sdk-0.2.0b2.dist-info/METADATA

@@ -0,0 +1,58 @@
+Metadata-Version: 2.4
+Name: cortexdb-sdk
+Version: 0.2.0b2
+Summary: Beta CortexDB HTTP client
+Author: CortexDB
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/AubakirovArman/CortexDB
+Project-URL: Repository, https://github.com/AubakirovArman/CortexDB
+Project-URL: Issues, https://github.com/AubakirovArman/CortexDB/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# cortexdb-sdk
+
+Stdlib Python client for the Core Alpha CortexDB HTTP API.
+
+```python
+from cortexdb_client import ContextPackResponse, CortexDBClient
+
+client = CortexDBClient("http://127.0.0.1:8181").with_retries(3, retry_delay_seconds=0.1).with_timeout(5.0)
+with client.with_session() as session:
+    tenant_client = session.with_tenant("tenant:alpha")
+    session.put_cell(1, "scope=default\nstatus=ready\nhello")
+    print(session.get_cell(1))
+    print(tenant_client.stats())
+    results = session.search_response("default", "hello")
+    print(results.search_mode, results.ann_report, results.results)
+    ann_eval = session.evaluate_ann_response("default", [1, 2, 3])
+    print(ann_eval.available, ann_eval.recall_q16)
+    retrieve = session.build_retrieve_context_aql("hello", "default", limit_candidates=10)
+    context: ContextPackResponse = session.context_response("default", retrieve)
+    verify = session.verify_response("default", session.build_verify_fact_aql("hello", "default"))
+    remember = session.remember_response("default", session.build_remember_aql("hello", "default", "decision", ttl_seconds=3600))
+    print(context.token_budget_tokens, verify.status, remember.cell_id)
+    print(session.ingest_text("default", "hello from sdk"))
+
+grounded = client.answer_with_grounded_context(
+    "default",
+    "default",
+    "What does the context say about hello?",
+    lambda pack: pack.cells[0].payload_text if pack.cells else "Not enough information.",
+    mode="audit",
+    limit_candidates=10,
+)
+print(grounded.citations, grounded.grounding.answer_supported)
+```
+
+The package metadata is prepared for PyPI as `cortexdb-sdk`. Publication is
+not automatic; run `../publish/check.sh` before cutting a package release.
+Run `make sdk-contract-check` from the repository root to validate this client
+against a freshly built local `cortex-server` together with the TypeScript and
+Rust SDKs.

cortexdb_sdk-0.2.0b2.dist-info/RECORD

@@ -0,0 +1,23 @@
+cortexdb_client.py,sha256=ki5o-JIO1hv4J6y2ZsznuMkzqO-fPQfOl8VgzwjeaVo,1772
+_cortexdb_client/__init__.py,sha256=GG0k-qtx-jhYK3HNAf2xODO7x6WhsXdmOT49QvJbwaI,1845
+_cortexdb_client/answering.py,sha256=e03Y6QwrU1eAKtF6R2eAF_g3sdqyaIsxj28ak0DXBKM,1936
+_cortexdb_client/aql.py,sha256=ZUrSAha0ESPqzKuP7UCGem84dl6mlnvHA9dLc35mUTM,3624
+_cortexdb_client/client.py,sha256=Upp3Xo7LumXgLwIIi-SG7kEGPDrZ-2D3jlAdqtb2Ly4,10719
+_cortexdb_client/errors.py,sha256=pACgB9tQTBfCibJ4laxF1hSmhSqbgd422_7ucXMkNHI,895
+_cortexdb_client/grounding.py,sha256=7BCLgTy7VfXVinrIA0O9cWng_uSFuZs5CLM2H0RLocQ,6063
+_cortexdb_client/models.py,sha256=c5uWummL6Y9o1ERNKA4kspvEbbJba9DZ9XoydctEYG0,1810
+_cortexdb_client/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+_cortexdb_client/transport.py,sha256=fKVsFDjN-ExqkBXEK9TCbuUmrrhbP1Ik9l7UiDKhlIw,2894
+_cortexdb_client/generated/__init__.py,sha256=UkMUyscgcpuoy1UM-IYz8_zGxQBSx1ahM6X6-yf1mdg,94
+_cortexdb_client/generated/openapi_types.py,sha256=fyGDcN2bgQkzcCVhGydqe9F5fndBDPqSx5KNRIR9ZO0,36881
+_cortexdb_client/model_types/__init__.py,sha256=1K8y1sXZYaX3sBvB9shfz6B3t4sYQsteOc5Yop2q6nw,1692
+_cortexdb_client/model_types/context.py,sha256=gvm7ucTiAuXEzZFrVbo6ns_830avhv5YXxSG3Pbk3LA,5138
+_cortexdb_client/model_types/core.py,sha256=rOZvJlWROY3XXpMowJIp1pl8Dc2UlUPMbBbFIlV-90g,6558
+_cortexdb_client/model_types/ingestion.py,sha256=8Br2MSjuCuMbHtKtLPF2WbzVNgi2bDoHxsllEZn1PR8,2106
+_cortexdb_client/model_types/memory.py,sha256=tLfkvH89Xc50VCELAoEA0XUb271xMtVWDyUDR2atPNI,498
+_cortexdb_client/model_types/search.py,sha256=t3VVl321qXCrsGSOQbuPoAEZV3fIKf0ftATq8J4eKYY,5876
+_cortexdb_client/model_types/verification.py,sha256=3nZm8CDO5VJnqCWZwwTiTYGkK3TWXv9a_HfqSrcFyFc,3016
+cortexdb_sdk-0.2.0b2.dist-info/METADATA,sha256=XcDiU8cqarbT__My75JXyF5mALm9u8oRFXxbIeUOaPc,2598
+cortexdb_sdk-0.2.0b2.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+cortexdb_sdk-0.2.0b2.dist-info/top_level.txt,sha256=KdcueE7PysJz00zDkan_K1om9hWVzWMeMohEdrrRi-8,33
+cortexdb_sdk-0.2.0b2.dist-info/RECORD,,

cortexdb_sdk-0.2.0b2.dist-info/WHEEL

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

cortexdb_sdk-0.2.0b2.dist-info/top_level.txt

@@ -0,0 +1,2 @@
+_cortexdb_client
+cortexdb_client