hemisphere-harness 0.1.0__tar.gz

hemisphere_harness-0.1.0/.env.example

@@ -0,0 +1,87 @@
+# Copy to .env. Everything is optional: with nothing set, the example runs offline.
+# `python -m hemisphere_harness` lists the providers you can name below.
+
+# --- Right hemisphere (the Master) ------------------------------------------------------
+# Setting RIGHT_MODEL is what switches the right hemisphere from the offline script to a
+# live LLM. Pick a strong, long-context model: this is the part that holds the whole picture.
+#
+#   RIGHT_PROVIDER      endpoint                                 key variable
+#   openai (default)    https://api.openai.com/v1                OPENAI_API_KEY
+#   nvidia              https://integrate.api.nvidia.com/v1      NVIDIA_API_KEY
+#   xai, grok           https://api.x.ai/v1                      XAI_API_KEY
+#   openrouter          https://openrouter.ai/api/v1             OPENROUTER_API_KEY
+#   ollama              http://localhost:11434/v1                none
+#   lmstudio            http://localhost:1234/v1                 none
+#   vllm                http://localhost:8000/v1                 none
+#   llamacpp            http://localhost:8080/v1                 none
+#   openai-compatible   set RIGHT_BASE_URL                       RIGHT_API_KEY, if needed
+RIGHT_PROVIDER=openai
+RIGHT_MODEL=
+
+# The key for the provider you chose. A provider's key is sent only to its own endpoint.
+OPENAI_API_KEY=
+# NVIDIA_API_KEY=
+# XAI_API_KEY=
+# OPENROUTER_API_KEY=
+
+# Override the provider's endpoint, for a proxy or a self-hosted server:
+# RIGHT_BASE_URL=http://localhost:8000/v1
+# Override the provider's key variable. This one is sent to whichever endpoint is in use:
+# RIGHT_API_KEY=
+
+# RIGHT_TIMEOUT_S=120
+# Unset by default, because some models reject the parameter:
+# RIGHT_TEMPERATURE=0.2
+# true also sends response_format={"type": "json_object"}. Helps small local models:
+# RIGHT_JSON_MODE=false
+
+# --- Left hemisphere (the Emissary) -----------------------------------------------------
+#   LEFT_PROVIDER       what it is                                         needs
+#   auto (default)      jev if JEV_API_KEY is set, otherwise mock
+#   jev                 TypeSafe AI's hosted Jev                           JEV_API_KEY
+#   ollama              a decision model served by Ollama, locally         LEFT_MODEL
+#   systemone           any other server implementing /v1/systemone        LEFT_BASE_URL, LEFT_MODEL
+#   llm-experimental    EXPERIMENTAL: a chat model, not calibrated         LEFT_MODEL
+#   mock                offline stand-in for development
+# LEFT_PROVIDER=auto
+
+# TypeSafe's hosted Jev. Keys: https://console.typesafe.ai/keys
+JEV_API_KEY=
+# The client appends /v1/systemone to the base URL:
+# JEV_BASE_URL=https://api.typesafe.ai
+# JEV_MODEL=jev-latest
+# JEV_TIMEOUT_S=10
+# TypeSafe's own names are accepted too: TYPESAFE_API_KEY, TYPESAFE_BASE_URL,
+# TYPESAFE_DEFAULT_MODEL.
+
+# A local decision model through Ollama. `ollama show <model>` must list "decision".
+# LEFT_PROVIDER=ollama
+# LEFT_MODEL=tev1
+
+# For ollama, systemone and llm-experimental:
+# LEFT_BASE_URL=http://localhost:11434
+# LEFT_API_KEY=
+# The first call may have to load the model, so the default is generous:
+# LEFT_TIMEOUT_S=120
+# llm-experimental only. "none" stops a reasoning model thinking before it answers;
+# "omit" leaves the parameter out for servers that reject it:
+# LEFT_REASONING_EFFORT=none
+
+# --- The loop ---------------------------------------------------------------------------
+# Minimum probability of the left's pick for the left to commit on its own:
+# HARNESS_COMMIT_THRESHOLD=0.8
+# Policy gate: at or above this, an option is allowed without sign-off:
+# HARNESS_PERMIT_YES_THRESHOLD=0.7
+# Policy gate: at or below this, only a human can approve an option:
+# HARNESS_PERMIT_NO_THRESHOLD=0.3
+# HARNESS_MAX_STEPS=6
+# Operator policy in plain language. Leave unset to disable the gate:
+# HARNESS_POLICY=Refunds above $500 need human sign-off.
+# Before the answer is shown, the left checks its factual claims and the right revises
+# any that do not hold. Skipped when the left is the mock:
+# HARNESS_CHECK_ANSWERS=true
+
+# --- Web UI (hemisphere-harness web) ----------------------------------------------------
+# The UI reads and writes this file. Without this, a new sign-in token is made at every
+# start. Read from the shell only, not from this file:
+# HARNESS_WEB_TOKEN=

hemisphere_harness-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,45 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+          cache-dependency-path: pyproject.toml
+
+      - name: Install
+        run: python -m pip install -e ".[dev]"
+
+      - name: Tests
+        run: python -m pytest -q
+
+      - name: Types
+        run: python -m mypy --strict src
+
+      # With nothing configured the example runs offline, so this needs no secrets.
+      - name: Offline example
+        run: python -m hemisphere_harness.examples.simple_loop

hemisphere_harness-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,62 @@
+name: Publish to PyPI
+
+# Runs when a release is published on GitHub. Uploads use PyPI's trusted publishing, so no
+# PyPI token is stored anywhere. The upload job runs in the "pypi" environment, which can
+# require an approval before anything is published.
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions: {}
+
+jobs:
+  build:
+    name: Build and check
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+
+      - name: The release tag matches the package version
+        if: github.event_name == 'release'
+        run: |
+          version=$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml', 'rb'))['project']['version'])")
+          if [ "${GITHUB_REF_NAME}" != "v${version}" ]; then
+            echo "Release tag ${GITHUB_REF_NAME} does not match version ${version} in pyproject.toml" >&2
+            exit 1
+          fi
+
+      - name: Build
+        run: |
+          python -m pip install build twine
+          python -m build
+          python -m twine check --strict dist/*
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Upload to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/hemisphere-harness/
+    permissions:
+      id-token: write  # trusted publishing: PyPI checks this workflow's identity, no token needed
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - uses: pypa/gh-action-pypi-publish@release/v1

hemisphere_harness-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+.env
+.hemisphere/
+.venv/
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+dist/
+build/
+.mypy_cache/

hemisphere_harness-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,71 @@
+# Contributing
+
+## Setup
+
+```bash
+python -m venv .venv && source .venv/bin/activate    # or: uv venv && source .venv/bin/activate
+pip install -e ".[dev]"                               # or: uv pip install -e ".[dev]"
+
+pytest
+python -m hemisphere_harness.examples.simple_loop     # the offline demo
+python -m hemisphere_harness                          # lists providers
+hemisphere-harness web                                # the web UI
+```
+
+The web UI's page is plain HTML, CSS and JavaScript in `src/hemisphere_harness/web/static/`,
+with no build step and no dependencies. Edit and reload. Insert anything a model or a
+user wrote with `textContent`, never `innerHTML`, and keep everything loaded from the
+server itself, because the Content-Security-Policy allows nothing else.
+
+The test suite makes no network calls and needs no credentials. Please keep it that way:
+test HTTP clients against `httpx.MockTransport`, as `tests/test_jev_client.py` and
+`tests/test_right_openai_compatible.py` do.
+
+Types are checked with `mypy --strict src`. CI runs the tests, the type check and the
+offline example on Python 3.11 to 3.14 for every pull request, so run them locally first.
+
+## Adding a provider
+
+This is the most useful kind of contribution, and usually the smallest.
+[docs/providers.md](docs/providers.md) has the full guide. In short:
+
+- **An OpenAI-compatible service** is one line in `src/hemisphere_harness/providers.py`,
+  one table row, and one test parameter.
+- **A service with its own API** is a subclass of `LLMRightHemisphere` with one method,
+  `complete`.
+- **A provider that pulls in a heavy SDK** is better as its own package, published with
+  an entry point, so that this package keeps its short list of small dependencies.
+
+## What the design protects
+
+The project is small on purpose, and its point is a specific relationship between two
+parts. Changes are easy to accept when they keep these true, and need a good argument
+when they do not. [docs/architecture.md](docs/architecture.md) says where each one is
+enforced.
+
+1. Only the right hemisphere generates. The left returns typed answers and nothing else.
+2. The left commits only a routine, low-stakes decision that it is sure of.
+3. Everything else returns to the right before anything is done.
+4. An operator's policy binds both hemispheres.
+5. Every step ends with the right reintegrating it.
+6. A failing left hemisphere is survivable. A failing right hemisphere is not.
+
+Two practical consequences:
+
+- A feature that lets the left act on more than it does today needs a test showing what
+  still stops it.
+- The harness reads the left's probabilities as calibrated. A left-hemisphere provider
+  whose numbers are not must say so.
+
+## Licence
+
+The project is MIT licensed. By contributing you agree that your contribution is
+released under the same licence.
+
+## Pull requests
+
+- Add or update tests for what you change. For a rule in the list above, check that the
+  test fails when the rule is broken.
+- Keep provider-specific knowledge in the provider's own module. `harness.py` and
+  `schemas.py` should not learn any provider's name.
+- Update `README.md`, `docs/` and `.env.example` when behaviour or configuration changes.

hemisphere_harness-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zaenus
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+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 NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.