witsoc 0.1.4

Witsoc mathematical research orchestration utilities

Witsoc

Witsoc is a collection of mathematical research orchestration utilities used by the Witsoc skill. The package exposes the same command surface as the local scripts/witsoc.py entrypoint while making the tools installable with pip.

Initial package scope:

• stable witsoc console command;
• compatibility with existing script names and orchestrator calls;
• packaged references, schemas, and subskill files needed by the scripts;
• gradual migration path from standalone scripts to importable modules.

PyPI package:

https://pypi.org/project/witsoc/

If the local Witsoc script tree is missing in a fresh environment, install from PyPI:

python3 -m pip install -U witsoc

or:

uv pip install -U witsoc

The canonical OpenScientist skill directory is:

~/.openscientist/skills/witsoc

If that skill folder exists but scripts/ and/or src/ were deleted, restore them into that folder from the installed PyPI package:

python3 -m pip install -U witsoc
python3 -m witsoc restore-skill --target ~/.openscientist/skills/witsoc --replace

Or from a surviving bootstrap.py inside the skill folder:

python3 ~/.openscientist/skills/witsoc/bootstrap.py --replace

Check without changing files:

python3 -m witsoc restore-skill --target ~/.openscientist/skills/witsoc --check
python3 ~/.openscientist/skills/witsoc/bootstrap.py --check

Force a refresh from PyPI:

python3 -m witsoc restore-skill --target ~/.openscientist/skills/witsoc --replace
python3 ~/.openscientist/skills/witsoc/bootstrap.py --replace

Restore an explicit target:

python3 -m witsoc restore-skill --target ~/.openscientist/skills/witsoc --replace
python3 ~/.openscientist/skills/witsoc/bootstrap.py --replace

Fresh-machine setup without checking in scripts/:

python3 -m pip install -U witsoc
mkdir -p ~/.openscientist/skills/witsoc
python3 -m witsoc restore-skill --target ~/.openscientist/skills/witsoc
python3 ~/.openscientist/skills/witsoc/scripts/witsoc.py --help

Runtime Preflight

Before using Witsoc scripts from a skill folder, verify:

test -f ~/.openscientist/skills/witsoc/scripts/witsoc.py
test -f ~/.openscientist/skills/witsoc/src/witsoc/cli.py

If either check fails:

python3 ~/.openscientist/skills/witsoc/bootstrap.py --replace

The safest local launcher is:

python3 ~/.openscientist/skills/witsoc/witsoc.py --help

It checks scripts/ and src/, restores them through bootstrap.py if they are missing, and then delegates to scripts/witsoc.py.

Example:

witsoc route "deep run prove or disprove this open conjecture"
witsoc lovasz-packet runs/example
witsoc orchestrator-plan route "prove a theorem"

Nested aliases are also available:

witsoc strategy rank-lanes --prompt "deep run prove or disprove this open conjecture"
witsoc lovasz packet runs/example

Lazy Surface

Witsoc is intentionally lazy at the package boundary. The default command surface exposes cheap routing and decision packets first; heavy research engines remain callable by explicit command name or by the orchestrator after it chooses a plan.

Cheap boundary calls:

python3 ~/.openscientist/skills/witsoc/witsoc.py llm-contract
python3 ~/.openscientist/skills/witsoc/witsoc.py subskills
python3 ~/.openscientist/skills/witsoc/witsoc.py spawn-template explorer --target "..."
witsoc route "..."
witsoc orchestrator-plan route "..."
witsoc strategy rank-lanes --prompt "..."
witsoc lovasz packet runs/example

Discover commands by tier:

witsoc commands
witsoc commands --tier core
witsoc commands --tier heavy --json
witsoc install-help

Old direct aliases still work for compatibility, for example:

witsoc counterexample-search runs/example
witsoc worker-dispatch runs/example --write

Those commands are not imported or loaded until invoked.

Build

From this directory:

uv build

This produces:

dist/witsoc-0.1.4.tar.gz
dist/witsoc-0.1.4-py3-none-any.whl

Local wheel smoke test:

python3 -m venv /tmp/witsoc-venv
/tmp/witsoc-venv/bin/pip install --no-deps dist/witsoc-0.1.4-py3-none-any.whl
/tmp/witsoc-venv/bin/witsoc route --field route "deep run prove or disprove this open conjecture"

Publish, after configuring PyPI credentials:

uv publish

Migration Model

Version 0.1.4 packages the existing scripts/ tree as the compatibility surface. The stable entrypoint is witsoc.cli:main; old calls through scripts/witsoc.py delegate to the package CLI. Future releases can move individual scripts into importable package modules while keeping the same console commands.