Metadata-Version: 2.2
Name: ruleforge-python
Version: 0.1.2
Summary: Python SDK for Ruleforge policy CLI orchestration and alert integrations.
Author: Ruleforge Maintainers
License: Ruleforge Proprietary License
        Version 1.0
        
        Copyright (c) 2026 Ruleforge Maintainers. All rights reserved.
        
        1. Grant of Rights
        Subject to the terms of this license, Ruleforge Maintainers grant you a
        limited, non-exclusive, non-transferable, revocable license to use the
        software for internal evaluation and internal business purposes.
        
        2. Restrictions
        You may not, without prior written permission from Ruleforge Maintainers:
        - redistribute, sublicense, sell, lease, or commercially host the software;
        - provide the software to third parties as a managed service;
        - remove, alter, or obscure proprietary notices;
        - use trademarks, names, or logos of Ruleforge Maintainers.
        
        3. Ownership
        The software and all related intellectual property rights are and remain the
        exclusive property of Ruleforge Maintainers and their licensors.
        
        4. Third-Party Components
        The software includes third-party components licensed by their respective
        owners. See THIRD_PARTY_NOTICES.md for required attributions and license terms.
        
        5. No Warranty
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT.
        
        6. Limitation of Liability
        TO THE MAXIMUM EXTENT PERMITTED BY LAW, IN NO EVENT SHALL RULEFORGE MAINTAINERS
        OR CONTRIBUTORS BE LIABLE FOR ANY INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
        CONSEQUENTIAL DAMAGES, OR ANY LOSS OF DATA, USE, BUSINESS, OR PROFITS.
        
        7. Termination
        This license terminates automatically if you fail to comply with its terms.
        Upon termination, you must stop use of the software and destroy all copies.
        
        8. Contact
        For commercial, redistribution, OEM, or managed-service licensing, contact the
        copyright owner/maintainers.
        
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>=7.4; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
Dynamic: requires-python

# 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`.
