Metadata-Version: 2.4
Name: scitex-dev
Version: 0.3.0
Summary: Shared developer utilities for the SciTeX ecosystem
Author-email: Yusuke Watanabe <ywatanabe@scitex.ai>
License-Expression: AGPL-3.0-only
Project-URL: Homepage, https://github.com/ywatanabe1989/scitex-dev
Project-URL: Repository, https://github.com/ywatanabe1989/scitex-dev
Project-URL: Documentation, https://scitex-dev.readthedocs.io/
Keywords: scitex,developer-tools,documentation,llm-friendly,mcp
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: cli
Requires-Dist: click>=8.0.0; extra == "cli"
Provides-Extra: mcp
Requires-Dist: fastmcp>=2.0.0; extra == "mcp"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=7.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=2.0; extra == "docs"
Requires-Dist: myst-parser>=2.0; extra == "docs"
Requires-Dist: sphinx-copybutton>=0.5; extra == "docs"
Requires-Dist: sphinx-autodoc-typehints>=1.25; extra == "docs"
Provides-Extra: all
Requires-Dist: scitex-dev[cli]; extra == "all"
Requires-Dist: scitex-dev[mcp]; extra == "all"
Requires-Dist: scitex-dev[dev]; extra == "all"
Requires-Dist: scitex-dev[docs]; extra == "all"
Dynamic: license-file

# SciTeX Dev (`scitex-dev`)

<p align="center">
  <a href="https://scitex.ai">
    <img src="docs/scitex-logo-blue-cropped.png" alt="SciTeX" width="400">
  </a>
</p>

<p align="center"><b>Shared developer utilities for the SciTeX ecosystem</b></p>

<p align="center">
  <a href="https://badge.fury.io/py/scitex-dev"><img src="https://badge.fury.io/py/scitex-dev.svg" alt="PyPI version"></a>
  <a href="https://scitex-dev.readthedocs.io/"><img src="https://readthedocs.org/projects/scitex-dev/badge/?version=latest" alt="Documentation"></a>
  <a href="https://github.com/ywatanabe1989/scitex-dev/actions/workflows/test.yml"><img src="https://github.com/ywatanabe1989/scitex-dev/actions/workflows/test.yml/badge.svg" alt="Tests"></a>
  <a href="https://www.gnu.org/licenses/agpl-3.0"><img src="https://img.shields.io/badge/License-AGPL--3.0-blue.svg" alt="License: AGPL-3.0"></a>
</p>

<p align="center">
  <a href="https://scitex-dev.readthedocs.io/">Full Documentation</a> · <code>pip install scitex-dev</code>
</p>

---

## Problem

The SciTeX ecosystem spans multiple packages (scitex-clew, scitex-writer, scitex-stats, figrecipe, etc.), each with their own documentation, versions, APIs, and CLI commands. Keeping them in sync, discovering what's available, and maintaining consistency across the ecosystem becomes increasingly difficult as it grows.

## Solution

`scitex-dev` provides a unified toolkit for developing and maintaining the SciTeX ecosystem:

- **Docs aggregation** — discover, build, and search documentation across all packages from a single entry point
- **Unified search** — search Python APIs, CLI commands, MCP tools, and docs with fuzzy matching and Google-like syntax
- **Version management** — track, compare, and fix version mismatches across pyproject.toml, `__init__.py`, git tags, PyPI, and RTD
- **Bulk rename** — safe, preview-able renaming with cross-reference updates across the entire codebase
- **LLM-friendly types** — `Result`, `ErrorCode`, `@supports_return_as` for consistent structured responses

Zero runtime dependencies. Pure stdlib.

## Installation

```bash
pip install scitex-dev

# With CLI support:
pip install scitex-dev[cli]

# With MCP server:
pip install scitex-dev[mcp]

# Everything:
pip install scitex-dev[all]
```

## Quick Start

```python
import scitex_dev

# Unified search across the ecosystem
results = scitex_dev.search("save figure")

# Version management
versions = scitex_dev.list_versions()
mismatches = scitex_dev.get_mismatches()

# Documentation aggregation
docs = scitex_dev.get_docs(package="scitex-writer", format="json")
```

## Three Interfaces

<details>
<summary><b>Python API</b></summary>

```python
import scitex_dev

# Search
scitex_dev.search("ttest", scope="api")
scitex_dev.search('+required -excluded "exact phrase"')

# Docs
scitex_dev.get_docs()
scitex_dev.get_docs(package="scitex-writer", format="json")
scitex_dev.build_docs(package="scitex-writer")
scitex_dev.search_docs("installation")

# Versions
scitex_dev.list_versions()
scitex_dev.check_versions(["scitex", "figrecipe"])
scitex_dev.get_mismatches()
scitex_dev.fix_mismatches(dry_run=True)

# LLM-friendly types
from scitex_dev import Result, supports_return_as

@supports_return_as
def my_function(x: int) -> int:
    return x * 2

result = my_function(5, return_as="result")
# Result(success=True, data=10)
```

</details>

<details>
<summary><b>CLI Commands</b></summary>

```bash
# 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 "save figure"

# Bulk rename
scitex-dev rename old_name new_name --dry-run

# See all commands
scitex-dev --help
scitex-dev --help-recursive
```

</details>

<details>
<summary><b>MCP Server</b></summary>

```bash
# 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:

```json
{
  "mcpServers": {
    "scitex-dev": {
      "command": "scitex-dev",
      "args": ["mcp", "start"],
      "env": {
        "SCITEX_DEV_ENV_SRC": "${SCITEX_DEV_ENV_SRC}"
      }
    }
  }
}
```

Switch environments via your shell profile:

```bash
# Local machine
export SCITEX_DEV_ENV_SRC=~/.scitex/dev/local.src

# Remote server
export SCITEX_DEV_ENV_SRC=~/.scitex/dev/remote.src
```

</details>

## Part of SciTeX

`scitex-dev` is part of [SciTeX](https://scitex.ai). It provides the shared infrastructure that keeps the ecosystem consistent and discoverable. When used with the orchestrator package `scitex`, it enables unified version management and documentation across all modules:

```python
import scitex_dev

# See the entire ecosystem at a glance
versions = scitex_dev.list_versions()
mismatches = scitex_dev.get_mismatches()

# Search across all installed SciTeX packages
scitex_dev.search("statistical test")
```

The SciTeX system follows the Four Freedoms for Research below, inspired by [the Free Software Definition](https://www.gnu.org/philosophy/free-sw.en.html):

>Four Freedoms for Research
>
>0. The freedom to **run** your research anywhere — your machine, your terms.
>1. The freedom to **study** how every step works — from raw data to final manuscript.
>2. The freedom to **redistribute** your workflows, not just your papers.
>3. 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.

---

<p align="center">
  <a href="https://scitex.ai">
    <img src="docs/scitex-icon-navy-inverted.png" alt="SciTeX" width="40">
  </a>
</p>
