Metasci

Metasci is a research harness for scientific experimentation and discovery. It provides a portable CLI control plane for objectives, hypotheses, experiment specs, evidence, verification, artifacts, and human feedback across repositories.

Status

This repository contains the first Python package skeleton:

• metasci init creates a per-repository .metasci/ capsule.
• metasci objective create records project objectives.
• metasci experiment spec records versioned experiment specifications.
• metasci experiment run records runs and locks spec content.
• metasci evidence add records evidence with provenance and verification status.
• metasci verifier record records verifier outcomes and metrics.
• metasci verifier define writes local verifier command definitions.
• metasci report export writes a local markdown project summary.
• metasci queue add-experiment, metasci queue add-agent, and metasci queue run persist and process local work.
• metasci agent list detects known local CLI adapters.
• metasci state summarizes local project state.
• metasci verify runs local consistency checks.
• metasci agent run exercises the adapter boundary. External CLI execution is opt-in with --execute.

Development

uv sync --dev
uv run pytest
uv run ruff check .
uv run mypy src

Local Verifiers

Verifier definitions live under .metasci/verifiers/ as JSON files. Commands are stored as argument arrays, not shell strings.

metasci verifier define python-tests \
  --command python \
  --command -m \
  --command pytest
metasci verify --verifier python-tests

Queue

The local queue is stored in SQLite and can be resumed after process exit.

metasci queue add-agent "Summarize current evidence" --adapter dry_run
metasci queue list
metasci queue run

Install

After the first PyPI release:

uvx metasci --help
uv add --dev metasci
pip install metasci

For local development:

uv pip install -e .
uv add --dev --editable .

Installed CLI:

metasci --help
python -m metasci --help

Release

This repository is configured for PyPI Trusted Publishing through .github/workflows/publish-pypi.yml. Configure the PyPI trusted publisher with:

• Project: metasci
• Owner: pylit-ai
• Repository: metasci
• Workflow: publish-pypi.yml
• Environment: pypi

Release checklist:

uv run python scripts/check_release_hygiene.py
uv run python scripts/check_version_tag.py v0.1.0
uv run pytest
uv run ruff check .
uv run mypy src
uv build
uvx --from twine twine check dist/*
git tag v0.1.0
git push origin v0.1.0