helixor-reasoner 0.2.0__tar.gz

helixor_reasoner-0.2.0/LICENSE

@@ -0,0 +1,17 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   Copyright 2026 Helixor AI, Inc.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

helixor_reasoner-0.2.0/PKG-INFO

@@ -0,0 +1,57 @@
+Metadata-Version: 2.4
+Name: helixor-reasoner
+Version: 0.2.0
+Summary: Typed client for the Helixor reasoning API: decide, fetch proofs, report outcomes.
+Project-URL: Homepage, https://helixor.dev
+Author-email: Helixor <engineering@helixor.ai>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: decisions,helixor,reasoning,sdk
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.7
+Description-Content-Type: text/markdown
+
+# helixor-reasoner
+
+Typed client for the Helixor reasoning API: decide, fetch proofs, report outcomes.
+
+## Install
+
+```bash
+pip install helixor-reasoner
+```
+
+## Usage
+
+```python
+from helixor_reasoner import ApiClient
+
+with ApiClient(base_url="https://api.example.com") as client:
+    result = client.get_health()
+```
+
+Responses are validated against the API contract; non-2xx responses raise typed exceptions.
+
+## Operations
+
+| Method | HTTP | Summary |
+| --- | --- | --- |
+| `decide` | `POST /v1/decide` | Decide |
+| `get_health` | `GET /v1/health` | Health |
+
+## License
+
+`Apache-2.0` - see [LICENSE](LICENSE).
+
+## Links
+
+- Homepage: https://helixor.dev

helixor_reasoner-0.2.0/README.md

@@ -0,0 +1,35 @@
+# helixor-reasoner
+
+Typed client for the Helixor reasoning API: decide, fetch proofs, report outcomes.
+
+## Install
+
+```bash
+pip install helixor-reasoner
+```
+
+## Usage
+
+```python
+from helixor_reasoner import ApiClient
+
+with ApiClient(base_url="https://api.example.com") as client:
+    result = client.get_health()
+```
+
+Responses are validated against the API contract; non-2xx responses raise typed exceptions.
+
+## Operations
+
+| Method | HTTP | Summary |
+| --- | --- | --- |
+| `decide` | `POST /v1/decide` | Decide |
+| `get_health` | `GET /v1/health` | Health |
+
+## License
+
+`Apache-2.0` - see [LICENSE](LICENSE).
+
+## Links
+
+- Homepage: https://helixor.dev

helixor_reasoner-0.2.0/helixor_reasoner/__init__.py

@@ -0,0 +1,7 @@
+from .client import ApiClient
+from . import models
+from .contract import CONTRACT_HASH_ALGORITHM, OPERATION_HASH_ALGORITHM, OPERATION_SHA256, SPEC_SHA256
+from .operation_contracts import OPERATION_CONTRACTS, OperationContractsManifest
+from .errors import ApiException, ApiHttpException, ApiResponseValidationException
+
+__all__ = ["ApiClient", "models", "CONTRACT_HASH_ALGORITHM", "OPERATION_HASH_ALGORITHM", "OPERATION_SHA256", "SPEC_SHA256", "OPERATION_CONTRACTS", "OperationContractsManifest", "ApiException", "ApiHttpException", "ApiResponseValidationException"]

helixor_reasoner-0.2.0/helixor_reasoner/_operations/__init__.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ..client import ApiClient
+
+from .public_operations import PublicOperations, PublicResourceMethods
+
+
+class PublicResource(PublicResourceMethods):
+    def __init__(self, client: ApiClient) -> None:
+        self._client = client
+
+
+__all__ = ['PublicOperations', 'PublicResourceMethods', 'PublicResource']

helixor_reasoner-0.2.0/helixor_reasoner/_operations/public_operations.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+from typing import Any, Iterator, Literal, Mapping, Protocol, TYPE_CHECKING
+
+from .. import models as Models
+
+if TYPE_CHECKING:
+    from ..client import ApiClient
+
+
+class _ClientHelpers(Protocol):
+    """What the operation methods below call on self; ApiClient satisfies it."""
+
+    def request(self, method: str, path: str, *, body: Any = None, content_type: str = 'application/json', response_model: type[Any] | None = None, request_headers: Mapping[str, Any] | None = None) -> Any: ...
+
+
+class PublicOperations:
+    def decide(self: _ClientHelpers, body: Models.DecideRequest) -> Models.DecisionResponse:
+        path = '/v1/decide'
+        return self.request('POST', path, body=body, content_type='application/json', response_model=Models.DecisionResponse)
+
+    def get_health(self: _ClientHelpers) -> Models.HealthResponse:
+        path = '/v1/health'
+        return self.request('GET', path, response_model=Models.HealthResponse)
+
+
+class PublicResourceMethods:
+    _client: ApiClient
+
+    def decide(self, body: Models.DecideRequest) -> Models.DecisionResponse:
+        return self._client.decide(body=body)
+
+    def get_health(self) -> Models.HealthResponse:
+        return self._client.get_health()

helixor_reasoner-0.2.0/helixor_reasoner/client.py

@@ -0,0 +1,193 @@
+from __future__ import annotations
+
+import json
+import time
+from typing import Any, Callable, Iterator, Mapping, TypeVar
+from urllib.parse import quote, urlencode
+
+import httpx
+
+from pydantic import BaseModel, TypeAdapter, ValidationError
+
+from . import models as Models
+from ._operations import PublicOperations, PublicResource
+from .errors import ApiDeserializationException, ApiHttpException, ApiResponseValidationException, ApiSerializationException, ApiValidationException, RawResponse
+
+
+T = TypeVar("T")
+
+
+class ApiClient(PublicOperations):
+    def __init__(self, base_url: str | None = None, headers: Mapping[str, str] | None = None, api_key: str | Callable[[], str] | None = None, timeout: float | None = None) -> None:
+        self.base_url = (base_url or None or '').rstrip('/')
+        if not self.base_url:
+            raise ValueError('ApiClient requires base_url: this SDK has no default API host')
+        self.headers = dict(headers or {})
+        self.api_key = api_key
+        # The configured timeout is the DEFAULT, not a ceiling. A caller driving an
+        # LLM-backed operation legitimately needs longer than a CRUD caller, and one
+        # baked value forces it to reach around the generated client.
+        self.timeout = 60.0 if timeout is None else timeout
+        self._client = httpx.Client(base_url=self.base_url, headers=self.headers, timeout=self.timeout, follow_redirects=False)
+
+        self.public = PublicResource(self)
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> ApiClient:
+        return self
+
+    def __exit__(self, exc_type: Any, exc: Any, traceback: Any) -> None:
+        self.close()
+
+    def request(self, method: str, path: str, *, body: Any = None, content_type: str = 'application/json', response_model: type[T] | None = None, request_headers: Mapping[str, Any] | None = None) -> T | Any | None:
+        try:
+            request_kwargs = self._encode_request_body(body, content_type)
+        except Exception as exc:
+            raise ApiSerializationException("Unable to serialize API request body") from exc
+        path = self._append_auth_query(path)
+        headers = self._build_headers(content_type)
+        if request_headers is not None:
+            headers.update({name: str(value) for name, value in request_headers.items() if value is not None})
+        max_attempts = 3
+        retry_statuses = [408, 409, 429, 500, 502, 503, 504]
+        retry_methods = ['GET', 'HEAD', 'OPTIONS', 'PUT', 'DELETE']
+        backoff = 0.25
+        max_backoff = 2.0
+        response = None
+        for attempt in range(1, max_attempts + 1):
+            try:
+                with self._client.stream(method, path, headers=headers, **request_kwargs) as streamed_response:
+                    declared_length = streamed_response.headers.get('Content-Length')
+                    if declared_length is not None and int(declared_length) > 10485760:
+                        raise ApiDeserializationException('API response exceeds the configured size limit')
+                    content = bytearray()
+                    for chunk in streamed_response.iter_bytes():
+                        if len(content) + len(chunk) > 10485760:
+                            raise ApiDeserializationException('API response exceeds the configured size limit')
+                        content.extend(chunk)
+                    # iter_bytes() already decoded the body; drop the encoding headers so
+                    # the rebuilt response does not decode (e.g. gunzip) it a second time.
+                    decoded_headers = [
+                        (name, value) for name, value in streamed_response.headers.multi_items()
+                        if name.lower() not in ('content-encoding', 'content-length')
+                    ]
+                    response = httpx.Response(
+                        status_code=streamed_response.status_code,
+                        headers=decoded_headers,
+                        content=bytes(content),
+                    )
+            except httpx.RequestError:
+                if attempt >= max_attempts or method.upper() not in retry_methods or False:
+                    raise
+                time.sleep(min(backoff, max_backoff))
+                backoff *= 2
+                continue
+            if response.status_code not in retry_statuses or method.upper() not in retry_methods or attempt >= max_attempts:
+                break
+            time.sleep(min(backoff, max_backoff))
+            backoff *= 2
+        assert response is not None
+        if response.status_code >= 400:
+            parsed_error: Any
+            try:
+                parsed_error = response.json()
+            except ValueError:
+                parsed_error = None
+            raise ApiHttpException(
+                f'API request failed with status {response.status_code}',
+                raw_response=RawResponse(response.status_code, response.headers, response.text),
+                parsed_error=parsed_error,
+            )
+        if not response.content:
+            return None
+        if response_model is bytes:
+            return response.content
+        try:
+            payload = response.json()
+        except ValueError as exc:
+            raise ApiDeserializationException(
+                "Unable to parse API response JSON",
+                raw_response=RawResponse(response.status_code, response.headers, response.text),
+            ) from exc
+        if response_model is None:
+            return payload
+        try:
+            return TypeAdapter(response_model).validate_python(payload)
+        except ValidationError as exc:
+            raise ApiResponseValidationException(
+                "API response failed schema validation",
+                raw_response=RawResponse(response.status_code, response.headers, response.text),
+                parsed_error=payload,
+            ) from exc
+
+    def _encode_body(self, body: Any) -> Any:
+        if isinstance(body, BaseModel):
+            return body.model_dump(mode="json", by_alias=True, exclude_none=True)
+        return body
+
+    def _encode_request_body(self, body: Any, content_type: str) -> dict[str, Any]:
+        if body is None:
+            return {}
+        if content_type == 'multipart/form-data':
+            multipart_body = (
+                body.model_dump(mode='python', by_alias=True, exclude_none=True)
+                if isinstance(body, BaseModel)
+                else body
+            )
+            if not isinstance(multipart_body, Mapping):
+                raise ApiSerializationException('Multipart request body must be a mapping')
+            parts: dict[str, Any] = {}
+            for key, value in multipart_body.items():
+                if value is None:
+                    continue
+                if isinstance(value, (bytes, bytearray, memoryview)):
+                    parts[key] = (key, bytes(value), 'application/octet-stream')
+                    continue
+                if isinstance(value, bool):
+                    form_value = 'true' if value else 'false'
+                elif isinstance(value, (dict, list)):
+                    form_value = json.dumps(value, separators=(',', ':'))
+                else:
+                    form_value = str(value)
+                parts[key] = (None, form_value)
+            return {'files': parts}
+        encoded = self._encode_body(body)
+        if content_type == 'application/json':
+            return {'json': encoded}
+        if content_type == 'application/x-www-form-urlencoded':
+            return {'data': encoded}
+        if content_type in {'application/octet-stream', 'application/pdf'} or content_type.startswith('image/'):
+            return {'content': encoded}
+        return {'content': encoded}
+
+    def _resolve_auth_value(self, value: str | Callable[[], str] | None) -> str | None:
+        if value is None:
+            return None
+        return value() if callable(value) else value
+
+    def _build_headers(self, content_type: str = 'application/json') -> dict[str, str]:
+        headers = dict(self.headers)
+        if content_type != 'multipart/form-data':
+            headers.setdefault('Content-Type', content_type)
+        api_key = self._resolve_auth_value(self.api_key)
+        if api_key:
+            headers['X-API-Key'] = api_key
+        return headers
+
+    def _append_auth_query(self, path: str) -> str:
+        return path
+
+    def _build_path(self, path: str, params: Mapping[str, Any]) -> str:
+        for key, value in params.items():
+            if value is None or value == "":
+                raise ApiValidationException(f"Missing required path parameter: {key}")
+            path = path.replace("{" + key + "}", quote(str(value), safe=""))
+        return path
+
+    def _append_query(self, path: str, params: Mapping[str, Any]) -> str:
+        query_params = {key: value for key, value in params.items() if value is not None}
+        if not query_params:
+            return path
+        return path + "?" + urlencode(query_params, doseq=True)

helixor_reasoner-0.2.0/helixor_reasoner/contract.py

@@ -0,0 +1,15 @@
+"""Generated contract identity for drift detection.
+
+SPEC_SHA256 is the canonical hash of the whole OpenAPI document.
+OPERATION_SHA256 is the wire identity of each HTTP operation; login
+compatibility uses the login operation hash, not the document hash.
+"""
+
+SPEC_SHA256 = "a81ad4404e5cdbbc52afdc4a70c033345aa3fe39074cc42c9f30b4e082f30fa8"
+CONTRACT_VERSION = "0.1.0"
+CONTRACT_HASH_ALGORITHM = "sha256-canonical-json-v1"
+OPERATION_HASH_ALGORITHM = "sha256-canonical-json-operation-v1"
+OPERATION_SHA256 = {
+  "GET /v1/health": "5ee627b0358ea87788b51bfe6e9dceca9e8c790b52d52d3e53e626d72cd80f46",
+  "POST /v1/decide": "64422b005c949027ebc3599e842c9f9ae1b4a4f2e5dbfd727ec4a49f629d508a"
+}

helixor_reasoner-0.2.0/helixor_reasoner/errors.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Mapping
+
+
+@dataclass(slots=True)
+class RawResponse:
+    status_code: int | None
+    headers: Mapping[str, str]
+    body: str | bytes | None
+
+
+class ApiErrorBody(dict):
+    pass
+
+
+class ApiException(Exception):
+    def __init__(self, message: str, *, raw_response: RawResponse | None = None, parsed_error: Any = None) -> None:
+        super().__init__(message)
+        self.raw_response = raw_response
+        self.parsed_error = parsed_error
+
+
+class ApiHttpException(ApiException):
+    pass
+
+
+class ApiValidationException(ApiException):
+    pass
+
+
+class ApiResponseValidationException(ApiException):
+    pass
+
+
+class ApiNetworkException(ApiException):
+    pass
+
+
+class ApiSerializationException(ApiException):
+    pass
+
+
+class ApiDeserializationException(ApiException):
+    pass

helixor_reasoner-0.2.0/helixor_reasoner/models.py

@@ -0,0 +1,191 @@
+from __future__ import annotations
+
+import logging
+import warnings
+from datetime import date, datetime
+from typing import Annotated, Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+
+_LOGGER = logging.getLogger(__name__)
+
+_SEEN_UNKNOWN_FIELDS: set[tuple[str, tuple[str, ...]]] = set()
+
+
+class _UnknownFieldWarningModel(BaseModel):
+    """Accepts unknown fields but reports them once per model and field set.
+
+    The unknown_fields policy for this SDK is "warn". Parsing stays permissive
+    on purpose: a producer adding a field must not break a consumer mid-rolling
+    deploy. But silence is how a renamed field becomes a None that surfaces as a
+    confusing error several layers away, so each new shape is logged once --
+    deduplicated because these models are parsed per response and an unbounded
+    log would be worse than no log at all.
+    """
+
+    @model_validator(mode="after")
+    def _report_unknown_fields(self):
+        extra = self.model_extra
+        if not extra:
+            return self
+        names = tuple(sorted(extra))
+        key = (type(self).__name__, names)
+        if key not in _SEEN_UNKNOWN_FIELDS:
+            _SEEN_UNKNOWN_FIELDS.add(key)
+            _LOGGER.warning(
+                "%s received field(s) not declared by the contract: %s. "
+                "The producer may be ahead of this generated SDK; regenerate it "
+                "if these fields are expected.",
+                type(self).__name__,
+                ", ".join(names),
+            )
+        return self
+
+
+class ComposedVerdict(_UnknownFieldWarningModel):
+    model_config = ConfigDict(populate_by_name=True, extra='allow')
+    band: str | None = None
+    rule_ids: list[str] | None = None
+    verdict: str
+
+
+class DecideFailureDetail(_UnknownFieldWarningModel):
+    model_config = ConfigDict(populate_by_name=True, extra='allow')
+    failure_code: str
+    message: str
+
+
+class DecideFailureResponse(_UnknownFieldWarningModel):
+    model_config = ConfigDict(populate_by_name=True, extra='allow')
+    detail: DecideFailureDetail
+
+
+with warnings.catch_warnings():
+    # Contract field(s) intentionally shadow pydantic BaseModel attributes: schema.
+    warnings.filterwarnings('ignore', message='^Field name "schema" in "DecideRequest" shadows an attribute in parent "_UnknownFieldWarningModel"$', category=UserWarning)
+    class DecideRequest(_UnknownFieldWarningModel):
+        model_config = ConfigDict(populate_by_name=True, extra='allow')
+        answer_under_test: Any | None = None
+        evidence: list[EvidenceItem] | None = None
+        goal: str
+        questions: list[DecisionQuestion]
+        require: DecideRequire | None = None
+        schema: Literal['helixor.decide_request.v1'] = Field(default='helixor.decide_request.v1')
+        scope: DecideScope | None = None
+
+
+class DecideRequire(_UnknownFieldWarningModel):
+    model_config = ConfigDict(populate_by_name=True, extra='allow')
+    max_latency_ms: int | None = None
+    min_confidence: float | None = None
+    proof: bool | None = None
+
+
+class DecideScope(_UnknownFieldWarningModel):
+    model_config = ConfigDict(populate_by_name=True, extra='allow')
+    domain: str | None = None
+    org: str | None = None
+    session: str | None = None
+    tenant: str | None = None
+    user: str | None = None
+
+
+class DecisionCost(_UnknownFieldWarningModel):
+    model_config = ConfigDict(populate_by_name=True, extra='allow')
+    units: int
+
+
+class DecisionOption(_UnknownFieldWarningModel):
+    model_config = ConfigDict(populate_by_name=True, extra='allow')
+    criteria: str | None = None
+    label: str | None = None
+    option_id: str
+
+
+class DecisionProof(_UnknownFieldWarningModel):
+    model_config = ConfigDict(populate_by_name=True, extra='allow')
+    artifact: str | None = None
+    checks: list[str] | None = None
+    citations: list[str] | None = None
+    digest: str | None = None
+    kind: Literal['replay', 'solver_certificate', 'citation_set', 'tcn_consistent', 're_derivation_agreement', 'distribution_threshold']
+    threshold: float | None = None
+
+
+with warnings.catch_warnings():
+    # Contract field(s) intentionally shadow pydantic BaseModel attributes: schema.
+    warnings.filterwarnings('ignore', message='^Field name "schema" in "DecisionQuestion" shadows an attribute in parent "_UnknownFieldWarningModel"$', category=UserWarning)
+    class DecisionQuestion(_UnknownFieldWarningModel):
+        model_config = ConfigDict(populate_by_name=True, extra='allow')
+        context_refs: list[str] | None = None
+        family_id: str
+        kind: Literal['choice', 'score', 'boolean']
+        metadata: dict[str, Any] | None = None
+        options: list[DecisionOption]
+        prompt: str
+        question_id: str
+        schema: Literal['helixor.decision_question.v1'] = Field(default='helixor.decision_question.v1')
+
+
+with warnings.catch_warnings():
+    # Contract field(s) intentionally shadow pydantic BaseModel attributes: schema.
+    warnings.filterwarnings('ignore', message='^Field name "schema" in "DecisionResponse" shadows an attribute in parent "_UnknownFieldWarningModel"$', category=UserWarning)
+    class DecisionResponse(_UnknownFieldWarningModel):
+        model_config = ConfigDict(populate_by_name=True, extra='allow')
+        composed: ComposedVerdict | None = None
+        cost: DecisionCost | None = None
+        helix: HelixDecisionNote | None = None
+        latency_ms: int | None = None
+        proof_id: str | None = None
+        schema: Literal['helixor.decision.v1'] = Field(default='helixor.decision.v1')
+        verdicts: dict[str, QuestionVerdict]
+
+
+class EvidenceItem(_UnknownFieldWarningModel):
+    model_config = ConfigDict(populate_by_name=True, extra='allow')
+    fields: dict[str, Any] | None = None
+    id: str
+    source: str | None = None
+    text: str | None = None
+
+
+class HTTPValidationError(_UnknownFieldWarningModel):
+    model_config = ConfigDict(populate_by_name=True, extra='allow')
+    detail: list[ValidationError] | None = None
+
+
+class HealthResponse(_UnknownFieldWarningModel):
+    model_config = ConfigDict(populate_by_name=True, extra='allow')
+    capabilities_loaded: int
+    capabilities_total: int
+    component: str
+    status: str
+    version: str
+
+
+class HelixDecisionNote(_UnknownFieldWarningModel):
+    model_config = ConfigDict(populate_by_name=True, extra='allow')
+    degraded: list[dict[str, Any]] | None = None
+    fingerprint: str | None = None
+    version: str | None = None
+
+
+class QuestionVerdict(_UnknownFieldWarningModel):
+    model_config = ConfigDict(populate_by_name=True, extra='allow')
+    masked: list[str] | None = None
+    p_correct: float | None = None
+    proof: DecisionProof | None = None
+    reason: Literal['not_certified', 'insufficient_evidence', 'over_budget'] | Literal['malformed', 'disallowed'] | None = None
+    value: Any | None = None
+    verdict: Literal['answer', 'abstain', 'refuse']
+    would_unmask: str | None = None
+
+
+class ValidationError(_UnknownFieldWarningModel):
+    model_config = ConfigDict(populate_by_name=True, extra='allow')
+    ctx: dict[str, Any] | None = None
+    input: Any | None = None
+    loc: list[str | int]
+    msg: str
+    type: str

helixor_reasoner-0.2.0/helixor_reasoner/operation_contracts.py

@@ -0,0 +1,79 @@
+from __future__ import annotations
+
+import json
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field
+
+
+class ContractRef(BaseModel):
+    content_types: list[str] = Field(default_factory=list)
+    schema_ref: str | None = None
+    schema_value: dict[str, Any] = Field(default_factory=dict, alias='schema')
+
+
+class RequestContract(ContractRef):
+    required: bool = False
+
+
+class ResponseContract(ContractRef):
+    status_code: str | None = None
+
+
+class ErrorContract(ResponseContract):
+    envelope: dict[str, Any] = Field(default_factory=dict)
+
+
+class OperationParameterContract(BaseModel):
+    name: str
+    location: str = Field(alias='in')
+    required: bool = False
+    schema_ref: str | None = None
+    schema_value: dict[str, Any] = Field(default_factory=dict, alias='schema')
+
+
+class WorkflowContract(BaseModel):
+    query_key_strategy: str
+    audit_tags: list[str] = Field(default_factory=list)
+
+
+class OperationContract(BaseModel):
+    operation_id: str = Field(alias='operationId')
+    kind: Literal['query', 'mutation']
+    method: str
+    path: str
+    sha256: str = ''
+    tags: list[str] = Field(default_factory=list)
+    summary: str = ''
+    idempotent: bool
+    retryable: bool
+    cache_key: list[str] = Field(alias='cacheKey')
+    parameters: list[OperationParameterContract] = Field(default_factory=list)
+    request_contract: RequestContract = Field(alias='requestContract')
+    response_contract: ResponseContract = Field(alias='responseContract')
+    error_contract: ErrorContract = Field(alias='errorContract')
+    auth: dict[str, Any]
+    pagination: dict[str, Any] | None = None
+    workflow: WorkflowContract
+
+
+class OperationContractsManifest(BaseModel):
+    schema_version: str
+    package_name: str
+    base_url: str | None = None
+    auth: dict[str, Any]
+    runtime: dict[str, Any]
+    resources: dict[str, Any]
+    validation: dict[str, Any]
+    error_handling: dict[str, Any]
+    operations: list[OperationContract]
+    diagnostics: list[str] = Field(default_factory=list)
+
+    def by_operation_id(self) -> dict[str, OperationContract]:
+        return {operation.operation_id: operation for operation in self.operations}
+
+
+RAW_OPERATION_CONTRACTS = json.loads("{\n  \"auth\": {\n    \"auto_detect\": true,\n    \"default_provider\": null,\n    \"enabled\": true,\n    \"fail_on_missing_required\": true,\n    \"headers\": {},\n    \"operations\": {},\n    \"providers\": {},\n    \"schemes\": {\n      \"apiKeyAuth\": {\n        \"env_var\": \"HELIXOR_API_KEY\",\n        \"location\": \"header\",\n        \"name\": \"X-API-Key\",\n        \"prefix\": \"Bearer\",\n        \"required\": false,\n        \"scopes\": [],\n        \"security_scheme\": \"apiKeyAuth\",\n        \"type\": \"api_key\"\n      }\n    }\n  },\n  \"base_url\": null,\n  \"diagnostics\": [],\n  \"error_handling\": {\n    \"envelope\": {\n      \"fields\": {\n        \"code\": \"code\",\n        \"details\": \"details\",\n        \"message\": \"message\",\n        \"request_id\": \"requestId\",\n        \"timestamp\": \"timestamp\",\n        \"trace_id\": \"traceId\"\n      },\n      \"import_from\": null,\n      \"schema_ref\": null,\n      \"source\": \"openapi\",\n      \"type_name\": \"ApiErrorBody\"\n    },\n    \"exceptions\": {\n      \"base_class\": \"ApiException\",\n      \"deserialization_exception\": \"ApiDeserializationException\",\n      \"http_exception\": \"ApiHttpException\",\n      \"import_from\": null,\n      \"network_exception\": \"ApiNetworkException\",\n      \"response_validation_exception\": \"ApiResponseValidationException\",\n      \"serialization_exception\": \"ApiSerializationException\",\n      \"source\": \"generate\",\n      \"validation_exception\": \"ApiValidationException\"\n    },\n    \"mode\": \"throw\",\n    \"raw_payload\": {\n      \"include_body\": true,\n      \"include_headers\": true,\n      \"max_body_bytes\": 65536\n    },\n    \"unknown_error_body\": \"wrap_raw\"\n  },\n  \"operations\": [\n    {\n      \"auth\": {\n        \"headers\": [],\n        \"required\": true,\n        \"schemes\": [\n          {\n            \"configured\": true,\n            \"env_var\": null,\n            \"location\": \"header\",\n            \"name\": \"ApiKeyAuth\",\n            \"prefix\": null,\n            \"required\": true,\n            \"scopes\": [],\n            \"security_scheme\": \"ApiKeyAuth\",\n            \"type\": \"api_key\"\n          }\n        ],\n        \"security\": [\n          {\n            \"ApiKeyAuth\": []\n          }\n        ]\n      },\n      \"cacheKey\": [\n        \"decide\"\n      ],\n      \"errorContract\": {\n        \"content_types\": [\n          \"application/json\"\n        ],\n        \"envelope\": {\n          \"fields\": {\n            \"code\": \"code\",\n            \"details\": \"details\",\n            \"message\": \"message\",\n            \"request_id\": \"requestId\",\n            \"timestamp\": \"timestamp\",\n            \"trace_id\": \"traceId\"\n          },\n          \"import_from\": null,\n          \"schema_ref\": null,\n          \"source\": \"openapi\",\n          \"type_name\": \"ApiErrorBody\"\n        },\n        \"schema\": {},\n        \"schema_ref\": \"#/components/schemas/DecideFailureResponse\",\n        \"status_code\": \"404\"\n      },\n      \"idempotent\": false,\n      \"kind\": \"mutation\",\n      \"method\": \"POST\",\n      \"operationId\": \"decide\",\n      \"parameters\": [],\n      \"path\": \"/v1/decide\",\n      \"requestContract\": {\n        \"content_types\": [\n          \"application/json\"\n        ],\n        \"contents\": [\n          {\n            \"content_type\": \"application/json\",\n            \"schema\": {},\n            \"schema_ref\": \"#/components/schemas/DecideRequest\"\n          }\n        ],\n        \"default_content_type\": \"application/json\",\n        \"required\": true,\n        \"schema\": {},\n        \"schema_ref\": \"#/components/schemas/DecideRequest\"\n      },\n      \"resource\": {\n        \"language_names\": {\n          \"csharp\": \"DecideAsync\",\n          \"java\": \"decide\",\n          \"python\": \"decide\",\n          \"rust\": \"decide\",\n          \"typescript\": \"decide\"\n        },\n        \"method_name\": \"decide\",\n        \"name\": \"public\"\n      },\n      \"responseContract\": {\n        \"content_types\": [\n          \"application/json\"\n        ],\n        \"schema\": {},\n        \"schema_ref\": \"#/components/schemas/DecisionResponse\",\n        \"status_code\": \"200\"\n      },\n      \"retryable\": false,\n      \"runtime\": {\n        \"idempotency\": {\n          \"applies\": false,\n          \"enabled\": false,\n          \"header_name\": \"Idempotency-Key\",\n          \"methods\": [\n            \"POST\",\n            \"PATCH\"\n          ]\n        },\n        \"retry\": {\n          \"enabled\": true,\n          \"initial_backoff_seconds\": 0.25,\n          \"max_attempts\": 3,\n          \"max_backoff_seconds\": 2.0,\n          \"retry_methods\": [\n            \"GET\",\n            \"HEAD\",\n            \"OPTIONS\",\n            \"PUT\",\n            \"DELETE\"\n          ],\n          \"retry_on_network_error\": true,\n          \"retry_statuses\": [\n            408,\n            409,\n            429,\n            500,\n            502,\n            503,\n            504\n          ],\n          \"retryable\": false\n        },\n        \"timeout\": {\n          \"total_seconds\": 60.0\n        }\n      },\n      \"sha256\": \"64422b005c949027ebc3599e842c9f9ae1b4a4f2e5dbfd727ec4a49f629d508a\",\n      \"summary\": \"Decide\",\n      \"tags\": [\n        \"public\"\n      ],\n      \"workflow\": {\n        \"audit_tags\": [\n          \"sdk\",\n          \"mutation\",\n          \"post\"\n        ],\n        \"query_key_strategy\": \"operation_and_params\"\n      }\n    },\n    {\n      \"auth\": {\n        \"headers\": [],\n        \"required\": true,\n        \"schemes\": [\n          {\n            \"configured\": true,\n            \"env_var\": null,\n            \"location\": \"header\",\n            \"name\": \"ApiKeyAuth\",\n            \"prefix\": null,\n            \"required\": true,\n            \"scopes\": [],\n            \"security_scheme\": \"ApiKeyAuth\",\n            \"type\": \"api_key\"\n          }\n        ],\n        \"security\": [\n          {\n            \"ApiKeyAuth\": []\n          }\n        ]\n      },\n      \"cacheKey\": [\n        \"getHealth\"\n      ],\n      \"errorContract\": {\n        \"content_types\": [],\n        \"envelope\": {\n          \"fields\": {\n            \"code\": \"code\",\n            \"details\": \"details\",\n            \"message\": \"message\",\n            \"request_id\": \"requestId\",\n            \"timestamp\": \"timestamp\",\n            \"trace_id\": \"traceId\"\n          },\n          \"import_from\": null,\n          \"schema_ref\": null,\n          \"source\": \"openapi\",\n          \"type_name\": \"ApiErrorBody\"\n        },\n        \"schema\": {},\n        \"schema_ref\": null,\n        \"status_code\": null\n      },\n      \"idempotent\": true,\n      \"kind\": \"query\",\n      \"method\": \"GET\",\n      \"operationId\": \"getHealth\",\n      \"parameters\": [],\n      \"path\": \"/v1/health\",\n      \"requestContract\": {\n        \"content_types\": [],\n        \"contents\": [],\n        \"default_content_type\": null,\n        \"required\": false,\n        \"schema\": {},\n        \"schema_ref\": null\n      },\n      \"resource\": {\n        \"language_names\": {\n          \"csharp\": \"GetHealthAsync\",\n          \"java\": \"getHealth\",\n          \"python\": \"get_health\",\n          \"rust\": \"get_health\",\n          \"typescript\": \"getHealth\"\n        },\n        \"method_name\": \"getHealth\",\n        \"name\": \"public\"\n      },\n      \"responseContract\": {\n        \"content_types\": [\n          \"application/json\"\n        ],\n        \"schema\": {},\n        \"schema_ref\": \"#/components/schemas/HealthResponse\",\n        \"status_code\": \"200\"\n      },\n      \"retryable\": true,\n      \"runtime\": {\n        \"idempotency\": {\n          \"applies\": false,\n          \"enabled\": false,\n          \"header_name\": \"Idempotency-Key\",\n          \"methods\": [\n            \"POST\",\n            \"PATCH\"\n          ]\n        },\n        \"retry\": {\n          \"enabled\": true,\n          \"initial_backoff_seconds\": 0.25,\n          \"max_attempts\": 3,\n          \"max_backoff_seconds\": 2.0,\n          \"retry_methods\": [\n            \"GET\",\n            \"HEAD\",\n            \"OPTIONS\",\n            \"PUT\",\n            \"DELETE\"\n          ],\n          \"retry_on_network_error\": true,\n          \"retry_statuses\": [\n            408,\n            409,\n            429,\n            500,\n            502,\n            503,\n            504\n          ],\n          \"retryable\": true\n        },\n        \"timeout\": {\n          \"total_seconds\": 60.0\n        }\n      },\n      \"sha256\": \"5ee627b0358ea87788b51bfe6e9dceca9e8c790b52d52d3e53e626d72cd80f46\",\n      \"summary\": \"Health\",\n      \"tags\": [\n        \"public\"\n      ],\n      \"workflow\": {\n        \"audit_tags\": [\n          \"sdk\",\n          \"query\",\n          \"get\"\n        ],\n        \"query_key_strategy\": \"operation_and_params\"\n      }\n    }\n  ],\n  \"package_name\": \"helixor-reasoner\",\n  \"pagination\": {\n    \"auto_detect\": false,\n    \"enabled\": true,\n    \"operations\": {},\n    \"patterns\": {}\n  },\n  \"resources\": {\n    \"enabled\": true,\n    \"infer_from_tags\": true,\n    \"max_python_methods_per_class\": 40,\n    \"oversized_python_group_severity\": \"warning\",\n    \"resources\": {}\n  },\n  \"runtime\": {\n    \"idempotency\": {\n      \"enabled\": false,\n      \"header_name\": \"Idempotency-Key\",\n      \"methods\": [\n        \"POST\",\n        \"PATCH\"\n      ]\n    },\n    \"max_response_bytes\": 10485760,\n    \"retry\": {\n      \"enabled\": true,\n      \"initial_backoff_seconds\": 0.25,\n      \"max_attempts\": 3,\n      \"max_backoff_seconds\": 2.0,\n      \"retry_methods\": [\n        \"GET\",\n        \"HEAD\",\n        \"OPTIONS\",\n        \"PUT\",\n        \"DELETE\"\n      ],\n      \"retry_on_network_error\": true,\n      \"retry_statuses\": [\n        408,\n        409,\n        429,\n        500,\n        502,\n        503,\n        504\n      ]\n    },\n    \"timeout\": {\n      \"total_seconds\": 60.0\n    }\n  },\n  \"schema_version\": \"sdk.operation-contracts.v1\",\n  \"validation\": {\n    \"error_response\": \"strict\",\n    \"raw_payload_capture\": true,\n    \"request\": \"strict\",\n    \"response\": \"strict\",\n    \"unknown_fields\": \"warn\"\n  }\n}")
+
+OPERATION_CONTRACTS = OperationContractsManifest.model_validate(RAW_OPERATION_CONTRACTS)

helixor_reasoner-0.2.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "helixor-reasoner"
+version = "0.2.0"
+description = "Typed client for the Helixor reasoning API: decide, fetch proofs, report outcomes."
+readme = "README.md"
+license = "Apache-2.0"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+authors = [{name = "Helixor", email = "engineering@helixor.ai"}]
+keywords = ["helixor", "reasoning", "decisions", "sdk"]
+classifiers = [
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+dependencies = ["httpx>=0.27", "pydantic>=2.7"]
+
+[project.urls]
+Homepage = "https://helixor.dev"
+
+[tool.hatch.build.targets.wheel]
+packages = ["helixor_reasoner"]
+core-metadata-version = "2.4"
+
+[tool.hatch.build.targets.sdist]
+include = ["/helixor_reasoner", "/README.md", "/LICENSE", "/pyproject.toml"]
+core-metadata-version = "2.4"