witsoc 0.1.1

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:

pip install witsoc

or:

uv pip install 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:

pip install -U witsoc
witsoc restore-skill

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

python3 bootstrap.py

Check without changing files:

witsoc restore-skill --check
python3 bootstrap.py --check

Force a refresh from PyPI:

witsoc restore-skill --replace
python3 bootstrap.py --replace

Restore an explicit target:

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

Fresh-machine setup without checking in scripts/:

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

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:

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.1.tar.gz
dist/witsoc-0.1.1-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.1-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.1 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.