Metadata-Version: 2.4
Name: tenaxisos-sdk
Version: 0.2.0
Summary: Build, validate, sign, and publish TenaxisOS packages and playbooks
License: MIT
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer>=0.12
Requires-Dist: rich>=13
Requires-Dist: jsonschema>=4.23
Requires-Dist: cryptography>=42
Requires-Dist: httpx>=0.27
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Provides-Extra: langchain
Requires-Dist: langchain-core>=0.3; extra == "langchain"
Provides-Extra: mcp
Requires-Dist: mcp>=1.0; extra == "mcp"
Dynamic: license-file

# tenaxisos-sdk

Python SDK and CLI for building, testing, signing, and publishing TenaxisOS
packages — agents, MCP servers, and playbooks that install into a TenaxisOS
kernel and can be shared through the Tenaxis Hub.

## What this is

`tenaxisos-sdk` is the toolkit for building community capabilities for
TenaxisOS:

- **Author** agents and MCP servers as plain Python, using `Agent` and
  `MCPServer` base classes with host-brokered LLM/tool/file access — no
  network calls, secrets, or infrastructure of your own to manage.
- **Test locally** against `LocalMockHost`, a fake host that lets you drive
  and assert on agent/tool behavior entirely offline.
- **Build** a signed, versioned package manifest from your code.
- **Publish** to the Tenaxis Hub (or import straight into a kernel you
  control for local development) so others can discover and install it.

## Getting started

The fastest way in is [`examples/`](examples/) — three runnable,
heavily-commented examples, one per authoring surface (native agent, MCP
server, LangChain framework adapter). Each has its own tests you can run
immediately, no kernel or network required:

```bash
pip install -e ".[dev,mcp,langchain]"
pytest examples/minimal_text_agent/test_agent.py -v
```

See [`examples/README.md`](examples/README.md) for which one to start with.

## Documentation

Prose tutorials — go here once you know which capability you're building
and want more depth than the examples give:

- [Writing a native agent](docs/native_agent_tutorial.md)
- [Writing an MCP server](docs/mcp_server_tutorial.md)
- [Local testing with `LocalMockHost`](docs/local_testing.md)
- [Publishing and installing](docs/publish_and_install.md)
- [Runtime permission outcomes](docs/runtime_outcomes.md)

## What this contains

| Directory | Purpose |
|---|---|
| `src/tenaxisos_sdk/core/` | Manifest validation, JSON Schema loading, Ed25519 signing/verification |
| `src/tenaxisos_sdk/agents/` | `Agent`/`RunContext`/`Finding` authoring surface, manifest generation |
| `src/tenaxisos_sdk/host/` | The host-brokered contract (`Host` protocol, `ToolOutcome`) every agent runs against |
| `src/tenaxisos_sdk/testing/` | `LocalMockHost` — no-kernel local test host |
| `src/tenaxisos_sdk/tools/` | `Tool`/`MCPServer` authoring surface, MCP manifest generation, `[mcp]` extra for the real stdio protocol bridge |
| `src/tenaxisos_sdk/cli/` | The `tenaxis` CLI: `validate`, `build`, `sign`, `verify`, `test`, `publish`, `import`, `keygen`, `run`, `agent build`, `mcp init/test/build`, `workflow import` |
| `src/tenaxisos_sdk/runtime/adapters/` | Agent framework adapters (LangChain today, `[langchain]` optional extra) |
| `src/tenaxisos_sdk/importers/` | External-workflow importers (n8n today) used by `tenaxis workflow import` |

This package is **not yet published to PyPI** — install it from source
(below) in the meantime.

## Prerequisites

- **Python 3.11 or 3.12**.
- No database, no server, no `.env` file — the CLI is stateless and takes
  everything (hub URL, API keys, key paths) as command-line flags.

## Installation

```bash
python3 -m venv .venv && source .venv/bin/activate   # optional but recommended
pip install -e ".[dev]"     # editable install + pytest/ruff; drop [dev] for CLI-only use
tenaxis --help
```

Add `[langchain]` (e.g. `pip install -e ".[dev,langchain]"`) if you need the
LangChain agent adapter, or `[mcp]` if you need to run an MCP server as a
real stdio process — both are kept optional so the base SDK never requires
heavy adapter-specific dependencies.

## Everyday usage

```bash
tenaxis keygen                                        # once — generates an Ed25519 signing key pair
tenaxis validate <manifest.json>                       # schema + structural validation
tenaxis test <manifest.json>                           # runs the package's declared tests
tenaxis build <manifest-dir> --out <out.package.json>  # produces a distributable package artifact
tenaxis sign <manifest.json> --key <private-key-path>  # signing ceremony (human-reviewed, not run in CI)
tenaxis verify <manifest.json> --pubkey <public-key-b64> [--require]
tenaxis publish <manifest.json> --hub <hub-url> --api-key <publisher-api-key>
tenaxis import <n8n-export.json> --out <package-dir>   # n8n → native workflow package
```

`tenaxis keygen` writes your private signing key to disk (permissions locked
to owner-only) — keep it out of version control and treat it like any other
private key material; the CLI never transmits or stores it for you.

### Tests

```bash
pip install -e ".[dev]"
pytest tests/ -v
ruff check src/ tests/
```

## License

MIT — see [LICENSE](LICENSE).
