Metadata-Version: 2.4
Name: yacs-python
Version: 0.1.0a2
Summary: Thin Python client for the licensed YACS desktop engine
Author: David Pahl and Lukas Pahl
License-Expression: MIT
Project-URL: Homepage, https://yacs.studio
Project-URL: Repository, https://github.com/David-Pahl/yacs-python
Project-URL: Issues, https://github.com/David-Pahl/yacs-python/issues
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3 :: Only
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: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# yacs-python

`yacs-python` is the small, dependency-free Python interface to the licensed
YACS desktop engine. It provides secure local discovery, background-job
helpers, and a command-line interface. It contains no circuit solver or other
proprietary YACS implementation code.

## Install

Install into the Python environment that will automate YACS:

```bash
python -m pip install yacs-python
```

YACS Desktop must be installed and have a valid license. Installing this
package does not install or unlock the solver.

## Python API

```python
from yacs_python import Desktop

with Desktop.connect() as yacs:
    result = yacs.analyze(circuit, analysis)
```

Long-running operations can be managed explicitly:

```python
with Desktop.connect() as yacs:
    job = yacs.analyze(circuit, analysis, wait=False)
    print(job.status())
    result = job.result()
```

For large results, `job.download("result.json")` streams to a temporary file,
verifies the engine-provided SHA-256 digest, and only then atomically replaces
the destination.

## CLI

```bash
yacs status
yacs analyze request.json --output result.json
yacs run refine_roots request.json --output roots.json
```

The v1 API accepts normalized JSON request objects. Complete `.yacs` workspace
parsing remains engine-owned so client releases do not duplicate private or
rapidly evolving desktop normalization rules.

## Security boundary

The client connects only to numeric loopback addresses discovered through a
private per-session descriptor. It rejects redirects, bypasses system HTTP
proxies, verifies the engine instance handshake, and receives a scoped token
that cannot access desktop or licensing-control endpoints.

The descriptor is a short-lived capability available to processes running as
the same operating-system user. Do not copy or publish it.

## Compatibility

Client releases are versioned independently from YACS Desktop. This release
supports YACS Desktop Automation API v1.

Development and managed-installation overrides:

- `YACS_APP_PATH`
- `YACS_CONNECTION_FILE`
- `YACS_AUTOMATION_SESSION_DIR`

## License

The client is MIT licensed. YACS Desktop and its numerical engine are separate
products governed by their own license terms.
