From install to first incident.

The core is pure Python standard library: pip install then run works offline, with deterministic fake backends and no API keys. Frontier providers are opt-in extras behind vendor-neutral seams.

Install

python3 -m venv .venv
source .venv/bin/activate
pip install percept-vision
python -c "import percept; print('Percept import ready')"

Package name: percept-vision. Python import: percept. Heavy dependencies (cv2, numpy, sounddevice) arrive lazily via extras; the package imports cleanly with nothing extra installed.

Arm a watch

watch() is the frozen high-level entrypoint (WATCH_VERSION = "1.1.0"). Goals are plain-language strings — or Goal objects, or WatchPlans, or any mix. A frame that changes nothing yields zero events; one WatchEvent is yielded per gate FIRE or ASK.

import percept

async for event in percept.watch(stream, "the kettle boils"):
    handle(event)  # WatchEvent — one per gate FIRE or ASK; silent frames yield nothing

Run a source end to end

percept.run(...) is the batteries-included front door: it opens a video or audio source, drives the cognition core over frames, and yields durable Incidents. Delivery is idempotent — incidents are deduped by incident.id on redelivery.

import percept

async for incident in percept.run(
    source="kitchen.mp4",                  # camera index, file, or RTSP — or any frame iterable
    goals=["the milk is boiling over"],
    fps=4.0,
    on_ask=handle_ask,                     # low-confidence refusals — asks are not incidents
):
    notify(incident)                       # a durable Incident, deduped on redelivery

Offline mode — no keys, no network

The deterministic fakes (FakeVision, FakeConductor, FakeSTT, FakeTTS) call no network and need no credential, so you can exercise the full wiring before any provider is chosen.

from percept import Percept

agent = Percept.create(mode="offline")     # scripted/fake seams — no keys, no network
verdict = await agent.perceive_judged(frame)

Safety posture: in LIVE mode an unset vision backend — or a real backend with its credential missing — raises a loud ModeError naming the exact env var to set. You can never silently land on a fake and mistake it for success.

Where to go next

1. Understand the pipelineRead how a frame moves sample → route → cache → judge → gate, and why the gate has three states, in Cognition pipeline.
2. Author richer plansMove from bare strings to typed WatchPlans with judges and overrides in WatchPlans & goals.
3. Try the hosted serviceRun the same wheel without installing anything via Percept Cloud and its API.