Build systems that know what to notice.
Percept (percept-vision) is an open-source cognition layer for goal-driven, proactive vision agents: entity memory, a three-state consequence gate, and reasoning over events — the temporal cognition a raw VLM-in-a-loop lacks. Percept Cloud runs the same wheel as a hosted service.
The first line is the shape of the product; the second is the frozen OSS entrypoint you actually call. goals accepts bare strings, Goal objects, WatchPlans, or any mix.
Quickstart
Install the package, arm a plain-language watch, and iterate incidents with percept.run — offline, with no API keys.
02 · ConceptsCognition pipeline
Sample → route → cache → judge → gate. The three-state gate, rising-edge firing, and fail-closed judging.
03 · ConceptsWatchPlans & goals
How intent travels from a plain string to an armed goal: desugaring, stable ids, two-phase apply, and configuration provenance.
04 · ConceptsEvidence & memory
Episodes, the entity graph, opaque evidence handles, durable incidents, and the single diagnostic funnel.
05 · ManagedPercept Cloud
Hosted runs of the provenance-stamped OSS wheel over a bearer-protected API, with provisioned client API keys.
06 · ReferenceAPI reference
Endpoints, multipart fields, run lifecycle, response schemas, and a create-and-poll curl pair.
Core concepts
Watch
A standing, plain-language condition armed over a stream. Watches are intent — not a request to call a model on every frame. The frozen entrypoint is watch().
Goal
The compiled unit a watch arms. Bare strings desugar into Goal objects with stable content-hash ids; the plain-language condition is carried verbatim, never compiled to a rigid predicate.
Gate
The sole firing authority. Every verdict — judged, transition, episode, absence, rhythm — maps to exactly one of three states: FIRE, ASK, or SILENT. The gate fires on the rising edge, not on every frame a condition stays true.
WatchEvent
What watch() yields: one event per gate FIRE or ASK. A frame that changes nothing yields nothing.
Incident
The durable record of a fire, produced by percept.run and by hosted Cloud runs. Incidents are deduplicated on redelivery by incident id.
Evidence handle
An opaque reference to the retained material behind a decision. Decisions carry handles, not raw frames; dereference yields a real artifact or a typed failure — never a silent empty.
Trace
The recorded runtime path of a run: TraceEvents structured into a portable bundle that replays deterministically without ever calling a model.
Product boundaries
| Surface | Owns | Does not own |
|---|---|---|
| Percept OSS | The gate, runtime semantics, Incidents, evidence, trace | Hosted tenancy or API keys |
| Percept Cloud | Hosted execution of the pinned OSS wheel, auth, samples, run lifecycle | A fork of OSS perception semantics |
| Playground | A guided experience over the Cloud API | Runtime authorization logic |