Perceive basics - Perceptron Docs

Perceive turns regular Python functions into prompt templates. You describe the sequence of messages, call the function, and receive a structured result.

from perceptron import perceive, image, text

@perceive()
def describe(image_path):
    return image(image_path) + text("Describe the primary object.")

print(describe("drone.png").text)

The SDK assembles the request payload, calls the API, and returns a PerceiveResult that contains text, structured points, parsed segments, and semantic warnings.

Building blocks

from perceptron import system, text, agent, image, point, box, polygon, block

Node	What it adds	Example
`system(text)`	Global instruction.	`system("You are an inspection assistant.")`
`text(str)`	User text content.	`text("List defects")`
`image(value)`	Register an image input.	`img = image("frame.png")`
`agent(text)`	Assistant history.	`agent(previous_answer)`
`point/box/polygon(...)`	Spatial anchor tied to an image.	`box(40, 60, 160, 140, image=img)`
`block(*nodes)`	Reusable group of nodes.	`block(system_prompt, text_hint)`

Compose nodes with + to keep ordering explicit.

Expect a specific structure

from perceptron import perceive, image, text

@perceive(expects="point")
def find_center(frame):
    return image(frame) + text("Return one point marking the defect center.")

result = find_center("part.jpg")
print(result.points)  # [SinglePoint(...)]
print(result.errors)  # semantic warnings, if any

Setting expects adds deterministic guidance, validates the result, and filters result.points to that type. Turn on allow_multiple=True when the model should return more than one tag.

Multiple images

from perceptron import perceive, image, text, box

@perceive()
def compare(day, night):
    day_img = image(day)
    night_img = image(night)
    return (
        text("Compare the highlighted region in both frames.")
        + night_img
        + box(40, 60, 160, 140, mention="focus", image=night_img)
        + day_img
    )

When more than one image is present, always pass image= to the anchors so the SDK binds coordinates to the correct image. With strict=True, missing anchors raise AnchorError; otherwise the SDK records a warning in result.errors.

Validate and debug

Review result.errors for semantic issues before trusting structured outputs.
Inspect result.parsed to see text and tags in order.
Call inspect_task(your_function, ...) to view the compiled Task without sending a request.

Need more answers? The Python SDK FAQs cover common troubleshooting steps and roadmap questions.

​Building blocks

​Expect a specific structure

​Multiple images

​Validate and debug

Building blocks

Expect a specific structure

Multiple images

Validate and debug