Metadata-Version: 2.4
Name: synax-sdk
Version: 0.2.4
Summary: Python SDK and CLI for building skills on the Synax agentic platform.
Project-URL: Homepage, https://github.com/synergentic/synax-sdk
Project-URL: Documentation, https://github.com/synergentic/synax-sdk/tree/main/docs
Project-URL: Repository, https://github.com/synergentic/synax-sdk
Author: Synergentic, Inc., Juan Hernandez
License: Apache-2.0
License-File: LICENSE
Keywords: agentic,ai,sdk,skills,synax
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27
Requires-Dist: jsonschema>=4.0
Requires-Dist: pynacl>=1.5
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: black>=24.0; extra == 'dev'
Requires-Dist: isort>=5.13; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pip-audit>=2.7; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Requires-Dist: types-jsonschema>=4.0; extra == 'dev'
Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
Description-Content-Type: text/markdown

# synax-sdk

[![CI](https://github.com/synergentic/synax-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/synergentic/synax-sdk/actions/workflows/ci.yml)
[![PyPI version](https://img.shields.io/pypi/v/synax-sdk.svg)](https://pypi.org/project/synax-sdk/)
[![Python versions](https://img.shields.io/pypi/pyversions/synax-sdk.svg)](https://pypi.org/project/synax-sdk/)
[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)

The Python SDK and `synax` CLI for building **skills** on the [Synax](https://synax.com)
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

```bash
pip install synax-sdk
```

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

## Quick start

```bash
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:

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

## What a skill looks like

```python
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>/`:

```yaml
# 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`](./docs/testing_skills.md)
for the full schema.

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

```python
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`](./CHANGELOG.md) for what's
new and breaking.

## Documentation

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

## Development

```bash
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`](./LICENSE).
