piq

piq is a minimalist go-look-report primitive for AI agents — one verb, modality dispatch, observe-only by covenant, and a bundled cheap-vision report. It is the observation layer that lets an agent look before it acts, without pulling in a full computer-use stack.

The problem

AI agents that edit code or manage systems need to inspect the world before making changes, but the available options are either overpowered (full computer-use frameworks with screenshot stacks and toolchains) or underpowered (shell commands that return unstructured text). There was no single, cheap primitive that could dispatch across modalities — file reads, image captures, web fetches — and return a structured observation without side effects, so every agent reinvented the same look-before-leap boilerplate.

The approach

piq exposes one verb — observe — that dispatches across input modalities (local files, URLs, images) and returns a structured report. The observe-only covenant guarantees no writes, no mutations, and no side effects, so the caller can trust the observation layer as a read-only boundary. A bundled cheap-vision pass using a lightweight model annotates image observations without requiring a heavyweight vision stack. The 9-test suite, 5 documentation pages, CI, and pre-commit hooks gate the contract.

What it demonstrates

Shipping an observe-only primitive with an explicit no-side-effect covenant at stage 5 shows the same discipline as a larger tool: the contract has to hold because every agent above it depends on the guarantee that a look never alters what it sees. The minimal test and doc surface matches the minimal surface area — one verb, one guarantee.