perceivo

Python SDK for building AI orchestration components: create, validate and run orchestrations locally, then publish them to Perceivo Cloud.

Installation

pip install perceivo

Optional extras add service clients, for example Redis:

pip install "perceivo[redis]"

The extras are redis, milvus, elasticsearch, database and fastapi. Python 3.11, 3.12 and 3.13 are supported.

Quick start

These commands create a project with a starter orchestration, validate it and run it locally. They need no account.

perceivo init
perceivo new orchestration my-first-orch
perceivo validate component ./my-first-orch/agent.py ./my-first-orch/agent.yaml
perceivo validate orchestration ./my-first-orch/
perceivo run orchestration ./my-first-orch/ --input '{"query": "test"}'
# expect: RESULT: PASS

Write your own component

Replace my-first-orch/agent.py with:

import perceivo

@perceivo.agent
async def my_agent(input: perceivo.primitives.AgentInput) -> perceivo.primitives.AgentOutput:
    api_key = await perceivo.secrets.get("ANTHROPIC_API_KEY")
    perceivo.log.info("Processing request")

    # Your logic here
    answer = "Hello from perceivo!"

    return perceivo.primitives.AgentOutput(
        artifact=perceivo.primitives.Artifact(
            type=perceivo.primitives.ArtifactType.JSON,
            data={"answer": answer},
        ),
        response_data={"answer": answer, "result": answer},
    )

Then run the two validate commands and the run command again.

Component Types

SDK Modules

The first group is what a component body normally reaches for; the second is the authoring and local-run side, used by the CLI and by scripts around a project.

For HTTP requests to external APIs (LLMs, etc.), use httpx or the provider's Python SDK directly. Retrieve API keys with perceivo.secrets.get().

Configuration

Create a perceivo.yaml in your project:

version: 1

files:
  working_dir: ./working_files
  org_dir: ./org_files

secrets:
  source: dotenv
  dotenv_path: .env

redis:
  enabled: false
  url: redis://localhost:6379

logging:
  level: INFO
  format: console

Secrets are read from .env in local mode. In Perceivo Cloud, they are resolved from the configured managed secret service.

Local vs Cloud

Local runs exercise the same component interface through local adapters and configured mocks. Cloud runs use managed services and distributed execution, so credentials, service availability, networking, and performance differ even when the component code stays the same. See the documentation for adapter and mocking guidance.

Documentation

The complete documentation is at perceivo.ai/docs. The examples directory holds three complete orchestrations, each exactly as it downloads from the website: an import file, one folder per component and a notebook that runs it on your machine.

Support and security

• Questions and bugs: open an issue, or email support@perceivo.ai.
• Security vulnerabilities: do not open a public issue; follow SECURITY.md.
• Contributing: see CONTRIBUTING.md and the Code of Conduct.

License

Apache 2.0 — see LICENSE.