Metadata-Version: 2.4
Name: dsh-python-bridge
Version: 0.0.1
Summary: Python decorator library and runtime that exposes a Python module as a Cordis Service / Event listener / capability Provider through the DeepSeek Harness Python Capability Bridge
Project-URL: Homepage, https://github.com/deepseek-ai/deepseek-harness
Project-URL: Documentation, https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/subsystems/python-bridge.md
Project-URL: Issues, https://github.com/deepseek-ai/deepseek-harness/issues
Project-URL: Source, https://github.com/deepseek-ai/deepseek-harness
Author: DeepSeek
License-Expression: MIT
Keywords: agent,bridge,cordis,deepseek,deepseek-harness,json-rpc,plugin
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# dsh-python-bridge

English | [中文](README.zh.md)

Python decorator library and runtime that exposes a Python module as a Cordis Service Provider, Tool Consumer, Event Listener, or capability seam Provider through the DeepSeek Harness Python Capability Bridge. Decorators are zero-side-effect at import time; the runtime is `python -u -m dsh_bridge.runtime <module>` and serves newline-delimited JSON-RPC 2.0 over stdio (matching `@deepseek-ai/dsh-sdk-protocol` `JsonRpcLineTransport`).

## Installation

```sh
pip install dsh-python-bridge
```

## Decorators

| Decorator | Purpose |
| --- | --- |
| `@service(name, settings_namespace=None)` | Class decorator; marks a class as a `ctx.<name>` Service Provider |
| `@provide_method(timeout_ms=None, is_concurrency_safe=None)` | Method decorator inside `@service`; each decorated method becomes a public TS method |
| `@tool(name, description, parameters, output_schema=None, timeout_ms=None)` | Function decorator; becomes `ctx.tools.register(defineTool({...}))` |
| `@on(event_name, mode='emit', prepend=False, global_=False)` | Function decorator; becomes `ctx.on(...)` |
| `@capability(seam, backend)` | Class decorator; replaces a capability seam provider |
| `@method(name=None)` | Method decorator inside `@capability` |
| `@system_prompt_section(order, text)` | Function decorator; registers a prompt section |
| `@guard()` | Function decorator; registers as a tool guard |
| `@restrict_tools(allow=None, deny=None)` | Method decorator; per-agent tool restriction |

Each decorator returns the original callable (or class) unchanged — Python business code is unmodified at runtime.

## Runtime

```sh
python -u -m dsh_bridge.runtime <module.path> [--class <ClassName>] [--function <func>]...
```

The runtime walks the bridge registry and dispatches JSON-RPC requests to the matching Python callables. Errors map to the JSON-RPC error vocabulary in `dsh_bridge._errors` (`-32001`/`timeout`, `-32003`/`permission`, etc.).

### Runtime manifest

The `initialize` handshake returns `serverInfo` plus a `manifest` carrying every dynamically registered surface with the metadata a host needs to build the plugin without codegen. The client sends `clientInfo: { name, version }`; a client whose major version differs from the runtime's `serverInfo.version` is rejected with a `protocol-mismatch` error (wire version negotiation).

- `tools[]` — `name`, `description`, `parameters` (JSON Schema), `outputSchema`
- `provideMethods[]` — `name`, `timeoutMs`, `concurrencySafe`, `parameters` (PEP 484 annotation strings), `return`
- `services[]` — `name`, `class`, `initFields` (dataclass field name/annotation/default)
- `listeners[]` — `event`, `mode`, `prepend`, `global`, `function`

The full schema is documented in [`skill/dsh-python-plugin/references/manifest.md`](../../skill/dsh-python-plugin/references/manifest.md) in the bridge repository.

## Test

```sh
pip install -e .[test]
pytest
```

## Release

Publishing is a GitHub Actions workflow (`.github/workflows/publish-pypi.yml`): `pytest` runs across supported Python versions, the wheel builds and smoke-tests, and a pushed `v*` tag publishes to PyPI via trusted publishing (OIDC). Until the PyPI publisher is configured, cut the first release manually from a local build:

```sh
cd python/sdk-dsl
python -m pip install build twine
python -m build --outdir dist
twine upload dist/*
```

## License

MIT.
