SciTeX Dev (scitex-dev)
Shared developer utilities for the SciTeX ecosystem
Full Documentation · uv pip install scitex-dev[all]
Problem and Solution
| # | Problem | Solution |
|---|---|---|
| 1 | ~70 ecosystem packages drift apart -- versions, READMEs, sphinx setups, CLI conventions diverge faster than humans can audit | scitex-dev ecosystem audit-* -- audit-project, audit-cli, audit-mcp-tools, audit-python-apis, audit-skills, audit-summary enforce ~130 numbered rules across the whole ecosystem |
| 2 | Skills scattered across ~70 source repos -- AI agents can't discover them; humans can't review them | scitex-dev skills list / get / export -- aggregate every package's _skills/ and symlink them into ~/.claude/skills/scitex/ for live-edit dev loops |
| 3 | Coordinated releases need ten manual steps -- bump version, push tag, watch CI, verify PyPI, deploy — done per-package, multiplied by 70 | scitex-dev ecosystem sync + validate-versions + gui open -- one-shot install/sync across hosts, version-mismatch detection, and a web dashboard with the live state |
| 4 | Bulk renames across 70 repos break cross-references -- import paths, doc references, symlinks — sed -i corrupts something every time |
scitex-dev rename-symbols -- atomic rename with cross-reference updates, regex support, dry-run preview, git-safety guards |
| 5 | Lint rules drift from the API they enforce -- a renamed function in figrecipe leaves the rule pointing at a nonexistent symbol, and the bug only shows up months later | scitex-dev linter (engine, formerly scitex-linter) -- aggregates per-package rule plugins via the scitex_dev.linter.plugins entry point. Rules ship in the package whose API they enforce, so rename + rule + test land in one PR. Doc-block linting for .py / .ipynb / .md / .rst. scitex-dev linter sweep walks every package's README + docs in one shot |
Installation
There are exactly two installs. The CLI, the MCP server, icon rendering and skills all ship in the base install — there is no per-feature menu to assemble, and nothing to forget to add.
# Everything you need to USE scitex-dev:
pip install scitex-dev
# Plus the maintainer toolchain (pytest, sphinx, ...) — for working ON it:
pip install scitex-dev[all]
[all] adds development and documentation tooling on top of the base
install; it does not unlock features. Extra names are restricted to
{all, dev, docs} by PS-225, because a per-feature extra is something
somebody eventually pins — and a pin naming an extra that does not exist
installs anyway, warns into a log nobody reads, and silently omits the
capability.
Configuration
Copy .env.example to .env (gitignored) at your
project root, then edit. CLI flags always override env vars. The full
list (with inline comments) lives in .env.example.
Local state directories
scitex-dev reads optional config + cache from the canonical SciTeX local-state locations:
| Path | Scope | Purpose |
|---|---|---|
~/.scitex/dev/ |
user-global | per-user config, cache |
<proj-root>/.scitex/dev/ |
project-local | overrides for the current repo |
Project-local wins when both exist. Both are optional.
Architecture
scitex_dev/
├── _cli/
│ ├── audit/ ← rule corpus (PA*, PS*, SK*, §*)
│ │ ├── _api/ ← Python-API rules (PA-1xx)
│ │ ├── _project/ ← project-structure rules (PS-1xx, PS-5xx)
│ │ ├── _skills/ ← skill-file rules (SK-1xx)
│ │ └── _summary/ ← CLI/MCP §-rules + audit-all wrapper
│ ├── ecosystem/ ← cross-package commands (audit-all, list, …)
│ └── _skills.py ← `scitex-dev skills` group
├── _ecosystem/ ← shared helpers (skill-quality, ECOSYSTEM map)
├── _skills/ ← canonical skill-file corpus shipped to agents
└── testing/ ← `audit_all_for_package` pytest helper
Audit rules live alongside the code they check. Each rule has a
docstring, an entry in RULES, a severity in _SEVERITY_OVERRIDES,
and at least one unit test under tests/.../_audit/_project/.
Demo
flowchart LR
A["scitex-dev ecosystem<br/>audit-all <pkg>"] --> B[audit-cli]
A --> C[audit-mcp-tools]
A --> D[audit-skills]
A --> E[audit-python-apis]
A --> F[audit-project]
B & C & D & E & F --> G{any error?}
G -- "yes" --> H["exit 1<br/>(CI fails)"]
G -- "no" --> I["exit 0<br/>(CI green)"]
scitex-dev is a CLI/audit tool — its "demo" is the audit running on a
package. Sample output (run on scitex-io):
=== audit-cli ===
ok scitex-io: no CLI convention violations
=== audit-mcp-tools ===
ok scitex-io: no MCP convention violations
=== audit-skills ===
ok scitex-io: no skills violations
=== audit-python-apis ===
ok scitex-io: no Python API violations
=== audit-project ===
ok scitex-io: no project-structure violations
Failure mode (sample, scitex-dsp before the Hilbert fix):
=== audit-project ===
fail scitex-dsp (/home/ywatanabe/proj/scitex-dsp): 2 error(s)
[E] [PS-141 §1] README.md: missing mandatory `## Demo` section
[E] [PS-503 §5] examples/01_demo_out: no FINISHED_SUCCESS/<session_id>/ subdir
See examples/ for runnable demos that exercise
scitex-dev's own commands (search, version-management, docs
aggregation).
Four Interfaces
Python API ⭐⭐
All public names are re-exported flat from the top-level package — import
them directly from scitex_dev (internals live under _release, _docs,
_core; don't import those paths).
# Version management
from scitex_dev import detect_mismatches, fix_local, fix_remote, verify_versions
mismatches = detect_mismatches()
fix_local(packages=["scitex-stats"], confirm=True)
verify_versions()
# CI/CD
from scitex_dev import check_ci, get_failing_packages, check_pypi_publish
status = check_ci()
failing = get_failing_packages()
# Docs & search
from scitex_dev import get_docs, build_docs, search
get_docs(package="scitex-writer")
search("save figure")
# Deployment
from scitex_dev import deploy_scitex_hub, verify_production
deploy_scitex_hub(confirm=True)
# LLM-friendly types
from scitex_dev import Result, ErrorCode, supports_return_as
Skills are managed through the CLI (
scitex-dev skills list/get/export), not a Python module.
CLI Commands ⭐⭐⭐ (primary)
# Ecosystem management
scitex-dev ecosystem list
scitex-dev ecosystem list --versions
scitex-dev ecosystem fix-mismatches --dry-run
scitex-dev ecosystem sync
# Documentation
scitex-dev docs --package scitex-writer
scitex-dev search-docs "save figure"
# Bulk rename
scitex-dev rename-symbols old_name new_name --dry-run
# See all commands
scitex-dev --help
scitex-dev --help-recursive
MCP Server ⭐⭐
# Start server
scitex-dev mcp start
# Check setup
scitex-dev mcp doctor
scitex-dev mcp list-tools
# Installation info
scitex-dev mcp installation
Claude Code Setup — add .mcp.json to your project root. Use SCITEX_DEV_ENV_SRC to load configuration from a .src file:
{
"mcpServers": {
"scitex-dev": {
"command": "scitex-dev",
"args": ["mcp", "start"],
"env": {
"SCITEX_DEV_ENV_SRC": "${SCITEX_DEV_ENV_SRC}"
}
}
}
}
Switch environments via your shell profile:
# Local machine
export SCITEX_DEV_ENV_SRC=~/.scitex/dev/local.src
# Remote server
export SCITEX_DEV_ENV_SRC=~/.scitex/dev/remote.src
Skills ⭐⭐⭐ (primary)
Skills provide workflow-oriented guides that AI agents query to discover capabilities and usage patterns.
scitex-dev skills list # List available skill pages
scitex-dev skills get SKILL # Show main skill page
scitex-dev skills export --package scitex-dev # Export to Claude Code
# Private skills (~/.scitex/*/skills/*-private/) are symlinked automatically
| Skill | Content |
|---|---|
result-types |
Result, ErrorCode, @supports_return_as for LLM-friendly responses |
cli-mcp-utils |
CLI and MCP utility helpers |
config |
Package configuration and priority config patterns |
versions |
Version management, mismatch detection and fixing |
ecosystem |
Ecosystem list, sync, and commit workflows |
rename |
Safe bulk rename with cross-reference updates |
docs-search |
Documentation aggregation and unified search |
test-runner |
Local and HPC test execution |
full-update / full-update-deploy |
End-to-end audit → bump → release → sync pipelines |
agentic-test-overview / -skills / -mcp |
Agent-vs-agent quality testing |
dynamic-audit |
Cross-package periodic audit checklist |
env-vars |
SCITEX_DEV_* / SCITEX_* environment variable reference |
Part of SciTeX
scitex-dev is part of SciTeX. Install via
the umbrella with pip install scitex[dev] to use as
scitex.dev (Python) or scitex dev ... (CLI).
SciTeX follows the Four Freedoms for Research below, inspired by the Free Software Definition:
Four Freedoms for Research
- The freedom to run your research anywhere — your machine, your terms.
- The freedom to study how every step works — from raw data to final manuscript.
- The freedom to redistribute your workflows, not just your papers.
- The freedom to modify any module and share improvements with the community.
AGPL-3.0 — because we believe research infrastructure deserves the same freedoms as the software it runs on.
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file scitex_dev-0.47.0.tar.gz.
File metadata
- Download URL: scitex_dev-0.47.0.tar.gz
- Upload date:
- Size: 12.5 MB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via: twine/7.0.0 CPython/3.12.13
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
e33b89f601b698d6e5b87550ce693481cfd06b395994561c50678e98c9ad18d2
|
|
| MD5 |
fe1a45706cb83c3d0559a3d282a74208
|
|
| BLAKE2b-256 |
45a3673e80f864d66446d2466a3007ae0d7a05026baf168978a9996a40785a1d
|
File details
Details for the file scitex_dev-0.47.0-py3-none-any.whl.
File metadata
- Download URL: scitex_dev-0.47.0-py3-none-any.whl
- Upload date:
- Size: 11.1 MB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via: twine/7.0.0 CPython/3.12.13
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
62f7d0a83524d53c060d2431a4265bda37ec3c4348201d4db685309cdca3b840
|
|
| MD5 |
be478a0b02e7527b0e273961b840ed55
|
|
| BLAKE2b-256 |
9f7fe5815ba0b859bbc4b1a12ac1e8c482a9b6867d94bf9cfe569fdb0dc7f536
|
