viewise 0.1.2__tar.gz

viewise-0.1.2/PKG-INFO

@@ -0,0 +1,92 @@
+Metadata-Version: 2.4
+Name: viewise
+Version: 0.1.2
+Summary: Python SDK for Viewise semantic telemetry ingestion.
+Author: Viewise
+Project-URL: Homepage, https://github.com/Tanishv/xalpha
+Project-URL: Repository, https://github.com/Tanishv/xalpha
+Project-URL: Issues, https://github.com/Tanishv/xalpha/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.27
+
+# Viewise Python SDK
+
+Viewise observes agent runs through a small semantic telemetry contract. The SDK
+sends events to a Viewise backend and keeps agent code resilient when telemetry
+is unavailable.
+
+## Install
+
+```bash
+python -m pip install viewise
+```
+
+## Configure
+
+Set the runtime environment values copied from the Viewise Setup page:
+
+```bash
+export VIEWISE_BASE_URL="https://viewise-backend.fly.dev"
+export VIEWISE_INGEST_KEY="<workspace-api-key-from-viewise-setup>"
+export VIEWISE_AGENT_REF="workspace.agentx"
+export VIEWISE_AGENT_NAME="agentx"
+```
+
+You can also configure the SDK in code:
+
+```python
+import viewise
+
+viewise.configure(
+    base_url="https://viewise-backend.fly.dev",
+    ingest_key="<workspace-api-key-from-viewise-setup>",
+    agent_ref="workspace.agentx",
+    agent_name="agentx",
+)
+```
+
+Never commit API keys or place them in prompts, logs, or source code.
+
+## API
+
+```python
+viewise.start_run(run_ref, task, occurred_at=None)
+viewise.observe_evidence(run_ref, source, retrieved_at=None, evidence_ref=None)
+viewise.complete_run(run_ref, result, occurred_at=None)
+viewise.fail_run(run_ref, exc_or_error, occurred_at=None)
+viewise.sanitize_error(exc_or_error)
+```
+
+Supported event types are:
+
+- `run.started`
+- `evidence.observed`
+- `run.completed`
+- `run.failed`
+
+Top-level telemetry calls return a delivery result. They do not raise when
+Viewise or the network is unavailable, so agent work can continue.
+
+## Smoke Test
+
+```python
+import viewise
+
+run_ref = "local-run-001"
+
+viewise.start_run(run_ref, "SDK install smoke test")
+viewise.observe_evidence(
+    run_ref,
+    {"provider": "local", "kind": "smoke"},
+    evidence_ref="smoke-001",
+)
+viewise.complete_run(run_ref, {"status": "ok"})
+```

viewise-0.1.2/README.md

@@ -0,0 +1,36 @@
+# Financial Agent Lab
+
+This repository contains the xalpha observability product and its maintained
+evidence/wiki layer.
+
+- [xalpha](xalpha/README.md) is the planned SaaS for observing, explaining, and
+  evaluating financial agents. Its current phase and gate status are maintained
+  in [xalpha/PHASES.md](xalpha/PHASES.md).
+- [Professor](https://github.com/Tanishv/professor) is the separate dogfood
+  financial research agent. It owns research runtime code and local trace
+  generation.
+
+The [mission wiki](wiki/index.md) keeps historical experiment evidence and
+learnings from Professor that inform xalpha's design. The broader charter remains
+[`vision.md`](vision.md), and durable working rules live in
+[`AGENTS.md`](AGENTS.md).
+
+## Repository map
+
+```text
+xalpha/     SaaS source, local stack, source-of-truth docs, and build guidance
+wiki/       Shared experiments, learnings, roadmap, and distribution notes
+sources/    Shared raw source material and intake rules
+scripts/    Repository-level maintenance checks
+```
+
+## Offline validation
+
+```bash
+source .venv/bin/activate
+docker compose -f xalpha/docker-compose.yml up -d postgres
+python -m scripts.repository_checks
+```
+
+These commands do not call the OpenAI API. Stop the local PostgreSQL service
+afterward with `docker compose -f xalpha/docker-compose.yml down`.

viewise-0.1.2/README.pypi.md

@@ -0,0 +1,73 @@
+# Viewise Python SDK
+
+Viewise observes agent runs through a small semantic telemetry contract. The SDK
+sends events to a Viewise backend and keeps agent code resilient when telemetry
+is unavailable.
+
+## Install
+
+```bash
+python -m pip install viewise
+```
+
+## Configure
+
+Set the runtime environment values copied from the Viewise Setup page:
+
+```bash
+export VIEWISE_BASE_URL="https://viewise-backend.fly.dev"
+export VIEWISE_INGEST_KEY="<workspace-api-key-from-viewise-setup>"
+export VIEWISE_AGENT_REF="workspace.agentx"
+export VIEWISE_AGENT_NAME="agentx"
+```
+
+You can also configure the SDK in code:
+
+```python
+import viewise
+
+viewise.configure(
+    base_url="https://viewise-backend.fly.dev",
+    ingest_key="<workspace-api-key-from-viewise-setup>",
+    agent_ref="workspace.agentx",
+    agent_name="agentx",
+)
+```
+
+Never commit API keys or place them in prompts, logs, or source code.
+
+## API
+
+```python
+viewise.start_run(run_ref, task, occurred_at=None)
+viewise.observe_evidence(run_ref, source, retrieved_at=None, evidence_ref=None)
+viewise.complete_run(run_ref, result, occurred_at=None)
+viewise.fail_run(run_ref, exc_or_error, occurred_at=None)
+viewise.sanitize_error(exc_or_error)
+```
+
+Supported event types are:
+
+- `run.started`
+- `evidence.observed`
+- `run.completed`
+- `run.failed`
+
+Top-level telemetry calls return a delivery result. They do not raise when
+Viewise or the network is unavailable, so agent work can continue.
+
+## Smoke Test
+
+```python
+import viewise
+
+run_ref = "local-run-001"
+
+viewise.start_run(run_ref, "SDK install smoke test")
+viewise.observe_evidence(
+    run_ref,
+    {"provider": "local", "kind": "smoke"},
+    evidence_ref="smoke-001",
+)
+viewise.complete_run(run_ref, {"status": "ok"})
+```

viewise-0.1.2/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "viewise"
+version = "0.1.2"
+description = "Python SDK for Viewise semantic telemetry ingestion."
+readme = "README.pypi.md"
+requires-python = ">=3.11"
+dependencies = ["httpx>=0.27"]
+authors = [{ name = "Viewise" }]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+[project.urls]
+Homepage = "https://github.com/Tanishv/xalpha"
+Repository = "https://github.com/Tanishv/xalpha"
+Issues = "https://github.com/Tanishv/xalpha/issues"
+
+[tool.setuptools.packages.find]
+include = ["viewise*"]
+
+[tool.ruff]
+line-length = 88
+target-version = "py313"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+
+[tool.mypy]
+python_version = "3.13"
+strict = true
+
+[[tool.mypy.overrides]]
+module = "fastapi.*"
+ignore_missing_imports = false

viewise-0.1.2/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

viewise-0.1.2/viewise/__init__.py

@@ -0,0 +1,876 @@
+from __future__ import annotations
+
+import json
+import os
+import re
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from time import sleep
+from typing import Any, Protocol, cast
+from uuid import UUID, uuid4
+
+import httpx
+
+__version__ = "0.1.2"
+SCHEMA_VERSION = "1.0"
+EVENTS_ENDPOINT = "/v1/semantic/events"
+SUPPORTED_EVENT_TYPES = frozenset(
+    {"run.started", "evidence.observed", "run.completed", "run.failed"}
+)
+CONTEXT_SNAPSHOT_KEYS = frozenset(
+    {
+        "raw_trace_sha256",
+        "artifact_ref",
+        "response_id",
+        "usage",
+        "web_actions_count",
+        "cited_sources_count",
+    }
+)
+_CREDENTIAL_PATTERNS = (
+    re.compile(r"Bearer\s+[A-Za-z0-9._~+/=-]+", re.IGNORECASE),
+    re.compile(r"xak_[A-Za-z0-9._~+/=-]+"),
+    re.compile(r"sk-[A-Za-z0-9._~+/=-]+"),
+    re.compile(
+        r"(?i)(api[_ -]?key|token|secret|authorization)(['\":=\s]+)"
+        r"([A-Za-z0-9._~+/=-]+)"
+    ),
+)
+_REQUEST_DETAIL_PATTERNS = (
+    re.compile(
+        r"(?i)(request[_ -]?id)(['\":=\s]+)([A-Za-z0-9._~+/=-]+)"
+    ),
+)
+_SAFE_ERROR_MESSAGE_LIMIT = 500
+_runtime_config: RuntimeConfig | None = None
+
+
+class ViewiseError(RuntimeError):
+    """Base error raised by the Viewise SDK."""
+
+
+class ViewiseConfigError(ViewiseError):
+    """Raised when SDK configuration or call input is invalid."""
+
+
+class ViewiseAuthError(ViewiseError):
+    """Raised when Viewise rejects the configured ingest key."""
+
+
+class ViewiseRequestError(ViewiseError):
+    """Raised when Viewise rejects a semantic event."""
+
+
+class ViewiseServiceError(ViewiseError):
+    """Raised when Viewise or the network cannot accept an event after retries."""
+
+
+class Response(Protocol):
+    status_code: int
+
+    @property
+    def text(self) -> str: ...
+
+    def json(self) -> object: ...
+
+
+class HttpSender(Protocol):
+    def post(
+        self,
+        url: str,
+        *,
+        headers: dict[str, str],
+        json: dict[str, Any],
+    ) -> Response: ...
+
+
+@dataclass(frozen=True)
+class EventReceipt:
+    event_id: str
+    run_id: str
+    event_type: str
+    status: str
+    run_status: str
+    raw: Mapping[str, object]
+    agent_ref: str | None = None
+    run_ref: str | None = None
+
+
+@dataclass(frozen=True)
+class DeliveryResult:
+    delivered: bool
+    event_type: str
+    run_ref: str
+    event_id: str = ""
+    run_id: str = ""
+    status: str = ""
+    run_status: str = ""
+    raw: Mapping[str, object] | None = None
+    agent_ref: str | None = None
+    error: str | None = None
+    skipped_metadata_keys: tuple[str, ...] = ()
+
+    @classmethod
+    def from_receipt(
+        cls,
+        receipt: EventReceipt,
+        *,
+        run_ref: str,
+        skipped_metadata_keys: tuple[str, ...] = (),
+    ) -> DeliveryResult:
+        return cls(
+            delivered=True,
+            event_type=receipt.event_type,
+            run_ref=receipt.run_ref or run_ref,
+            event_id=receipt.event_id,
+            run_id=receipt.run_id,
+            status=receipt.status,
+            run_status=receipt.run_status,
+            raw=receipt.raw,
+            agent_ref=receipt.agent_ref,
+            skipped_metadata_keys=skipped_metadata_keys,
+        )
+
+
+@dataclass(frozen=True)
+class RuntimeConfig:
+    base_url: str
+    ingest_key: str
+    agent_ref: str
+    agent_name: str
+
+
+class HttpxSender:
+    def __init__(self, *, timeout: float = 10.0) -> None:
+        self._timeout = timeout
+
+    def post(
+        self,
+        url: str,
+        *,
+        headers: dict[str, str],
+        json: dict[str, Any],
+    ) -> Response:
+        return httpx.post(url, headers=headers, json=json, timeout=self._timeout)
+
+
+class Client:
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        ingest_key: str | None = None,
+        api_key: str | None = None,
+        agent_ref: str | None = None,
+        agent_id: str | None = None,
+        sender: HttpSender | None = None,
+        max_attempts: int = 3,
+        retry_backoff_seconds: float = 0.0,
+        idempotency_prefix: str = "viewise",
+        credential_label: str = "ingest key",
+        agent_name: str | None = None,
+    ) -> None:
+        self._base_url = require_non_blank(base_url, "base url").rstrip("/")
+        self._credential_label = require_non_blank(credential_label, "credential label")
+        self._ingest_key = require_one_key(
+            ingest_key=ingest_key,
+            api_key=api_key,
+            label=self._credential_label,
+        )
+        self._agent_ref = normalize_ref(agent_ref, "agent ref") if agent_ref else None
+        self._agent_id = require_uuid_text(agent_id, "agent id") if agent_id else None
+        if (self._agent_ref is None) == (self._agent_id is None):
+            raise ViewiseConfigError("exactly one agent_ref or agent_id is required")
+        if max_attempts < 1:
+            raise ViewiseConfigError("max_attempts must be at least 1")
+        if retry_backoff_seconds < 0:
+            raise ViewiseConfigError("retry_backoff_seconds cannot be negative")
+        self._sender = sender or HttpxSender()
+        self._max_attempts = max_attempts
+        self._retry_backoff_seconds = retry_backoff_seconds
+        self._idempotency_prefix = require_non_blank(
+            idempotency_prefix,
+            "idempotency prefix",
+        )
+        self._agent_name = agent_name.strip() if agent_name else None
+
+    @classmethod
+    def from_env(
+        cls,
+        *,
+        sender: HttpSender | None = None,
+        max_attempts: int = 3,
+        retry_backoff_seconds: float = 0.0,
+    ) -> Client:
+        base_url = require_env("VIEWISE_BASE_URL")
+        ingest_key = os.environ.get("VIEWISE_INGEST_KEY") or os.environ.get(
+            "VIEWISE_API_KEY"
+        )
+        if ingest_key is None or not ingest_key.strip():
+            raise ViewiseConfigError(
+                "VIEWISE_INGEST_KEY or VIEWISE_API_KEY is required"
+            )
+        agent_ref = require_env("VIEWISE_AGENT_REF")
+        agent_name = require_env("VIEWISE_AGENT_NAME")
+        return cls(
+            base_url=base_url,
+            ingest_key=ingest_key,
+            agent_ref=agent_ref,
+            agent_name=agent_name,
+            sender=sender,
+            max_attempts=max_attempts,
+            retry_backoff_seconds=retry_backoff_seconds,
+        )
+
+    def start_run(
+        self,
+        *,
+        run_ref: str | None = None,
+        run_id: str | None = None,
+        task: str,
+        occurred_at: datetime | None = None,
+        effective_config: Mapping[str, object] | None = None,
+        run_context_snapshot: Mapping[str, object] | None = None,
+        experiment_id: str | None = None,
+        entity_ref: str | None = None,
+    ) -> EventReceipt:
+        payload: dict[str, object] = {"task": require_non_blank(task, "task")}
+        if effective_config is not None:
+            payload["effective_config"] = dict(effective_config)
+        if run_context_snapshot is not None:
+            payload["run_context_snapshot"] = compact_context_snapshot(
+                run_context_snapshot
+            )
+        if experiment_id is not None:
+            payload["experiment_id"] = require_non_blank(experiment_id, "experiment id")
+        if entity_ref is not None:
+            payload["entity_ref"] = require_non_blank(entity_ref, "entity ref")
+        return self._post_event(
+            run_ref=run_ref,
+            run_id=run_id,
+            event_type="run.started",
+            occurred_at=occurred_at,
+            payload=payload,
+        )
+
+    def observe_evidence(
+        self,
+        *,
+        run_ref: str | None = None,
+        run_id: str | None = None,
+        source: object,
+        retrieved_at: datetime,
+        evidence_ref: str | None = None,
+        occurred_at: datetime | None = None,
+        published_at: datetime | None = None,
+        effective_at: datetime | None = None,
+        effective_period_start_at: datetime | None = None,
+        effective_period_end_at: datetime | None = None,
+        available_at: datetime | None = None,
+        available_at_status: str | None = None,
+    ) -> EventReceipt:
+        source_text = normalize_source(source)
+        payload: dict[str, object] = {
+            "source": source_text,
+            "retrieved_at": format_timestamp(retrieved_at),
+        }
+        add_optional_timestamp(payload, "published_at", published_at)
+        add_optional_timestamp(payload, "effective_at", effective_at)
+        add_optional_timestamp(
+            payload,
+            "effective_period_start_at",
+            effective_period_start_at,
+        )
+        add_optional_timestamp(
+            payload,
+            "effective_period_end_at",
+            effective_period_end_at,
+        )
+        if available_at is None and available_at_status == "unknown":
+            payload["available_at"] = None
+        else:
+            add_optional_timestamp(payload, "available_at", available_at)
+        if available_at_status is not None:
+            payload["available_at_status"] = require_non_blank(
+                available_at_status,
+                "available_at_status",
+            )
+        return self._post_event(
+            run_ref=run_ref,
+            run_id=run_id,
+            event_type="evidence.observed",
+            occurred_at=occurred_at or retrieved_at,
+            payload=payload,
+            idempotency_suffix=evidence_ref or source_text,
+        )
+
+    def complete_run(
+        self,
+        *,
+        run_ref: str | None = None,
+        run_id: str | None = None,
+        output: object,
+        occurred_at: datetime | None = None,
+    ) -> EventReceipt:
+        return self._post_event(
+            run_ref=run_ref,
+            run_id=run_id,
+            event_type="run.completed",
+            occurred_at=occurred_at,
+            payload={"output": output},
+        )
+
+    def fail_run(
+        self,
+        *,
+        run_ref: str | None = None,
+        run_id: str | None = None,
+        error: object,
+        occurred_at: datetime | None = None,
+    ) -> EventReceipt:
+        return self._post_event(
+            run_ref=run_ref,
+            run_id=run_id,
+            event_type="run.failed",
+            occurred_at=occurred_at,
+            payload={"error": error},
+        )
+
+    def _post_event(
+        self,
+        *,
+        run_ref: str | None,
+        run_id: str | None,
+        event_type: str,
+        occurred_at: datetime | None,
+        payload: dict[str, object],
+        idempotency_suffix: str | None = None,
+    ) -> EventReceipt:
+        identity = self._identity(run_ref=run_ref, run_id=run_id)
+        idempotency_key = self._idempotency_key(
+            event_type=event_type,
+            identity=identity,
+            suffix=idempotency_suffix,
+        )
+        last_error: Exception | None = None
+        for attempt in range(1, self._max_attempts + 1):
+            body = {
+                **identity,
+                "event_id": f"evt_{uuid4()}",
+                "schema_version": SCHEMA_VERSION,
+                "event_type": event_type,
+                "occurred_at": format_timestamp(occurred_at or datetime.now(UTC)),
+                "idempotency_key": idempotency_key,
+                "payload": payload,
+            }
+            try:
+                response = self._sender.post(
+                    f"{self._base_url}{EVENTS_ENDPOINT}",
+                    headers={"Authorization": f"Bearer {self._ingest_key}"},
+                    json=body,
+                )
+            except httpx.TransportError as exc:
+                last_error = exc
+                if attempt < self._max_attempts:
+                    self._sleep_before_retry()
+                    continue
+                raise ViewiseServiceError(
+                    redact(
+                        f"semantic ingestion request failed: {exc}",
+                        self._ingest_key,
+                    )
+                ) from exc
+            if response.status_code >= 500 and attempt < self._max_attempts:
+                self._sleep_before_retry()
+                continue
+            return parse_receipt(
+                response,
+                event_type=event_type,
+                secret=self._ingest_key,
+                credential_label=self._credential_label,
+            )
+        raise ViewiseServiceError(
+            redact(f"semantic ingestion request failed: {last_error}", self._ingest_key)
+        )
+
+    def _identity(self, *, run_ref: str | None, run_id: str | None) -> dict[str, str]:
+        if self._agent_ref is not None:
+            if run_id is not None:
+                raise ViewiseConfigError("run_id cannot be used with agent_ref")
+            return {
+                "agent_ref": self._agent_ref,
+                "run_ref": normalize_ref(run_ref, "run ref"),
+            }
+        if run_ref is not None:
+            raise ViewiseConfigError("run_ref cannot be used with agent_id")
+        if self._agent_id is None:
+            raise ViewiseConfigError("agent_id is required")
+        return {
+            "agent_id": self._agent_id,
+            "run_id": require_uuid_text(run_id, "run id"),
+        }
+
+    def _idempotency_key(
+        self,
+        *,
+        event_type: str,
+        identity: Mapping[str, str],
+        suffix: str | None,
+    ) -> str:
+        if "agent_ref" in identity:
+            parts = [
+                self._idempotency_prefix,
+                identity["agent_ref"],
+                identity["run_ref"],
+                event_type,
+            ]
+        else:
+            parts = [self._idempotency_prefix, event_type, identity["run_id"]]
+        if suffix is not None:
+            parts.append(normalize_idempotency_part(suffix))
+        return ":".join(parts)
+
+    def _sleep_before_retry(self) -> None:
+        if self._retry_backoff_seconds > 0:
+            sleep(self._retry_backoff_seconds)
+
+
+def configure(
+    base_url: str,
+    ingest_key: str,
+    agent_ref: str,
+    agent_name: str,
+) -> None:
+    """Configure top-level SDK calls without reading environment variables."""
+
+    global _runtime_config
+    _runtime_config = RuntimeConfig(
+        base_url=require_non_blank(base_url, "VIEWISE_BASE_URL"),
+        ingest_key=require_non_blank(ingest_key, "VIEWISE_INGEST_KEY"),
+        agent_ref=normalize_ref(agent_ref, "VIEWISE_AGENT_REF"),
+        agent_name=require_non_blank(agent_name, "VIEWISE_AGENT_NAME"),
+    )
+
+
+def configured_client(*, sender: HttpSender | None = None) -> Client:
+    if _runtime_config is None:
+        return Client.from_env(sender=sender)
+    return Client(
+        base_url=_runtime_config.base_url,
+        ingest_key=_runtime_config.ingest_key,
+        agent_ref=_runtime_config.agent_ref,
+        agent_name=_runtime_config.agent_name,
+        sender=sender,
+    )
+
+
+def _reset_configuration_for_tests() -> None:
+    global _runtime_config
+    _runtime_config = None
+
+
+def start_run(
+    run_ref: str,
+    task: str,
+    occurred_at: datetime | None = None,
+    metadata: Mapping[str, object] | None = None,
+    *,
+    sender: HttpSender | None = None,
+) -> DeliveryResult:
+    mapped, skipped = map_start_metadata(metadata)
+    return deliver_safely(
+        event_type="run.started",
+        run_ref=run_ref,
+        skipped_metadata_keys=skipped,
+        call=lambda: configured_client(sender=sender).start_run(
+            run_ref=run_ref,
+            task=task,
+            occurred_at=occurred_at,
+            effective_config=optional_mapping(mapped.get("effective_config")),
+            run_context_snapshot=optional_mapping(mapped.get("run_context_snapshot")),
+            experiment_id=optional_str(mapped.get("experiment_id")),
+            entity_ref=optional_str(mapped.get("entity_ref")),
+        ),
+    )
+
+
+def observe_evidence(
+    run_ref: str,
+    source: object,
+    retrieved_at: datetime | None = None,
+    evidence_ref: str | None = None,
+    metadata: Mapping[str, object] | None = None,
+    *,
+    sender: HttpSender | None = None,
+) -> DeliveryResult:
+    mapped, skipped = map_evidence_metadata(metadata)
+    observed_at = retrieved_at or datetime.now(UTC)
+    return deliver_safely(
+        event_type="evidence.observed",
+        run_ref=run_ref,
+        skipped_metadata_keys=skipped,
+        call=lambda: configured_client(sender=sender).observe_evidence(
+            run_ref=run_ref,
+            source=source,
+            retrieved_at=observed_at,
+            evidence_ref=evidence_ref,
+            occurred_at=optional_datetime(mapped.get("occurred_at")) or observed_at,
+            published_at=optional_datetime(mapped.get("published_at")),
+            effective_at=optional_datetime(mapped.get("effective_at")),
+            effective_period_start_at=optional_datetime(
+                mapped.get("effective_period_start_at")
+            ),
+            effective_period_end_at=optional_datetime(
+                mapped.get("effective_period_end_at")
+            ),
+            available_at=optional_datetime(mapped.get("available_at")),
+            available_at_status=optional_str(mapped.get("available_at_status")),
+        ),
+    )
+
+
+def complete_run(
+    run_ref: str,
+    result: object,
+    occurred_at: datetime | None = None,
+    *,
+    sender: HttpSender | None = None,
+) -> DeliveryResult:
+    return deliver_safely(
+        event_type="run.completed",
+        run_ref=run_ref,
+        skipped_metadata_keys=(),
+        call=lambda: configured_client(sender=sender).complete_run(
+            run_ref=run_ref,
+            output=result,
+            occurred_at=occurred_at,
+        ),
+    )
+
+
+def fail_run(
+    run_ref: str,
+    exc_or_error: object,
+    occurred_at: datetime | None = None,
+    *,
+    sender: HttpSender | None = None,
+) -> DeliveryResult:
+    return deliver_safely(
+        event_type="run.failed",
+        run_ref=run_ref,
+        skipped_metadata_keys=(),
+        call=lambda: configured_client(sender=sender).fail_run(
+            run_ref=run_ref,
+            error=sanitize_error(exc_or_error),
+            occurred_at=occurred_at,
+        ),
+    )
+
+
+def deliver_safely(
+    *,
+    event_type: str,
+    run_ref: str,
+    skipped_metadata_keys: tuple[str, ...],
+    call: Callable[[], EventReceipt],
+) -> DeliveryResult:
+    try:
+        return DeliveryResult.from_receipt(
+            call(),
+            run_ref=run_ref,
+            skipped_metadata_keys=skipped_metadata_keys,
+        )
+    except Exception as exc:
+        return DeliveryResult(
+            delivered=False,
+            event_type=event_type,
+            run_ref=run_ref,
+            error=redact(
+                str(exc),
+                os.environ.get("VIEWISE_INGEST_KEY", ""),
+                os.environ.get("VIEWISE_API_KEY", ""),
+                configured_ingest_key(),
+            ),
+            skipped_metadata_keys=skipped_metadata_keys,
+        )
+
+
+def map_start_metadata(
+    metadata: Mapping[str, object] | None,
+) -> tuple[dict[str, object], tuple[str, ...]]:
+    return map_metadata(
+        metadata,
+        allowed={
+            "effective_config",
+            "run_context_snapshot",
+            "experiment_id",
+            "entity_ref",
+        },
+    )
+
+
+def map_evidence_metadata(
+    metadata: Mapping[str, object] | None,
+) -> tuple[dict[str, object], tuple[str, ...]]:
+    return map_metadata(
+        metadata,
+        allowed={
+            "occurred_at",
+            "published_at",
+            "effective_at",
+            "effective_period_start_at",
+            "effective_period_end_at",
+            "available_at",
+            "available_at_status",
+        },
+    )
+
+
+def map_metadata(
+    metadata: Mapping[str, object] | None,
+    *,
+    allowed: set[str],
+) -> tuple[dict[str, object], tuple[str, ...]]:
+    if metadata is None:
+        return {}, ()
+    mapped = {key: value for key, value in metadata.items() if key in allowed}
+    skipped = tuple(sorted(key for key in metadata if key not in allowed))
+    return mapped, skipped
+
+
+def optional_env(name: str) -> str | None:
+    value = os.environ.get(name)
+    if value is None or not value.strip():
+        return None
+    return value.strip()
+
+
+def optional_mapping(value: object) -> Mapping[str, object] | None:
+    if value is None:
+        return None
+    if not isinstance(value, Mapping):
+        raise ViewiseConfigError("metadata value must be an object")
+    return cast(Mapping[str, object], value)
+
+
+def optional_datetime(value: object) -> datetime | None:
+    if value is None:
+        return None
+    if not isinstance(value, datetime):
+        raise ViewiseConfigError("metadata timestamp must be a datetime")
+    return value
+
+
+def optional_str(value: object) -> str | None:
+    if value is None:
+        return None
+    if not isinstance(value, str):
+        raise ViewiseConfigError("metadata value must be a string")
+    return value
+
+
+def sanitize_error(error: object) -> dict[str, str]:
+    if isinstance(error, Mapping) and "message" in error:
+        message = str(error.get("message") or "unknown error")
+    else:
+        message = str(error or "unknown error")
+    message = redact(message, *environment_secrets())
+    for pattern in _REQUEST_DETAIL_PATTERNS:
+        message = pattern.sub(_omit_match, message)
+    if len(message) > _SAFE_ERROR_MESSAGE_LIMIT:
+        message = message[: _SAFE_ERROR_MESSAGE_LIMIT - 3].rstrip() + "..."
+    return {"message": message}
+
+
+def normalize_source(source: object) -> str:
+    if isinstance(source, str):
+        return require_non_blank(source, "source")
+    try:
+        serialized = json.dumps(
+            source,
+            ensure_ascii=False,
+            separators=(",", ":"),
+            sort_keys=True,
+        )
+    except TypeError:
+        serialized = str(source)
+    return require_non_blank(serialized, "source")
+
+
+def parse_receipt(
+    response: Response,
+    *,
+    event_type: str,
+    secret: str,
+    credential_label: str = "ingest key",
+) -> EventReceipt:
+    if response.status_code in (401, 403):
+        raise ViewiseAuthError(
+            redact(response_detail(response) or f"invalid {credential_label}", secret)
+        )
+    if response.status_code >= 500:
+        detail = response_detail(response) or response.text
+        raise ViewiseServiceError(
+            redact(
+                f"semantic ingestion failed with {response.status_code}: {detail}",
+                secret,
+            )
+        )
+    if response.status_code >= 400:
+        detail = response_detail(response) or response.text
+        raise ViewiseRequestError(
+            redact(
+                f"semantic ingestion failed with {response.status_code}: {detail}",
+                secret,
+            )
+        )
+    try:
+        payload = response.json()
+    except ValueError as exc:
+        raise ViewiseRequestError(
+            redact("semantic ingestion returned invalid receipt", secret)
+        ) from exc
+    if not isinstance(payload, Mapping):
+        raise ViewiseRequestError("semantic ingestion returned invalid receipt")
+    return EventReceipt(
+        event_id=str(payload.get("event_id", "")),
+        run_id=str(payload.get("run_id", "")),
+        event_type=str(payload.get("event_type", event_type)),
+        status=str(payload.get("status", "")),
+        run_status=str(payload.get("run_status", "")),
+        raw=cast(Mapping[str, object], payload),
+        agent_ref=optional_text(payload.get("agent_ref")),
+        run_ref=optional_text(payload.get("run_ref")),
+    )
+
+
+def response_detail(response: Response) -> str | None:
+    try:
+        payload = response.json()
+    except ValueError:
+        return None
+    if isinstance(payload, Mapping):
+        detail = payload.get("detail")
+        if detail is not None:
+            return str(detail)
+    return None
+
+
+def compact_context_snapshot(value: Mapping[str, object]) -> dict[str, object]:
+    return {key: value[key] for key in CONTEXT_SNAPSHOT_KEYS if key in value}
+
+
+def add_optional_timestamp(
+    payload: dict[str, object],
+    key: str,
+    value: datetime | None,
+) -> None:
+    if value is not None:
+        payload[key] = format_timestamp(value)
+
+
+def format_timestamp(value: datetime) -> str:
+    if value.tzinfo is None or value.utcoffset() is None:
+        raise ViewiseConfigError("timestamps must include timezone")
+    return value.astimezone(UTC).isoformat().replace("+00:00", "Z")
+
+
+def require_env(name: str) -> str:
+    return require_non_blank(os.environ.get(name, ""), name)
+
+
+def require_one_key(
+    *,
+    ingest_key: str | None,
+    api_key: str | None,
+    label: str,
+) -> str:
+    if ingest_key is not None and api_key is not None:
+        raise ViewiseConfigError("provide only one of ingest_key or api_key")
+    return require_non_blank(ingest_key or api_key or "", label)
+
+
+def require_non_blank(value: str, label: str) -> str:
+    stripped = value.strip()
+    if not stripped:
+        raise ViewiseConfigError(f"{label} is required")
+    return stripped
+
+
+def normalize_ref(value: str | None, label: str) -> str:
+    if value is None:
+        raise ViewiseConfigError(f"{label} is required")
+    stripped = require_non_blank(value, label)
+    if not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9._-]{0,127}", stripped):
+        raise ViewiseConfigError(f"{label} must be a valid ref")
+    return stripped
+
+
+def require_uuid_text(value: str | None, label: str) -> str:
+    if value is None:
+        raise ViewiseConfigError(f"{label} is required")
+    try:
+        return str(UUID(require_non_blank(value, label)))
+    except ValueError as exc:
+        raise ViewiseConfigError(f"{label} must be a valid UUID") from exc
+
+
+def normalize_idempotency_part(value: str) -> str:
+    return require_non_blank(value, "idempotency part").replace("\n", " ")
+
+
+def optional_text(value: object) -> str | None:
+    if value is None:
+        return None
+    return str(value)
+
+
+def redact(message: str, *secrets: str) -> str:
+    redacted = message
+    for secret in secrets:
+        if secret:
+            redacted = redacted.replace(secret, "[REDACTED]")
+    for pattern in _CREDENTIAL_PATTERNS:
+        redacted = pattern.sub(_redact_match, redacted)
+    return redacted
+
+
+def environment_secrets() -> tuple[str, ...]:
+    names = {
+        "VIEWISE_INGEST_KEY",
+        "VIEWISE_API_KEY",
+        "OPENAI_API_KEY",
+        "ANTHROPIC_API_KEY",
+    }
+    values = []
+    for name, value in os.environ.items():
+        upper_name = name.upper()
+        if name in names or any(
+            token in upper_name for token in ("API_KEY", "TOKEN", "SECRET")
+        ):
+            stripped = value.strip()
+            if len(stripped) >= 8:
+                values.append(stripped)
+    configured = configured_ingest_key()
+    if configured:
+        values.append(configured)
+    return tuple(values)
+
+
+def configured_ingest_key() -> str:
+    if _runtime_config is None:
+        return ""
+    return _runtime_config.ingest_key
+
+
+def _redact_match(match: re.Match[str]) -> str:
+    if len(match.groups()) >= 3:
+        return f"{match.group(1)}{match.group(2)}[REDACTED]"
+    if match.group(0).lower().startswith("bearer"):
+        return "Bearer [REDACTED]"
+    return "[REDACTED]"
+
+
+def _omit_match(match: re.Match[str]) -> str:
+    return f"{match.group(1)}{match.group(2)}[OMITTED]"

viewise-0.1.2/viewise.egg-info/PKG-INFO

@@ -0,0 +1,92 @@
+Metadata-Version: 2.4
+Name: viewise
+Version: 0.1.2
+Summary: Python SDK for Viewise semantic telemetry ingestion.
+Author: Viewise
+Project-URL: Homepage, https://github.com/Tanishv/xalpha
+Project-URL: Repository, https://github.com/Tanishv/xalpha
+Project-URL: Issues, https://github.com/Tanishv/xalpha/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.27
+
+# Viewise Python SDK
+
+Viewise observes agent runs through a small semantic telemetry contract. The SDK
+sends events to a Viewise backend and keeps agent code resilient when telemetry
+is unavailable.
+
+## Install
+
+```bash
+python -m pip install viewise
+```
+
+## Configure
+
+Set the runtime environment values copied from the Viewise Setup page:
+
+```bash
+export VIEWISE_BASE_URL="https://viewise-backend.fly.dev"
+export VIEWISE_INGEST_KEY="<workspace-api-key-from-viewise-setup>"
+export VIEWISE_AGENT_REF="workspace.agentx"
+export VIEWISE_AGENT_NAME="agentx"
+```
+
+You can also configure the SDK in code:
+
+```python
+import viewise
+
+viewise.configure(
+    base_url="https://viewise-backend.fly.dev",
+    ingest_key="<workspace-api-key-from-viewise-setup>",
+    agent_ref="workspace.agentx",
+    agent_name="agentx",
+)
+```
+
+Never commit API keys or place them in prompts, logs, or source code.
+
+## API
+
+```python
+viewise.start_run(run_ref, task, occurred_at=None)
+viewise.observe_evidence(run_ref, source, retrieved_at=None, evidence_ref=None)
+viewise.complete_run(run_ref, result, occurred_at=None)
+viewise.fail_run(run_ref, exc_or_error, occurred_at=None)
+viewise.sanitize_error(exc_or_error)
+```
+
+Supported event types are:
+
+- `run.started`
+- `evidence.observed`
+- `run.completed`
+- `run.failed`
+
+Top-level telemetry calls return a delivery result. They do not raise when
+Viewise or the network is unavailable, so agent work can continue.
+
+## Smoke Test
+
+```python
+import viewise
+
+run_ref = "local-run-001"
+
+viewise.start_run(run_ref, "SDK install smoke test")
+viewise.observe_evidence(
+    run_ref,
+    {"provider": "local", "kind": "smoke"},
+    evidence_ref="smoke-001",
+)
+viewise.complete_run(run_ref, {"status": "ok"})
+```

viewise-0.1.2/viewise.egg-info/SOURCES.txt

@@ -0,0 +1,9 @@
+README.md
+README.pypi.md
+pyproject.toml
+viewise/__init__.py
+viewise.egg-info/PKG-INFO
+viewise.egg-info/SOURCES.txt
+viewise.egg-info/dependency_links.txt
+viewise.egg-info/requires.txt
+viewise.egg-info/top_level.txt

viewise-0.1.2/viewise.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

viewise-0.1.2/viewise.egg-info/requires.txt

@@ -0,0 +1 @@
+httpx>=0.27

viewise-0.1.2/viewise.egg-info/top_level.txt

@@ -0,0 +1 @@
+viewise