Perago

文档站（Read the Docs） · PyPI

Perago 是一个面向 Conductor worker 的 typed Python 运行时层，用来在版本化 workspace 上执行任务。它把任务函数签名、Pydantic 输入输出契约、Conductor TaskDef、LakeFS workspace 下载与按需发布、guardrail 校验和 worker 启动边界收敛到同一套模型里。

本文档提供项目概览、安装方式和最小入口；完整说明见文档站。

安装

要求 Python 3.10 或更新版本。

uv add perago

或：

pip install perago

仓库本地开发使用：

uv sync

最小示例

下面是一个最小的 workspace task。任务作者只需要声明 typed params/output、workspace 约束和任务元数据；Perago 负责校验、TaskDef 提取和运行时集成。

from pathlib import Path

from pydantic import BaseModel, Field

from perago import WorkspaceSpec, require_glob, task


class BuildFeaturesParams(BaseModel):
    feature_set: str
    min_rows: int = Field(ge=1)


class BuildFeaturesOutput(BaseModel):
    row_count: int = Field(ge=0)
    feature_count: int = Field(ge=0)


@task(
    name="features.build",
    owner_email="data@example.com",
    workspace=WorkspaceSpec(
        prefix="/",
        pre=[require_glob("raw/**/*.parquet", min_count=1)],
    ),
)
def build_features(
    workspace: Path,
    params: BuildFeaturesParams,
) -> BuildFeaturesOutput:
    return BuildFeaturesOutput(row_count=100, feature_count=24)

workspace-free task 使用同一套 decorator 和 typed contract，但不声明 workspace: Path，也不声明 WorkspaceSpec。

快速入口

perago CLI 的 MVP 入口是单任务 module target：

perago check app.workers.features_build
perago extract app.workers.features_build --output generated/features.build.json
perago start app.workers.features_build -j 4

perago check：导入模块并校验任务声明与本地 runtime config。
perago extract：生成带嵌入 schema 的 Conductor TaskDef JSON。
perago start：在真实 Conductor 配置下启动 supervisor-managed worker processes；workspace task 还需要 LakeFS 配置。

文档

文档首页：https://perago.readthedocs.io/zh-cn/latest/
Getting Started：https://perago.readthedocs.io/zh-cn/latest/getting-started/
LakeFS 发布协议：https://perago.readthedocs.io/zh-cn/latest/lakefs-publication-protocol.html
Development：https://perago.readthedocs.io/zh-cn/latest/development.html

仓库内的对应内容可从这里继续展开：

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

perago-0.6.1.tar.gz (106.4 kB view details)

Uploaded Jul 22, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

perago-0.6.1-py3-none-any.whl (79.5 kB view details)

Uploaded Jul 22, 2026 Python 3

File details

Details for the file perago-0.6.1.tar.gz.

File metadata

Download URL: perago-0.6.1.tar.gz
Upload date: Jul 22, 2026
Size: 106.4 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for perago-0.6.1.tar.gz
Algorithm	Hash digest
SHA256	`a12e6dbd9ad3661584fb375066f5313c0264d712398afd71fcae4e84b9a89f9b`
MD5	`7239b723dfaf28f05e80363f2052724b`
BLAKE2b-256	`1d7913ca3e213891d92e0c912079741cee6b3c5bcaf0dc620ab257dd2dbf0e6f`

See more details on using hashes here.

Provenance

The following attestation bundles were made for perago-0.6.1.tar.gz:

Publisher: publish.yml on Qiyin-Tech/perago

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: perago-0.6.1.tar.gz
- Subject digest: a12e6dbd9ad3661584fb375066f5313c0264d712398afd71fcae4e84b9a89f9b
- Sigstore transparency entry: 2215816862
- Sigstore integration time: Jul 22, 2026
Source repository:
- Permalink: Qiyin-Tech/perago@c1a29cd42eafb305516176a14315e142a5f8a7c1
- Branch / Tag: refs/tags/v0.6.1
- Owner: https://github.com/Qiyin-Tech
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: publish.yml@c1a29cd42eafb305516176a14315e142a5f8a7c1
- Trigger Event: release

File details

Details for the file perago-0.6.1-py3-none-any.whl.

File metadata

Download URL: perago-0.6.1-py3-none-any.whl
Upload date: Jul 22, 2026
Size: 79.5 kB
Tags: Python 3
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for perago-0.6.1-py3-none-any.whl
Algorithm	Hash digest
SHA256	`f4dda48d195dd4a9e0b7509213c60fd370fad757f1b14d20f44f9d0c41272183`
MD5	`621199a13c3dd950b3bb18b52e84e8c4`
BLAKE2b-256	`21868b168ad142cad11ce217543fcf777b0755aeaa5951ae18287ae1f9833a1c`

See more details on using hashes here.

Provenance

The following attestation bundles were made for perago-0.6.1-py3-none-any.whl:

Publisher: publish.yml on Qiyin-Tech/perago

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: perago-0.6.1-py3-none-any.whl
- Subject digest: f4dda48d195dd4a9e0b7509213c60fd370fad757f1b14d20f44f9d0c41272183
- Sigstore transparency entry: 2215816885
- Sigstore integration time: Jul 22, 2026
Source repository:
- Permalink: Qiyin-Tech/perago@c1a29cd42eafb305516176a14315e142a5f8a7c1
- Branch / Tag: refs/tags/v0.6.1
- Owner: https://github.com/Qiyin-Tech
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: publish.yml@c1a29cd42eafb305516176a14315e142a5f8a7c1
- Trigger Event: release

Release history Release notifications | RSS feed

This release

0.6.1

Jul 22, 2026

0.6.0

Jul 21, 2026

0.5.0

Jun 12, 2026

0.4.0

May 27, 2026

0.3.0

May 21, 2026

0.2.0

May 20, 2026

0.1.0

May 20, 2026

perago 0.6.1

Perago

安装

最小示例

快速入口

文档

Key dates

1 maintainer

Credits

Requires

Download files

Source Distribution

Built Distribution

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

Release history Release notifications | RSS feed