fabricium 0.1.1__tar.gz

fabricium-0.1.1/.env.example

@@ -0,0 +1,19 @@
+# Fabricium Integration Test Configuration
+# =========================================
+# Copy this file to .env and fill in your credentials.
+#
+# Required: provider + API key
+# Optional: model override (defaults to provider's cheapest model)
+
+# Provider name (deepseek, openrouter, anthropic, openai, google, ...)
+FABRICIUM_TEST_PROVIDER=deepseek
+
+# Model identifier (e.g. deepseek/deepseek-chat, openrouter/anthropic/claude-sonnet-4)
+FABRICIUM_TEST_MODEL=deepseek/deepseek-chat
+
+# API key for the provider above
+FABRICIUM_TEST_API_KEY=sk-your-key-here
+
+# ── Debug ───────────────────────────────────────────────────────────
+# Set to 1 to keep the Docker container after test failure (for inspection)
+# FABRICIUM_TEST_KEEP=1

fabricium-0.1.1/.github/workflows/ci.yml

@@ -0,0 +1,38 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  check:
+    name: Lint, type-check, and test
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Install dependencies
+        run: uv sync --dev
+
+      - name: Lint (ruff)
+        run: uv run ruff check .
+
+      - name: Format check (ruff)
+        run: uv run ruff format --check .
+
+      - name: Type check (mypy)
+        run: uv run mypy
+
+      - name: Run tests
+        run: uv run pytest -v --ignore=tests/integration/

fabricium-0.1.1/.github/workflows/release.yml

@@ -0,0 +1,80 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v[0-9]+.[0-9]+.[0-9]+'
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  build-and-publish:
+    name: Build, check, and publish to PyPI
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Install dependencies
+        run: uv sync --dev
+
+      - name: Lint (ruff)
+        run: uv run ruff check .
+
+      - name: Type check (mypy)
+        run: uv run mypy
+
+      - name: Run tests
+        run: uv run pytest --ignore=tests/integration/
+
+      - name: Extract version from tag
+        id: version
+        run: echo "version=${GITHUB_REF_NAME#v}" >> "$GITHUB_OUTPUT"
+
+      - name: Verify pyproject version matches tag
+        run: |
+          PYPROJECT_VERSION=$(uv run python -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          TAG_VERSION="${{ steps.version.outputs.version }}"
+          if [ "$PYPROJECT_VERSION" != "$TAG_VERSION" ]; then
+            echo "❌ pyproject.toml version ($PYPROJECT_VERSION) != tag version ($TAG_VERSION)"
+            exit 1
+          fi
+          echo "✅ Version $PYPROJECT_VERSION matches tag v$TAG_VERSION"
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/
+
+      - name: Generate changelog for release
+        id: changelog
+        run: |
+          VERSION="${{ steps.version.outputs.version }}"
+          # Extract the section for this version from CHANGELOG.md
+          CHANGELOG=$(awk "/^## \[${VERSION}\]/{found=1; next} /^## \[/{if(found) exit} found" CHANGELOG.md)
+          # Write to file for multiline support
+          echo "$CHANGELOG" > /tmp/changelog.md
+          echo "changelog_file=/tmp/changelog.md" >> "$GITHUB_OUTPUT"
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          name: "v${{ steps.version.outputs.version }}"
+          body_path: "${{ steps.changelog.outputs.changelog_file }}"
+          files: dist/*
+          draft: false
+          prerelease: false
+          generate_release_notes: false

fabricium-0.1.1/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.pyc
+.venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+*.egg-info/
+dist/
+eval_results/
+.env

fabricium-0.1.1/CHANGELOG.md

@@ -0,0 +1,43 @@
+# Changelog
+
+All notable changes to Fabricium will be documented in this file.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.1] — 2026-07-12
+
+### Changed
+
+- **PyPI publishing via OIDC Trusted Publishing** — no API token required; release workflow binds to the GitHub repo via PyPI's pending publisher
+
+## [0.1.0] — 2026-07-12
+
+### Added
+
+- **`HermesPlugin` class** — one-line plugin lifecycle registration: `setup`, `status`, `update`, `update --check`
+- **Single-profile and multi-profile modes** — `default_profile="my-profile"` or `default_profile=None`
+- **`fabricium.git_utils`** — Git subprocess wrappers: `fetch_remote`, `pull_branch`, `get_ahead_behind`, `get_diff`, `get_diff_stat`, `is_ancestor`, `stage_all`, `commit`, and more
+- **`fabricium.state`** — JSON state persistence: `load_state`, `save_state`, `set_profile_state`
+- **`fabricium.skills`** — Bundled skill lifecycle: `install_bundled_skills`, `remove_stale_skills`, `get_bundled_skill_names`
+- **`fabricium.prompts`** — TTY-aware prompt utilities: `prompt_yes_no`
+- **`fabricium.evals`** — Complete skill evaluation framework:
+  - `SkillEvalHarness` — Docker-based evaluation orchestrator
+  - `JudgeClient` — LLM-as-Judge with cross-provider support (Anthropic, OpenAI-compatible)
+  - `EvalConfig` — Environment-variable-driven configuration
+  - `EvalTask` / `RubricSpec` / `RubricDimension` / `ScoringBand` — task and rubric building blocks
+  - `calibrate()` — Judge-human agreement metrics (Cohen's κ, Spearman ρ)
+  - `JudgePrompt` — Customizable judge prompt templates
+  - Built-in example tasks and rubrics for Jovaltus evaluation
+  - Reasoning-model SSE proxy for DeepSeek V4 compatibility
+- **`fabricium.testing`** — Docker-based integration test environment:
+  - `HermesDockerTestEnv` — Disposable Hermes container for CLI testing
+  - `CliAssert` — Composable CLI output assertions
+  - `HermesConfig` — Provider/model configuration for test environments
+
+### Internals
+
+- 104 tests covering plugin lifecycle, git utilities, state persistence, skill management, and CLI assertions
+- ruff (E, F, I, N, W) + mypy `--strict` + pytest quality gates
+- MIT license
+- Conventional Commits history from initial extraction through eval pipeline refinements

fabricium-0.1.1/CONTRIBUTING.md

@@ -0,0 +1,132 @@
+# Contributing to Fabricium
+
+Thank you for your interest in contributing! Fabricium is the shared infrastructure for Hermes plugins — improvements here benefit every plugin in the ecosystem.
+
+## Development Setup
+
+```bash
+# Clone and enter the repo
+git clone https://github.com/LaiTszKin/fabricium.git
+cd fabricium
+
+# Install dev dependencies (pytest, ruff, mypy)
+uv sync --dev
+
+# Run the test suite (104 tests)
+uv run pytest
+
+# Lint and type-check
+uv run ruff check .
+uv run mypy
+```
+
+## Project Structure
+
+```
+fabricium/
+├── src/fabricium/
+│   ├── __init__.py          # HermesPlugin class
+│   ├── git_utils.py         # Git subprocess wrappers
+│   ├── state.py             # JSON state persistence
+│   ├── skills.py            # Bundled skill lifecycle
+│   ├── prompts.py           # TTY-aware prompts
+│   ├── evals/               # Skill evaluation framework
+│   │   ├── __init__.py
+│   │   ├── config.py        # EvalConfig (env-var driven)
+│   │   ├── harness.py       # SkillEvalHarness (Docker orchestrator)
+│   │   ├── judge.py         # JudgeClient (LLM-as-Judge)
+│   │   ├── tasks.py         # EvalTask dataclass
+│   │   ├── rubrics.py       # RubricSpec, RubricDimension, ScoringBand
+│   │   ├── runner.py        # CLI entry point
+│   │   ├── proxy.py         # Reasoning-model SSE proxy
+│   │   ├── example_tasks.py # Reference tasks for Jovaltus
+│   │   └── example_rubrics.py
+│   └── testing/             # Integration test environment
+│       ├── __init__.py
+│       ├── harness.py       # HermesDockerTestEnv
+│       ├── fixtures.py      # Pytest fixtures
+│       └── assertions.py    # CliAssert
+├── tests/
+│   ├── conftest.py
+│   ├── test_plugin.py
+│   ├── test_git_utils.py
+│   ├── test_state.py
+│   ├── test_skills.py
+│   ├── test_assertions.py
+│   └── integration/
+│       ├── conftest.py
+│       └── test_cli.py
+└── pyproject.toml
+```
+
+## Coding Standards
+
+### Python
+
+- **Style:** [ruff](https://docs.astral.sh/ruff/) with rules `E`, `F`, `I`, `N`, `W` (line length 100)
+- **Types:** [mypy](https://mypy-lang.org/) with `--strict`
+- **Tests:** [pytest](https://docs.pytest.org/) — aim for coverage on new code
+- **Formatting:** ruff handles import sorting and formatting
+
+Before committing:
+
+```bash
+uv run ruff check .          # Must pass
+uv run ruff format --check . # Must be clean
+uv run mypy                  # Must pass with --strict
+uv run pytest                # All 104 tests must pass
+```
+
+### Commit Messages
+
+Follow [Conventional Commits](https://www.conventionalcommits.org/):
+
+```
+type(scope): description
+
+- feat(evals): add parallel task execution
+- fix(state): handle empty profiles in load_state
+- refactor(plugin): extract profile helpers
+- docs(readme): add eval quick start
+```
+
+Types: `feat`, `fix`, `refactor`, `docs`, `test`, `chore`, `ci`.
+
+## Pull Request Process
+
+1. **Open an issue first** for significant changes — discuss the design before writing code
+2. **Branch from `main`** — use a descriptive branch name (`feat/eval-parallel`, `fix/state-empty-profiles`)
+3. **Keep PRs focused** — one logical change per PR. If you find a pre-existing issue, open a separate PR
+4. **Include tests** — new features need tests; bug fixes should include a regression test
+5. **Update docs** — if you add/change public API, update README.md
+6. **All checks must pass** — ruff, mypy, and pytest are required
+
+## Design Principles
+
+When contributing, keep these in mind:
+
+1. **Extract only what's actually shared.** Code goes into Fabricium only when at least two plugins need it.
+2. **Convention over configuration.** Sensible defaults. 99% of plugins shouldn't need options.
+3. **Library, not framework.** Plugins import Fabricium — Fabricium doesn't control them.
+4. **Zero runtime dependencies.** Fabricium uses only the Python standard library at runtime.
+5. **Backward compatibility.** Existing plugins must not break on upgrade.
+6. **TTY-safe by default.** Interactive prompts fall back to safe defaults when stdin is not a TTY.
+
+## Running Integration Tests
+
+Integration tests require Docker and a Hermes agent image:
+
+```bash
+# Pull the Hermes image (one-time)
+docker pull nousresearch/hermes-agent:latest
+
+# Run integration tests
+uv run pytest tests/integration/ -v
+
+# Skip integration tests in CI where Docker isn't available
+uv run pytest tests/ --ignore=tests/integration/
+```
+
+## Questions?
+
+Open a [GitHub Discussion](https://github.com/LaiTszKin/fabricium/discussions) or file an issue. We're happy to help!

fabricium-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lai Tsz Kin
+
+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.

fabricium-0.1.1/PKG-INFO

@@ -0,0 +1,8 @@
+Metadata-Version: 2.4
+Name: fabricium
+Version: 0.1.1
+Summary: Fabricium — Shared Hermes plugin infrastructure (CLI lifecycle, bundled skills, Git self-update, state persistence)
+Author-email: LaiTszKin <laitszkin1206@gmail.com>
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.10