Metadata-Version: 2.1
Name: ruleforge-python
Version: 0.1.2
Summary: Python SDK for Ruleforge policy CLI orchestration and alert integrations.
Home-page: UNKNOWN
Author: Ruleforge Maintainers
License: Proprietary
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3
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: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Intended Audience :: Information Technology
Classifier: Topic :: Security
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: THIRD_PARTY_NOTICES.md
Provides-Extra: dev
Requires-Dist: pytest-asyncio (>=0.21) ; extra == 'dev'
Requires-Dist: pytest (>=7.4) ; extra == 'dev'

# Ruleforge Python SDK

`ruleforge-python` is a cross-platform Python SDK for running Ruleforge
policies through the existing `policy` executable.

It provides:
- High-level managed service APIs with restart supervision.
- Low-level wrappers for `run`, `serve`, `test`, `fmt`, and `bundle`.
- Typed alert parsing from JSONL output.
- Pluggable alert sinks with optional disk-backed retry queue.

Supported wheel platforms (v1):
- Windows `x86_64`
- Linux `manylinux2014_x86_64`
- Linux `manylinux2014_aarch64`

Note: Windows connectors (`winlog`, `evtx`) remain Windows-only CLI features.

## Install

```bash
pip install ruleforge-python
```

## Quick Start (High Level)

```python
from ruleforge.service import RuleforgeService
from ruleforge.sinks import StdoutSink

svc = RuleforgeService.from_sources_config(
    sources_config="/opt/ruleforge/config/sources.live.json",
    sources_status="/opt/ruleforge/state/ruleforge.sources.status.json",
    sinks=[StdoutSink()],
)

svc.start()
try:
    for alert in svc.iter_alerts():
        print(alert.rule, alert.severity, alert.emit)
finally:
    svc.stop()
    svc.wait()
```

## Quick Start (Low Level)

```python
from ruleforge.cli import run

result = run(
    rules="examples/rules.dsl",
    schema="examples/schema.json",
    input_path="examples/events.jsonl",
)

print("exit:", result.exit_code)
print("alerts:", len(result.alerts))
```

## Binary Resolution

By default the SDK resolves `policy` in this order:
1. Explicit `policy_path=` argument.
2. `RULEFORGE_POLICY_PATH` environment variable.
3. Embedded packaged binary (`ruleforge/bin/policy.exe` on Windows, `ruleforge/bin/policy` on Linux).
4. `PATH` lookup (platform-specific names).

If no executable is found, an actionable `BinaryResolutionError` is raised.

## Packaging Note

Build artifacts (wheel only):

```bash
python python/scripts/build_release_artifacts.py \
  --policy-binary-path <path-to-policy-binary> \
  --output-root <cmake-build>/python_package/<config> \
  --clean-dist \
  --skip-tests
```

Or use the CMake target:

```bash
cmake --build cmake-build-debug --config Debug --target package_ruleforge_python
```

Output location for the CMake target:

`cmake-build-debug/python_package/Debug/dist`

Stage a profile wheel into the shared release folder:

```bash
cmake --build cmake-build-debug --config Debug --target stage_ruleforge_python_wheel
```

Default staged release folder:

`release/python/<RULEFORGE_VERSION>`

Verify staged multi-platform bundle before upload:

```bash
cmake --build cmake-build-debug --config Debug --target verify_ruleforge_python_release
```

Manual publish flow (TestPyPI first):

```bash
python -m twine upload --repository-url https://test.pypi.org/legacy/ release/python/<version>/*.whl
python -m twine upload release/python/<version>/*.whl
```

Use API-token auth for uploads:
- `TWINE_USERNAME=__token__`
- `TWINE_PASSWORD=<token>`

The packaging flow stages files in a build-only folder and does not modify
`python/src/ruleforge/bin`.

## Windows Notifier Pack

The Windows notifier deployment assets are intentionally not shipped inside the
Python wheel. Use the canonical pack under:

`examples/windows_bad_event_notifier`

## License

- Package/project license: `LICENSE` (proprietary).
- Third-party notices: `THIRD_PARTY_NOTICES.md`.


