Metadata-Version: 2.4
Name: hermes-cluxion
Version: 0.1.0
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
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 `cluxion-os`. 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_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[mlx]"
```

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

```bash
hermes plugins enable hermes-cluxion
```

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

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

For GitHub installs, `cluxion-runtime` falls back to the bundled Python runtime inside the plugin source tree. Install `vllm-mlx` separately if you want to start real local MLX servers:

```bash
python -m pip install "vllm-mlx>=0.3.0"
```

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.

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

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.

## License

Apache-2.0.
