Author SDK

The convilyn-sdk package — for third parties who build tool servers and workflow specs that run on the Convilyn platform.

This is different from the consumer SDK (convilyn), which is what applications use to call the platform. The two packages are split so the consumer SDK stays lightweight: workflow authors need server-side dependencies (Pydantic models for the wire format, server runtime helpers) that API callers don't.

Install

pip install convilyn-sdk

The v1.x legacy convilyn console-script still routes into the same Click group as convilyn-author but emits a one-time deprecation banner. It is scheduled for removal in v2.0; new scripts and CI should call convilyn-author directly.

What you build with it

Quick map

from convilyn_sdk import (
    # Servers
    ToolServer,
    ConvilynServer,
    ConvilynClient,
    ConvilynManifest,
    ToolCatalog,
    ToolContext,
    InMemoryDataStore,

    # Workflows
    WorkflowSpec,
    AgentRole,

    # Multi-role + checkpoints
    MultiRoleConfig,
    RoleConfig,
    CheckpointConfig,
    MultiAgentConfig,        # deprecated alias of MultiRoleConfig
    SpecialistConfigModel,   # deprecated alias of RoleConfig

    # Policy primitives
    FailureRule,
    TerminalFailureRule,
    RetryPolicy,
    TimeoutPolicy,
    ToolStage,
    OutputValidationPolicy,
    PatternCheck,
    RequiredSection,
    StructureCheck,
    HumanReviewPolicy,
    FallbackPolicy,

    # Policy wire-shape Configs (Pydantic siblings used by the builder)
    FailureRuleConfig,
    FallbackPolicyConfig,
    GoalCriteriaConfig,
    QaPolicyConfig,
    QualityCheckConfig,
    RetryPolicyConfig,
    RoutingPolicyConfig,
    SectionConfig,
    SlotPolicyConfig,
    StructuralCheckConfig,
    TaskPolicyConfig,
    TerminalFailurePolicyConfig,
    ToolStageConfig,

    # Tool execution types
    ToolSpec,
    ToolResult,
    ToolError,
    ToolDataRef,
    ComplianceReport,
    ComplianceResult,
)

Every name exported from convilyn_sdk at the top level is part of the supported public API. Anything starting with _ (e.g. convilyn_sdk._internal) is private and may change between releases.

Two-minute example

from convilyn_sdk import ToolServer, WorkflowSpec

server = ToolServer(name="my-analyzer", description="Text analysis tools")

@server.tool(description="Analyze text")
async def analyze_text(text: str) -> dict:
    return {"length": len(text), "words": len(text.split())}

workflow = (
    WorkflowSpec("my_text_analyzer", name="Text Analyzer")
    .with_input(types=["document"], formats=["pdf", "txt"])
    .with_output(format="json", additional={"type": "analysis_result"})
    .from_server(server)
    .add_phase("Parse", "Extract text using `my_analyzer__analyze_text`.")
)

# Compile to wire JSON
spec_json = workflow.compile()

# Run locally
if __name__ == "__main__":
    server.run()

Deployment

The author SDK ships its own deployment guide covering the three supported targets — containerized Lambda, Fargate, and any HTTPS-reachable VM. See the DEPLOYMENT.md in the package.

Versioning

convilyn-sdk follows semantic versioning. The v1.x line keeps Specialist / MultiAgentConfig / SpecialistConfigModel as deprecation aliases of their canonical names (AgentRole / MultiRoleConfig / RoleConfig); v2.0 will drop the aliases.

Next steps

• Tool Servers — ToolServer, @server.tool, ToolContext, manifest + data store
• Workflows — WorkflowSpec builder, multi-role workflows, checkpoints
• Policies — retry, timeout, fallback, output-validation, human-review knobs
• Types — Pydantic models for tool execution + compliance reports
• Hosted Runtime — deploy --hosted, rollback, logs CLI for the Convilyn-managed Lambda path
• Templates — template list / install / fork for the community marketplace