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"})
```
