priorish-sdk 0.1.0__tar.gz

priorish_sdk-0.1.0/.gitignore

@@ -0,0 +1,22 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.env
+.env.local
+.venv/
+venv/
+neo4j_data/
+neo4j_logs/
+.ruff_cache/
+.pytest_cache/
+.mypy_cache/
+*.ipynb_checkpoints/
+.gstack/
+.claude/
+_index.sqlite
+rust-preprocessor/target/

priorish_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,7 @@
+Metadata-Version: 2.4
+Name: priorish-sdk
+Version: 0.1.0
+Summary: Python SDK for the Priorish temporal search API
+Requires-Python: <4,>=3.11
+Requires-Dist: httpx>=0.28.0
+Requires-Dist: pydantic>=2.11.0

priorish_sdk-0.1.0/priorish_sdk/__init__.py

@@ -0,0 +1,67 @@
+"""Priorish Python SDK.
+
+Usage:
+    from priorish_sdk import PriorishClient
+
+    client = PriorishClient(api_key="your-key")
+    results = client.search("nonfarm payrolls", as_of="2026-03-01T00:00:00Z")
+    diff = client.diff("nonfarm payrolls", t1="2026-03-01", t2="2026-04-01")
+"""
+
+from priorish_sdk.client import PriorishClient
+from priorish_sdk.models import (
+    BaseRateResponse,
+    BatchSearchResponse,
+    BatchSearchResultSet,
+    DiffChange,
+    DiffResponse,
+    EdgeDetail,
+    EntityDiffResponse,
+    EpisodeDetail,
+    FactProvenance,
+    GraphNeighborsResponse,
+    NeighborEntity,
+    Provenance,
+    RelatedFact,
+    RevisionHistoryResponse,
+    SagaEpisode,
+    SagaGroup,
+    SagaListResponse,
+    SagaSummary,
+    SagaTimelineResponse,
+    SearchResponse,
+    SearchResult,
+    SourceStatus,
+    StatusResponse,
+    TimelineEvent,
+    TimelineResponse,
+)
+
+__all__ = [
+    "PriorishClient",
+    "BaseRateResponse",
+    "BatchSearchResponse",
+    "BatchSearchResultSet",
+    "DiffChange",
+    "DiffResponse",
+    "EdgeDetail",
+    "EntityDiffResponse",
+    "EpisodeDetail",
+    "FactProvenance",
+    "GraphNeighborsResponse",
+    "NeighborEntity",
+    "Provenance",
+    "RelatedFact",
+    "RevisionHistoryResponse",
+    "SagaEpisode",
+    "SagaGroup",
+    "SagaListResponse",
+    "SagaSummary",
+    "SagaTimelineResponse",
+    "SearchResponse",
+    "SearchResult",
+    "SourceStatus",
+    "StatusResponse",
+    "TimelineEvent",
+    "TimelineResponse",
+]

priorish_sdk-0.1.0/priorish_sdk/client.py

@@ -0,0 +1,310 @@
+"""Priorish Python SDK client."""
+
+from datetime import datetime
+
+import httpx
+
+from priorish_sdk.models import (
+    BaseRateResponse,
+    BatchSearchResponse,
+    CoverageResponse,
+    DiffResponse,
+    EntityDiffResponse,
+    FactProvenance,
+    GraphNeighborsResponse,
+    RevisionHistoryResponse,
+    SagaListResponse,
+    SagaTimelineResponse,
+    SearchResponse,
+    SeriesResponse,
+    StatusResponse,
+    TimelineResponse,
+)
+
+
+class PriorishClient:
+    """Client for the Priorish API.
+
+    Usage:
+        client = PriorishClient(api_key="your-key")
+        results = client.search("nonfarm payrolls")
+        diff = client.diff("nonfarm payrolls", t1="2026-03-01", t2="2026-04-01")
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = "https://api.priori.sh",
+        timeout: float = 30.0,
+    ):
+        self._client = httpx.Client(
+            base_url=base_url,
+            headers={"X-API-Key": api_key},
+            timeout=timeout,
+        )
+
+    def search(
+        self,
+        query: str,
+        as_of: str | datetime | None = None,
+        start_date: str | datetime | None = None,
+        end_date: str | datetime | None = None,
+        sources: list[str] | None = None,
+        limit: int = 10,
+        temperature: float = 0.0,
+        natural_language: bool = False,
+    ) -> SearchResponse:
+        """Temporal search: what was knowable at a specific point in time."""
+        params: dict = {
+            "query": query,
+            "limit": limit,
+        }
+        if natural_language:
+            params["natural_language"] = "true"
+        if temperature > 0.0:
+            params["temperature"] = temperature
+        if as_of:
+            params["as_of"] = str(as_of) if isinstance(as_of, datetime) else as_of
+        if start_date:
+            params["start_date"] = (
+                str(start_date) if isinstance(start_date, datetime) else start_date
+            )
+        if end_date:
+            params["end_date"] = str(end_date) if isinstance(end_date, datetime) else end_date
+        if sources:
+            params["sources"] = ",".join(sources)
+
+        resp = self._client.get("/search", params=params)
+        resp.raise_for_status()
+        return SearchResponse(**resp.json())
+
+    def diff(
+        self,
+        query: str,
+        t1: str | datetime,
+        t2: str | datetime,
+        sources: list[str] | None = None,
+    ) -> DiffResponse:
+        """Knowledge diff: what changed between two timestamps."""
+        params = {
+            "query": query,
+            "t1": str(t1) if isinstance(t1, datetime) else t1,
+            "t2": str(t2) if isinstance(t2, datetime) else t2,
+        }
+        if sources:
+            params["sources"] = ",".join(sources)
+
+        resp = self._client.get("/diff", params=params)
+        resp.raise_for_status()
+        return DiffResponse(**resp.json())
+
+    def status(self) -> StatusResponse:
+        """Get source freshness and system status."""
+        resp = self._client.get("/status")
+        resp.raise_for_status()
+        return StatusResponse(**resp.json())
+
+    def sagas(self, source: str | None = None) -> SagaListResponse:
+        """List all sagas with metadata."""
+        params = {}
+        if source:
+            params["source"] = source
+        resp = self._client.get("/sagas", params=params)
+        resp.raise_for_status()
+        return SagaListResponse(**resp.json())
+
+    def saga_timeline(
+        self,
+        name: str,
+        limit: int = 50,
+        offset: int = 0,
+    ) -> SagaTimelineResponse:
+        """Get a saga's timeline: episodes in chronological order."""
+        resp = self._client.get(
+            f"/sagas/{name}",
+            params={"limit": limit, "offset": offset},
+        )
+        resp.raise_for_status()
+        return SagaTimelineResponse(**resp.json())
+
+    def saga_diff(
+        self,
+        name: str,
+        episode_1: str | None = None,
+        episode_2: str | None = None,
+    ) -> DiffResponse:
+        """Diff two episodes within a saga. Defaults to two most recent."""
+        params = {}
+        if episode_1:
+            params["episode_1"] = episode_1
+        if episode_2:
+            params["episode_2"] = episode_2
+        resp = self._client.get(f"/sagas/{name}/diff", params=params)
+        resp.raise_for_status()
+        return DiffResponse(**resp.json())
+
+    def search_batch(
+        self,
+        query: str,
+        timestamps: list[str | datetime],
+        sources: list[str] | None = None,
+        limit: int = 10,
+    ) -> BatchSearchResponse:
+        """Run the same query at multiple timestamps for backtesting."""
+        ts_strs = [str(t) if isinstance(t, datetime) else t for t in timestamps]
+        params: dict = {
+            "query": query,
+            "timestamps": ",".join(ts_strs),
+            "limit": limit,
+        }
+        if sources:
+            params["sources"] = ",".join(sources)
+        resp = self._client.get("/search/batch", params=params)
+        resp.raise_for_status()
+        return BatchSearchResponse(**resp.json())
+
+    def timeline(
+        self,
+        entity: str | None = None,
+        saga: str | None = None,
+        as_of: str | datetime | None = None,
+        sources: list[str] | None = None,
+        limit: int = 50,
+        offset: int = 0,
+    ) -> TimelineResponse:
+        """Temporal evolution: how an entity's facts changed over time."""
+        params: dict = {"limit": limit, "offset": offset}
+        if entity:
+            params["entity"] = entity
+        if saga:
+            params["saga"] = saga
+        if as_of:
+            params["as_of"] = str(as_of) if isinstance(as_of, datetime) else as_of
+        if sources:
+            params["sources"] = ",".join(sources)
+        resp = self._client.get("/timeline", params=params)
+        resp.raise_for_status()
+        return TimelineResponse(**resp.json())
+
+    def provenance(self, fact_uuid: str) -> FactProvenance:
+        """Full provenance for a fact: source episodes, raw content, related facts."""
+        resp = self._client.get(f"/provenance/{fact_uuid}")
+        resp.raise_for_status()
+        return FactProvenance(**resp.json())
+
+    def entity_diff(
+        self,
+        entity_name: str,
+        t1: str | datetime,
+        t2: str | datetime,
+    ) -> EntityDiffResponse:
+        """Entity-centric diff: what changed for an entity between t1 and t2."""
+        params = {
+            "t1": str(t1) if isinstance(t1, datetime) else t1,
+            "t2": str(t2) if isinstance(t2, datetime) else t2,
+        }
+        resp = self._client.get(f"/entities/{entity_name}/diff", params=params)
+        resp.raise_for_status()
+        return EntityDiffResponse(**resp.json())
+
+    def entity_revisions(
+        self,
+        entity_name: str,
+        as_of: str | datetime | None = None,
+    ) -> RevisionHistoryResponse:
+        """Revision/contradiction history for an entity."""
+        params: dict = {}
+        if as_of:
+            params["as_of"] = str(as_of) if isinstance(as_of, datetime) else as_of
+        resp = self._client.get(f"/entities/{entity_name}/revisions", params=params)
+        resp.raise_for_status()
+        return RevisionHistoryResponse(**resp.json())
+
+    def entity_neighbors(
+        self,
+        entity_name: str,
+        relation_types: list[str] | None = None,
+        as_of: str | datetime | None = None,
+        limit: int = 100,
+    ) -> GraphNeighborsResponse:
+        """Graph neighbors: entities connected via edges."""
+        params: dict = {"limit": limit}
+        if relation_types:
+            params["relation_types"] = ",".join(relation_types)
+        if as_of:
+            params["as_of"] = str(as_of) if isinstance(as_of, datetime) else as_of
+        resp = self._client.get(f"/entities/{entity_name}/neighbors", params=params)
+        resp.raise_for_status()
+        return GraphNeighborsResponse(**resp.json())
+
+    def base_rates(
+        self,
+        relation_type: str,
+        entity_type: str | None = None,
+    ) -> BaseRateResponse:
+        """Base rate query: all edges of a given type for quantitative analysis."""
+        params: dict = {}
+        if entity_type:
+            params["entity_type"] = entity_type
+        resp = self._client.get(f"/base-rates/{relation_type}", params=params)
+        resp.raise_for_status()
+        return BaseRateResponse(**resp.json())
+
+    def relation_types(
+        self,
+        entity_type: str | None = None,
+    ) -> list[dict]:
+        """Discover available relation types and their counts."""
+        params: dict = {}
+        if entity_type:
+            params["entity_type"] = entity_type
+        resp = self._client.get("/relation-types", params=params)
+        resp.raise_for_status()
+        return resp.json()
+
+    def series(
+        self,
+        entity: str,
+        relation_type: str,
+        format: str = "json",
+        start_date: str | datetime | None = None,
+        end_date: str | datetime | None = None,
+    ) -> SeriesResponse:
+        """Time series data for an entity + relation type."""
+        params: dict = {"format": format}
+        if start_date:
+            params["start_date"] = (
+                str(start_date) if isinstance(start_date, datetime) else start_date
+            )
+        if end_date:
+            params["end_date"] = str(end_date) if isinstance(end_date, datetime) else end_date
+        resp = self._client.get(f"/series/{entity}/{relation_type}", params=params)
+        resp.raise_for_status()
+        return SeriesResponse(**resp.json())
+
+    def coverage(self) -> CoverageResponse:
+        """Coverage per source, entity type, and relation type."""
+        resp = self._client.get("/coverage")
+        resp.raise_for_status()
+        return CoverageResponse(**resp.json())
+
+    def provenance_chain(self, fact_uuid: str) -> dict:
+        """Extended provenance with content hashes."""
+        resp = self._client.get(f"/provenance/{fact_uuid}/chain")
+        resp.raise_for_status()
+        return resp.json()
+
+    def provenance_pack(self, fact_uuid: str) -> dict:
+        """Evidence bundle from R2 artifacts."""
+        resp = self._client.get(f"/provenance/{fact_uuid}/pack")
+        resp.raise_for_status()
+        return resp.json()
+
+    def close(self):
+        self._client.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        self.close()

priorish_sdk-0.1.0/priorish_sdk/models.py

@@ -0,0 +1,287 @@
+"""Priorish SDK response models."""
+
+from datetime import datetime
+
+from pydantic import BaseModel, Field
+
+
+class Provenance(BaseModel):
+    origin_url: str
+    source_type: str
+    indexed_at: datetime
+    content_hash: str
+    valid_from: datetime
+    valid_to: datetime | None = None
+    superseded_by: str | None = None
+
+
+class Evidence(BaseModel):
+    """Structured evidentiary weight for LLM consumption."""
+
+    basis: str = Field(
+        description="'primary' (from source doc) or 'derived' (computed from other facts)"
+    )
+    status: str = Field(description="'current' or 'superseded'")
+    corroboration: int = Field(description="Number of independent source episodes")
+    quantitative: bool = Field(description="Contains numeric/dollar/percent values")
+
+
+class SearchResult(BaseModel):
+    id: str
+    content: str
+    score: float
+    confidence_score: float = Field(
+        default=0.0,
+        description="Deprecated. Use evidence object instead.",
+    )
+    evidence: Evidence | None = None
+    provenance: Provenance
+    fact_type: str = Field(default="extracted", description="'extracted' or 'derived'")
+    saga_name: str | None = None
+    saga_label: str | None = None
+    cluster_size: int = Field(
+        default=1, description="Number of results folded into this one by temperature."
+    )
+
+
+class SagaGroup(BaseModel):
+    saga_name: str
+    saga_label: str
+    source_type: str
+    results: list[SearchResult]
+
+
+class SearchResponse(BaseModel):
+    query: str
+    as_of: datetime
+    results: list[SearchResult]
+    total_count: int = Field(description="Total results available before pagination.")
+    offset: int = 0
+    temperature: float = 0.0
+    source_freshness: dict[str, datetime | None] = Field(default_factory=dict)
+    saga_groups: list[SagaGroup] = []
+    ungrouped: list[SearchResult] = []
+
+
+class DiffChange(BaseModel):
+    type: str  # "revised", "added", "retracted"
+    fact_id: str | None = None
+    source_type: str | None = None
+    document_at_t1: str | None = None
+    document_at_t2: str | None = None
+    summary: str
+
+
+class DiffResponse(BaseModel):
+    query: str
+    t1: datetime
+    t2: datetime
+    results_at_t1: list[SearchResult]
+    results_at_t2: list[SearchResult]
+    changes: list[DiffChange]
+
+
+class EpisodeDetail(BaseModel):
+    """An ingested source document."""
+
+    uuid: str
+    name: str
+    content: str
+    source_type: str
+    origin_url: str
+    content_hash: str
+    ingested_at: datetime
+    valid_at: datetime
+    chunks: list[dict] | None = None
+
+
+class SagaSummary(BaseModel):
+    name: str
+    source_type: str
+    label: str
+    episode_count: int
+    earliest: datetime | None = None
+    latest: datetime | None = None
+
+
+class SagaListResponse(BaseModel):
+    sagas: list[SagaSummary]
+
+
+class SagaEpisode(BaseModel):
+    uuid: str
+    name: str
+    valid_at: datetime
+    created_at: datetime
+    source_type: str
+    origin_url: str
+    content_preview: str
+    fact_count: int
+
+
+class SagaTimelineResponse(BaseModel):
+    saga_name: str
+    as_of: datetime
+    source_type: str
+    label: str
+    episodes: list[SagaEpisode]
+    total_count: int
+    offset: int = 0
+
+
+class RelatedFact(BaseModel):
+    """A related fact with the same structure as the main fact."""
+
+    fact_uuid: str
+    fact: str
+    source_node: str
+    target_node: str
+    valid_at: datetime | None
+    invalid_at: datetime | None
+
+
+class FactProvenance(BaseModel):
+    """Full provenance for a single fact (edge)."""
+
+    fact_uuid: str
+    fact: str
+    source_node: str
+    target_node: str
+    valid_at: datetime | None
+    invalid_at: datetime | None
+    created_at: datetime
+    fact_type: str = "extracted"
+    source_chunk_index: int | None = None
+    episodes: list[EpisodeDetail]
+    related_facts: list[RelatedFact]
+    saga_name: str | None = None
+    saga_label: str | None = None
+
+
+class BatchSearchResultSet(BaseModel):
+    as_of: datetime
+    results: list[SearchResult]
+
+
+class BatchSearchResponse(BaseModel):
+    query: str
+    result_sets: list[BatchSearchResultSet]
+
+
+class TimelineEvent(BaseModel):
+    """A single temporal event in an entity's history."""
+
+    fact_uuid: str
+    fact: str
+    source_node: str
+    target_node: str
+    valid_at: datetime | None
+    invalid_at: datetime | None
+    created_at: datetime
+    source_type: str
+    origin_url: str
+
+
+class TimelineResponse(BaseModel):
+    entity: str
+    as_of: datetime
+    events: list[TimelineEvent]
+    total_count: int = Field(description="Total events available before pagination.")
+    offset: int = 0
+
+
+class SourceStatus(BaseModel):
+    source: str
+    last_successful_ingest: datetime | None = None
+    status: str  # "green", "yellow", "red"
+    document_count: int = 0
+
+
+class StatusResponse(BaseModel):
+    sources: list[SourceStatus]
+    total_documents: int = 0
+    total_entities: int = 0
+
+
+class EdgeDetail(BaseModel):
+    """An extracted fact/edge with full metadata."""
+
+    id: str
+    fact: str
+    relation_type: str
+    source_entity: str
+    target_entity: str
+    valid_at: datetime | None
+    invalid_at: datetime | None
+    created_at: datetime
+    expired_at: datetime | None = None
+    superseded_by: str | None = None
+    structured_data: dict | None = None
+    origin_url: str = ""
+    source_type: str = ""
+
+
+class EntityDiffResponse(BaseModel):
+    entity: str
+    t1: datetime
+    t2: datetime
+    appeared: list[EdgeDetail]
+    invalidated: list[EdgeDetail]
+
+
+class RevisionHistoryResponse(BaseModel):
+    entity: str
+    revisions: list[EdgeDetail]
+    total_count: int
+
+
+class NeighborEntity(BaseModel):
+    entity_id: str
+    name: str
+    entity_type: str
+    relation_type: str
+    fact: str
+    valid_at: datetime | None
+
+
+class GraphNeighborsResponse(BaseModel):
+    entity: str
+    neighbors: list[NeighborEntity]
+    total_count: int
+
+
+class BaseRateResponse(BaseModel):
+    relation_type: str
+    entity_type: str | None
+    total_count: int
+    edges: list[EdgeDetail]
+
+
+class SeriesPoint(BaseModel):
+    valid_at: str | None = None
+    fact: str = ""
+    value: float | str | None = None
+    unit: str | None = None
+    period: str | None = None
+
+
+class SeriesResponse(BaseModel):
+    entity: str
+    relation_type: str
+    count: int
+    data: list[dict]
+
+
+class CoverageSource(BaseModel):
+    name: str
+    doc_count: int = 0
+    entity_count: int = 0
+    edge_count: int = 0
+    earliest: str | None = None
+    latest: str | None = None
+
+
+class CoverageResponse(BaseModel):
+    sources: list[CoverageSource] = []
+    entity_types: list[dict] = []
+    relation_types: list[dict] = []

priorish_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,27 @@
+[project]
+name = "priorish-sdk"
+description = "Python SDK for the Priorish temporal search API"
+version = "0.1.0"
+requires-python = ">=3.11,<4"
+dependencies = [
+    "httpx>=0.28.0",
+    "pydantic>=2.11.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["priorish_sdk"]
+
+[tool.ruff]
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "UP", "B", "SIM", "I"]
+ignore = ["E501", "B008"]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"