Metadata-Version: 2.4
Name: hermes-cluxion
Version: 0.1.3
Summary: Hermes Agent plugin for Cluxion runtime planning, local model endpoints, and resource-aware harness handoff.
Project-URL: Homepage, https://github.com/cluxion/hermes-cluxion
Project-URL: Repository, https://github.com/cluxion/hermes-cluxion
Project-URL: Issues, https://github.com/cluxion/hermes-cluxion/issues
Author-email: cluxion <algocean1204@users.noreply.github.com>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: ai-agent,cluxion,hermes-agent,local-llm,plugin,vllm-mlx
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Plugins
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: psutil>=5.9
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.8; extra == 'dev'
Requires-Dist: twine>=6.0; extra == 'dev'
Provides-Extra: mlx
Requires-Dist: vllm-mlx>=0.3.0; extra == 'mlx'
Description-Content-Type: text/markdown

# hermes-cluxion

Hermes Agent plugin for Cluxion runtime planning, local model endpoint setup, and resource-aware harness handoff.

`hermes-cluxion` is intentionally separate from the old monolithic runtime. The package ships a light Hermes plugin and the `cluxion-runtime` CLI needed by that plugin.

## What This Plugin Does

- Registers `cluxion_plan` in Hermes.
- Registers `cluxion_bootstrap` in Hermes.
- Registers `cluxion_serve_local` for Cluxion-managed local vLLM-MLX endpoints.
- Registers `cluxion_hermes_config` to render Hermes `custom:cluxion-local` config.
- Keeps Hermes OAuth providers such as `xai-oauth`, `openai-codex`, and Anthropic under Hermes control.
- Uses `cluxion-runtime` as the stable harness boundary, preferring the console command and falling back to the bundled Python runtime for Git-installed plugins.

## Install

Install from PyPI if you want Python entry point discovery and the `cluxion-runtime` CLI:

```bash
python -m pip install "hermes-cluxion==0.1.3"
```

The PyPI package must be installed into the same Python environment that runs `hermes`.
After installing the package, enable the discovered plugin:

```bash
hermes-cluxion enable
```

Install from GitHub if you want Hermes to manage the plugin directory:

```bash
hermes plugins install cluxion/hermes-cluxion --enable
```

Install MLX runtime immediately if you do not want first-use bootstrap:

```bash
python -m pip install "hermes-cluxion[mlx]==0.1.3"
```

Check that Hermes can see the runtime command:

```bash
hermes-cluxion check
```

Hermes plugins are opt-in by design. The package exposes the `hermes_agent.plugins`
entry point named `hermes-cluxion`, but Hermes only loads third-party plugins after the user enables them.
Hermes v0.16 can load pip entry point plugins, but its `hermes plugins enable` command only recognizes directory-installed plugins. Use `hermes-cluxion enable` for PyPI installs.

## Runtime Bootstrap

Dry-run the local runtime install plan:

```bash
hermes-cluxion bootstrap --dry-run
```

Install or upgrade to the latest available `vllm-mlx`:

```bash
hermes-cluxion bootstrap --upgrade
```

`cluxion-runtime serve-local` also checks local runtime dependencies before starting. Use `--no-auto-install` to disable that behavior.
By default, heavy local runtime dependencies such as `vllm-mlx` are installed into an isolated managed venv at `~/.local/share/hermes-cluxion/runtime-venv`, not into the Hermes Agent venv.

## Local Model Flow

Prepare the Hermes config patch:

```bash
hermes-cluxion hermes-config \
  --model mlx-community/Qwen3.6-35B-A3B-OptiQ-4bit \
  --port 23003 \
  --context-length 131072
```

Start the local endpoint:

```bash
cluxion-runtime serve-local \
  --model mlx-community/Qwen3.6-35B-A3B-OptiQ-4bit \
  --port 23003 \
  --upgrade-runtime
```

Use `--dry-run` first if you only want to inspect the server command without starting the model:

```bash
cluxion-runtime serve-local \
  --model mlx-community/Qwen3.6-35B-A3B-OptiQ-4bit \
  --port 23003 \
  --dry-run
```

Then switch the Hermes session to:

```text
/model custom:cluxion-local:mlx-community/Qwen3.6-35B-A3B-OptiQ-4bit
```

## Release

This repository is configured for PyPI Trusted Publishing.

1. In PyPI account settings, create a pending Trusted Publisher for project `hermes-cluxion`.
2. Set owner/repository to `cluxion/hermes-cluxion`.
3. Set workflow file to `.github/workflows/publish.yml`.
4. Set environment to `pypi`.
5. Create a GitHub Release.
6. The workflow builds, checks, creates the PyPI project on first use, and publishes `hermes-cluxion` automatically without a PyPI token.

Expected Trusted Publisher claims:

```text
repository: cluxion/hermes-cluxion
workflow: .github/workflows/publish.yml
environment: pypi
```

## Hermes v0.16 PyPI Enablement

For pip-installed plugins:

```bash
python -m pip install "hermes-cluxion==0.1.3"
hermes-cluxion enable
hermes-cluxion status
```

The enable command updates `~/.hermes/config.yaml`, creates a timestamped backup if the file already exists, appends `hermes-cluxion` to `plugins.enabled`, and removes it from `plugins.disabled`.

## Docs

Detailed architecture, harness logic, install operations, and security notes live in [`cluxion-Docs`](./cluxion-Docs).

## License

Apache-2.0.
