synax-sdk 0.3.0

Python SDK and CLI for building skills on the Synax agentic platform.

synax-sdk

The Python SDK and synax CLI for building skills on the Synax agentic platform. Skill developers use this SDK to define skills in Python, generate the manifest automatically, sign artifacts with Ed25519, and publish them to a Synax platform instance.

Install

pip install synax-sdk

That gives you both the synax_sdk Python library and the synax CLI.

Quick start

synax keys generate                 # one-time, creates ~/.synax/keys/<fp>.key
synax skill init my-first-skill     # scaffold a new project
cd my-first-skill
uv sync                              # install deps (synax-sdk pinned)
uv run synax skill test              # run the bundled declarative test case
uv run synax skill build             # produce a signed artifact in build/signed_bundle/

To publish:

export SYNAX_PUBLISH_TOKEN=spt_...
uv run synax skill publish --target https://synax.your-company.com

What a skill looks like

from synax_sdk import Skill, secrets, logger

skill = Skill(
    name="github-pr-summary",
    version="1.0.0",
    description="Fetch and summarize GitHub pull requests",
    capabilities=["network:api.github.com", "secrets:GITHUB_TOKEN"],
    secrets=[{"name": "GITHUB_TOKEN", "type": "oauth_token", "description": "..."}],
)


@skill.tool(description="Fetch a PR and return a structured summary")
async def summarize_pr(repo: str, pr_number: int) -> dict:
    """Summarize a pull request.

    Args:
        repo: Repository in format owner/name.
        pr_number: Pull request number.
    """
    token = await secrets.get("GITHUB_TOKEN")
    logger.info("Summarizing PR", extra={"repo": repo, "pr_number": pr_number})
    # ... call the GitHub API, summarize, return ...
    return {"title": "...", "summary": "...", "files_changed": 7}

The SDK derives a full manifest from this code at build time. Type hints become JSON Schema parameter definitions. The Google-style docstring's Args: section becomes per-parameter descriptions. Capabilities and secrets get validated against the skill's declarations.

Testing locally

Two complementary patterns ship out of the box.

Declarative — drop a YAML case under test_inputs/<tool>/:

# test_inputs/summarize_pr/case_basic.yaml
input:
  repo: "owner/name"
  pr_number: 42
secrets:
  GITHUB_TOKEN: "test-token"
expected_output_schema:
  type: object
  properties:
    title: {type: string}
expected_secret_accesses: ["GITHUB_TOKEN"]

Run with synax skill test. See docs/testing_skills.md for the full schema.

Pytest-based — the SDK auto-registers two fixtures:

async def test_summarize_pr(synax_mock_platform, synax_skill_under_test):
    synax_mock_platform.secrets.set("GITHUB_TOKEN", "test-token")

    tool = next(t for t in synax_skill_under_test.tools if t.name == "summarize_pr")

    from synax_sdk.testing import run_tool_async
    result = await run_tool_async(tool, repo="owner/name", pr_number=42)

    assert "title" in result

CLI commands

synax keys
  generate / list / export / import / set-default / register

synax skill
  init <name>     scaffold a new project
  validate        check the manifest against the v1.0 schema
  test            run declarative test cases under test_inputs/
  info            show the loaded skill's metadata
  build           sign + package into build/signed_bundle/
  verify <yaml>   verify the signatures on a manifest
  publish         upload a signed bundle to a Synax platform

Run any command with --help for full options.

Status

This is the initial 0.1.0 release. The public API may change between minor versions until 1.0 — see CHANGELOG.md for what's new and breaking.

Documentation

• docs/README.md — project overview and reading order
• docs/parent_platform_context.md — what Synax is
• docs/manifest_spec.md — the v1.0 manifest format
• docs/testing_skills.md — testing patterns
• docs/technical_plan.md — internal design
• CHANGELOG.md — release notes

Development

uv sync                                           # install deps + create .venv
uv run pytest                                     # run tests
uv run ruff check .                               # lint
uv run black --check . && uv run isort --check .  # format check
uv run mypy synax_sdk synax_skill_cli             # type check

License

Apache License 2.0 — see LICENSE.