arche-sdk 0.1.0__py3-none-any.whl

arche_sdk/__init__.py

@@ -0,0 +1,49 @@
+# Copyright (c) 2026 Protos Systems LLC.
+# SPDX-License-Identifier: Apache-2.0
+"""Arche Python SDK public exports."""
+
+from arche_sdk._version import __version__
+from arche_sdk.client import ArcheClient
+from arche_sdk.errors import (
+    APIError,
+    ArcheSDKError,
+    AuthenticationError,
+    BulkLicenseNotAcceptedError,
+    ChecksumMismatchError,
+    ConflictError,
+    ConnectionError,
+    NotFoundError,
+    PermissionDeniedError,
+    RateLimitError,
+    ResponseDecodeError,
+    ServerError,
+    TimeoutError,
+    TransportError,
+    ValidationError,
+)
+from arche_sdk.models.bulk import SyncProgress, SyncResult
+from arche_sdk.pagination import Page
+from arche_sdk.request_options import RequestOptions
+
+__all__ = [
+    "APIError",
+    "ArcheClient",
+    "ArcheSDKError",
+    "AuthenticationError",
+    "BulkLicenseNotAcceptedError",
+    "ChecksumMismatchError",
+    "ConflictError",
+    "ConnectionError",
+    "NotFoundError",
+    "Page",
+    "PermissionDeniedError",
+    "RateLimitError",
+    "RequestOptions",
+    "ResponseDecodeError",
+    "ServerError",
+    "SyncProgress",
+    "SyncResult",
+    "TimeoutError",
+    "TransportError",
+    "ValidationError",
+]

arche_sdk/_version.py

@@ -0,0 +1,5 @@
+# Copyright (c) 2026 Protos Systems LLC.
+# SPDX-License-Identifier: Apache-2.0
+"""The SDK's release version, read by the build and the publish workflow."""
+
+__version__ = "0.1.0"

arche_sdk/auth.py

@@ -0,0 +1,26 @@
+# Copyright (c) 2026 Protos Systems LLC.
+# SPDX-License-Identifier: Apache-2.0
+"""Authentication header utilities for Arche SDK."""
+
+from __future__ import annotations
+
+from arche_sdk.config import SDKConfig
+
+
+class AuthHeaderProvider:
+    """Build auth headers for outgoing requests."""
+
+    def __init__(self, config: SDKConfig) -> None:
+        self._config = config
+
+    def headers(self) -> dict[str, str]:
+        """Return authentication headers.
+
+        Returns:
+            A dictionary containing either `X-Api-Key`, `Authorization`, or empty.
+        """
+        if self._config.api_key:
+            return {"X-Api-Key": self._config.api_key}
+        if self._config.bearer_token:
+            return {"Authorization": f"Bearer {self._config.bearer_token}"}
+        return {}

arche_sdk/client.py

@@ -0,0 +1,63 @@
+# Copyright (c) 2026 Protos Systems LLC.
+# SPDX-License-Identifier: Apache-2.0
+"""Root client for Arche Python SDK."""
+
+from __future__ import annotations
+
+import httpx
+
+from arche_sdk.config import SDKConfig
+from arche_sdk.resources.bulk import BulkClient
+from arche_sdk.resources.companies import CompaniesClient
+from arche_sdk.resources.filings import FilingsClient
+from arche_sdk.resources.narratives import NarrativesClient
+from arche_sdk.resources.statements import StatementsClient
+from arche_sdk.transport import HTTPTransport
+
+
+class ArcheClient:
+    """Synchronous Arche API client.
+
+    Args:
+        api_key: Optional API key for `X-Api-Key` authentication.
+        bearer_token: Optional bearer token for `Authorization` authentication.
+        base_url: Base API URL.
+        timeout_seconds: Default request timeout in seconds.
+        user_agent: Optional custom user-agent header.
+        http_client: Optional preconfigured `httpx.Client`.
+    """
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        bearer_token: str | None = None,
+        base_url: str = "https://api.arche.fi",
+        timeout_seconds: float = 30.0,
+        user_agent: str | None = None,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        self._config = SDKConfig(
+            api_key=api_key,
+            bearer_token=bearer_token,
+            base_url=base_url,
+            timeout_seconds=timeout_seconds,
+            user_agent=user_agent,
+        )
+        self._transport = HTTPTransport(self._config, http_client=http_client)
+
+        self.companies = CompaniesClient(self._transport)
+        self.filings = FilingsClient(self._transport)
+        self.statements = StatementsClient(self._transport)
+        self.narratives = NarrativesClient(self._transport)
+        self.bulk = BulkClient(self._transport)
+
+    def close(self) -> None:
+        """Close underlying HTTP transport resources."""
+        self._transport.close()
+
+    def __enter__(self) -> ArcheClient:
+        return self
+
+    def __exit__(self, exc_type: object, exc: object, tb: object) -> None:
+        self.close()

arche_sdk/config.py

@@ -0,0 +1,37 @@
+# Copyright (c) 2026 Protos Systems LLC.
+# SPDX-License-Identifier: Apache-2.0
+"""SDK configuration objects for Arche Python SDK."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+DEFAULT_BASE_URL = "https://api.arche.fi"
+DEFAULT_TIMEOUT_SECONDS = 30.0
+
+
+@dataclass(frozen=True)
+class SDKConfig:
+    """Immutable SDK configuration.
+
+    Args:
+        api_key: API key for `X-Api-Key` authentication.
+        bearer_token: Bearer token for `Authorization` authentication.
+        base_url: API base URL.
+        timeout_seconds: Default request timeout in seconds.
+        user_agent: Optional user-agent string override.
+    """
+
+    api_key: str | None = None
+    bearer_token: str | None = None
+    base_url: str = DEFAULT_BASE_URL
+    timeout_seconds: float = DEFAULT_TIMEOUT_SECONDS
+    user_agent: str | None = None
+
+    def __post_init__(self) -> None:
+        if self.api_key and self.bearer_token:
+            raise ValueError("Provide either api_key or bearer_token, not both.")
+        if self.timeout_seconds <= 0:
+            raise ValueError("timeout_seconds must be > 0")
+        if not self.base_url:
+            raise ValueError("base_url must be non-empty")

arche_sdk/envelopes.py

@@ -0,0 +1,50 @@
+# Copyright (c) 2026 Protos Systems LLC.
+# SPDX-License-Identifier: Apache-2.0
+"""Public envelope models used by Arche API."""
+
+from __future__ import annotations
+
+from typing import Generic, TypeVar
+
+from pydantic import BaseModel, ConfigDict
+
+T = TypeVar("T")
+
+
+class ErrorObject(BaseModel):
+    """Canonical API error object."""
+
+    model_config = ConfigDict(extra="allow")
+
+    code: str
+    http_status: int
+    message: str
+    details: dict[str, object] | None = None
+    trace_id: str | None = None
+
+
+class ErrorEnvelope(BaseModel):
+    """Canonical API error envelope."""
+
+    model_config = ConfigDict(extra="allow")
+
+    error: ErrorObject
+
+
+class SuccessEnvelope(BaseModel, Generic[T]):
+    """Canonical success envelope."""
+
+    model_config = ConfigDict(extra="allow")
+
+    data: T
+
+
+class PaginatedEnvelope(BaseModel, Generic[T]):
+    """Canonical paginated envelope."""
+
+    model_config = ConfigDict(extra="allow")
+
+    page: int
+    page_size: int
+    total: int
+    items: list[T]

arche_sdk/errors.py

@@ -0,0 +1,148 @@
+# Copyright (c) 2026 Protos Systems LLC.
+# SPDX-License-Identifier: Apache-2.0
+"""Arche SDK exception hierarchy and API error types."""
+
+from __future__ import annotations
+
+
+class ArcheSDKError(Exception):
+    """Base exception for all SDK errors."""
+
+
+class TransportError(ArcheSDKError):
+    """Transport-level error while making a request."""
+
+
+class TimeoutError(TransportError):
+    """Request timed out."""
+
+
+class ConnectionError(TransportError):
+    """Failed to connect to API."""
+
+
+class ResponseDecodeError(ArcheSDKError):
+    """Response body could not be decoded."""
+
+
+class ChecksumMismatchError(ArcheSDKError):
+    """A downloaded file's SHA-256 differs from the checksum the manifest records.
+
+    The file is removed rather than left in place: a partially written or
+    corrupted Parquet file that looks complete is worse than an absent one,
+    because the next sync would skip it.
+    """
+
+    def __init__(self, *, path: str, expected: str, actual: str) -> None:
+        self.path = path
+        self.expected = expected
+        self.actual = actual
+        super().__init__(f"{path}: expected sha256 {expected}, downloaded {actual}")
+
+
+class APIError(ArcheSDKError):
+    """Base API error returned by server."""
+
+    def __init__(
+        self,
+        *,
+        status_code: int,
+        code: str,
+        message: str,
+        details: dict[str, object] | None,
+        trace_id: str | None,
+        request_id: str | None,
+    ) -> None:
+        self.status_code = status_code
+        self.code = code
+        self.message = message
+        self.details = details or {}
+        self.trace_id = trace_id
+        self.request_id = request_id
+        super().__init__(f"{status_code} {code}: {message}")
+
+
+class ValidationError(APIError):
+    """Input validation error."""
+
+
+class AuthenticationError(APIError):
+    """Authentication failed."""
+
+
+class PermissionDeniedError(APIError):
+    """Permission denied."""
+
+
+class BulkLicenseNotAcceptedError(PermissionDeniedError):
+    """The organization has not accepted the current bulk-data license.
+
+    Download URLs are issued only once it has. Read the license with
+    ``client.bulk.license()`` and accept it with
+    ``client.bulk.accept_license(name=..., email=...)``.
+    """
+
+    def __init__(
+        self,
+        *,
+        status_code: int,
+        code: str,
+        message: str,
+        details: dict[str, object] | None,
+        trace_id: str | None,
+        request_id: str | None,
+    ) -> None:
+        super().__init__(
+            status_code=status_code,
+            code=code,
+            message=(
+                f"{message} With this SDK, read it with client.bulk.license() and "
+                "accept it with client.bulk.accept_license(name=..., email=...)."
+            ),
+            details=details,
+            trace_id=trace_id,
+            request_id=request_id,
+        )
+
+
+class NotFoundError(APIError):
+    """Resource not found."""
+
+
+class ConflictError(APIError):
+    """Conflict error."""
+
+
+class RateLimitError(APIError):
+    """Rate limit exceeded."""
+
+    def __init__(
+        self,
+        *,
+        status_code: int,
+        code: str,
+        message: str,
+        details: dict[str, object] | None,
+        trace_id: str | None,
+        request_id: str | None,
+        retry_after: str | None,
+        rate_limit_limit: str | None,
+        rate_limit_remaining: str | None,
+        rate_limit_reset: str | None,
+    ) -> None:
+        super().__init__(
+            status_code=status_code,
+            code=code,
+            message=message,
+            details=details,
+            trace_id=trace_id,
+            request_id=request_id,
+        )
+        self.retry_after = retry_after
+        self.rate_limit_limit = rate_limit_limit
+        self.rate_limit_remaining = rate_limit_remaining
+        self.rate_limit_reset = rate_limit_reset
+
+
+class ServerError(APIError):
+    """Server-side error (5xx)."""

arche_sdk/models/__init__.py

@@ -0,0 +1,109 @@
+# Copyright (c) 2026 Protos Systems LLC.
+# SPDX-License-Identifier: Apache-2.0
+"""Public model exports for Arche SDK."""
+
+from arche_sdk.models.ai import Narrative, NarrativeCitation
+from arche_sdk.models.bulk import (
+    BulkColumn,
+    BulkDataset,
+    BulkDatasetTotals,
+    BulkDownloadUrl,
+    BulkFile,
+    BulkLicense,
+    BulkLicenseAcceptance,
+    BulkLicenseAcceptanceRecord,
+    BulkSnapshot,
+    BulkSnapshotManifest,
+    SyncProgress,
+    SyncResult,
+)
+from arche_sdk.models.companies import (
+    EdgarCompanyCompleteness,
+    EdgarCompanyProfile,
+    EdgarCompanyProfileSource,
+    EdgarCompanyResolve,
+)
+from arche_sdk.models.edgar import (
+    EdgarDerivedMetricsCatalog,
+    EdgarDerivedMetricSpec,
+    EdgarDerivedMetricsPoint,
+    EdgarDerivedMetricsTimeSeries,
+    EdgarFiling,
+    EdgarStatementVersion,
+    EdgarStatementList,
+    MetricOverrideAudit,
+    NormalizedFact,
+    StatementUsd,
+    UsdValue,
+    NormalizedStatement,
+    RestatementDelta,
+    RestatementDeltaVersion,
+    RestatementLedger,
+    RestatementLedgerEntry,
+    RestatementMetricDelta,
+    RestatementMetricTimeline,
+    RestatementSummary,
+    StatementMetricAuditChain,
+    StatementQuality,
+)
+from arche_sdk.models.reconciliation import ReconciliationResult, ReconciliationSummaryBucket
+from arche_sdk.models.statements import (
+    DQAnomaly,
+    EdgarFinancialsAsOf,
+    EdgarFinancialsAsOfPage,
+    FactQuality,
+    OverrideRuleApplication,
+    StatementDQOverlay,
+    StatementOverrideTrace,
+)
+
+__all__ = [
+    "BulkColumn",
+    "BulkDataset",
+    "BulkDatasetTotals",
+    "BulkDownloadUrl",
+    "BulkFile",
+    "BulkLicense",
+    "BulkLicenseAcceptance",
+    "BulkLicenseAcceptanceRecord",
+    "BulkSnapshot",
+    "BulkSnapshotManifest",
+    "DQAnomaly",
+    "EdgarCompanyCompleteness",
+    "EdgarCompanyProfile",
+    "EdgarCompanyProfileSource",
+    "EdgarCompanyResolve",
+    "EdgarDerivedMetricSpec",
+    "EdgarDerivedMetricsCatalog",
+    "EdgarDerivedMetricsPoint",
+    "EdgarDerivedMetricsTimeSeries",
+    "EdgarFinancialsAsOf",
+    "EdgarFinancialsAsOfPage",
+    "EdgarFiling",
+    "EdgarStatementVersion",
+    "EdgarStatementList",
+    "FactQuality",
+    "MetricOverrideAudit",
+    "Narrative",
+    "NarrativeCitation",
+    "NormalizedFact",
+    "StatementUsd",
+    "UsdValue",
+    "NormalizedStatement",
+    "OverrideRuleApplication",
+    "ReconciliationResult",
+    "ReconciliationSummaryBucket",
+    "RestatementDelta",
+    "RestatementDeltaVersion",
+    "RestatementLedger",
+    "RestatementLedgerEntry",
+    "RestatementMetricDelta",
+    "RestatementMetricTimeline",
+    "RestatementSummary",
+    "StatementDQOverlay",
+    "StatementMetricAuditChain",
+    "StatementOverrideTrace",
+    "StatementQuality",
+    "SyncProgress",
+    "SyncResult",
+]

arche_sdk/models/ai.py

@@ -0,0 +1,32 @@
+# Copyright (c) 2026 Protos Systems LLC.
+# SPDX-License-Identifier: Apache-2.0
+"""Typed AI models for narratives endpoints."""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+from pydantic import BaseModel, ConfigDict
+
+
+class NarrativeCitation(BaseModel):
+    model_config = ConfigDict(extra="allow")
+
+    metric_code: str
+    period: str
+    value: str
+    comparison: str | None = None
+
+
+class Narrative(BaseModel):
+    model_config = ConfigDict(extra="allow")
+
+    company_id: str
+    cik: str
+    as_of_timestamp: datetime
+    narrative_type: str
+    window_label: str
+    input_hash: str
+    narrative_text: str
+    citations: list[NarrativeCitation]
+    created_at: datetime