Skip to main content
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
NodeWhat it addsExample
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.