SciTeX App (scitex-app)

Write-once interface for local + cloud SciTeX apps

Full Documentation · pip install scitex-app

---

Problem and Solution

#	Problem	Solution
1	Every lab reinvents its Django "lab tools" webapp -- three months of plumbing before the first domain feature ships	App scaffold -- scitex-app init <name> produces a working Django app with auth, file browser, session logging, routes, manifest
2	Apps don't compose -- each lab's app is a snowflake; can't install B into A's workspace	FilesBackend plugin registry -- apps declare a manifest.json; scitex-app dev-install registers them into any SciTeX Cloud workspace
3	Local-vs-cloud storage fork -- pathlib everywhere; cloud integration means rewriting every app	Auto-backend get_files(root) -- returns a FilesBackend that transparently uses local disk or cloud storage; same read/write API

Problem

SciTeX apps (like FigRecipe, Writer, Stats) need to work in three environments: standalone local (pip install), cloud (scitex.ai), and self-hosted. Today, each environment requires different file I/O code — pathlib locally, HTTP REST calls on cloud. This means maintaining two codebases or tightly coupling apps to one deployment mode.

Solution

SciTeX App provides a unified file storage SDK with a single FilesBackend protocol. Apps call get_files() and get back a backend that works identically regardless of environment. Write your app once — it runs everywhere.

Environment	Backend	How it works
Local	FileSystemBackend	pathlib-based, zero dependencies
Cloud	CloudFilesBackend	HTTP REST via SCITEX_API_TOKEN (injected at runtime)
Custom	register_backend()	S3, GCS, or any storage you need

_{Table 1. Three deployment modes. The SDK auto-detects cloud when SCITEX_API_TOKEN is set; otherwise defaults to local filesystem.}

Seven Operations

Every backend implements the same 7-method protocol:

Method	Description
read(path)	Read file content (text or binary)
write(path, content)	Write content, creating parent dirs
list(directory)	List files with optional extension filter
exists(path)	Check if a file exists
delete(path)	Delete a file
rename(old, new)	Rename/move a file
copy(src, dest)	Copy a file

_{Table 2. The FilesBackend protocol. Uses typing.Protocol for structural subtyping — backends just implement the methods, no inheritance required.}

Installation

Requires Python >= 3.10. Zero dependencies — pure stdlib.

pip install scitex-app

SciTeX users: pip install scitex already includes App SDK. Access via scitex.app.

Quickstart

from scitex_app.sdk import get_files

# Local filesystem (default)
files = get_files("./my_project")
content = files.read("config/settings.yaml")
files.write("output/result.csv", csv_text)

# List files with filter
yaml_files = files.list("config", extensions=[".yaml"])

# Cloud mode (auto-detected via SCITEX_API_TOKEN)
import os
os.environ["SCITEX_API_TOKEN"] = "your-token"
cloud_files = get_files()  # routes through cloud REST API

Three Interfaces

Python API

from scitex_app.sdk import get_files, register_backend, FilesBackend

files = get_files("./project")        # auto-detect backend
files.read("data.csv")                # read file
files.write("out.txt", "hello")       # write file
files.list(extensions=[".yaml"])       # list with filter
files.exists("config.yaml")           # check existence
files.delete("temp.txt")              # delete file
files.rename("old.txt", "new.txt")    # rename/move
files.copy("src.txt", "dst.txt")      # copy file

Full API reference

CLI Commands

scitex-app --help-recursive              # Show all commands
scitex-app read <path>                   # Read a file
scitex-app write <path> "content"        # Write to a file
scitex-app list [directory]              # List files
scitex-app exists <path>                 # Check existence
scitex-app delete <path>                 # Delete a file
scitex-app rename <old> <new>            # Rename/move a file
scitex-app copy <src> <dest>             # Copy a file
scitex-app list-python-apis              # List Python API tree
scitex-app mcp list-tools                # List MCP tools

All file commands support --json output. Destructive commands support --dry-run.

Full CLI reference

MCP Server — for AI Agents

AI agents can read, write, and manage files through the unified SDK.

Tool	Description
app_read_file	Read a file through the SDK backend
app_write_file	Write content to a file
app_list_files	List files in a directory
app_file_exists	Check if a file exists
app_delete_file	Delete a file
app_copy_file	Copy a file
app_rename_file	Rename/move a file

_{Table 3. Seven MCP tools mirroring the FilesBackend protocol. All tools accept JSON parameters and return JSON results.}

scitex-app mcp start

Full MCP specification

App Development CLI

Create, validate, and publish SciTeX apps — no platform installation required.

# Scaffold a new app
scitex-app app init . --name my_cool_app

# Validate before submission
scitex-app app validate .

# Dev-install on your SciTeX Cloud server
scitex-app app dev-install . --server http://127.0.0.1:8000

# Submit for public review
scitex-app app submit .

Also available via the main CLI: scitex app init, scitex app validate, etc.

Role in SciTeX Ecosystem

scitex-app is the complete toolkit for app developers — runtime SDK + development CLI. It provides backend-agnostic interfaces that let apps work locally, on the cloud, or self-hosted without code changes.

scitex (orchestrator, core compute, CLI, MCP)
  |-- scitex-app (this package) -- app SDK + development CLI
  |     |-- appmaker            -- scaffold, validate, publish
  |     |-- ScitexAppConfig     -- Django base class for app integration
  |     |-- AppValidator        -- security/privilege checking
  |     |-- FilesBackend        -- unified file I/O protocol
  |     |-- paths               -- project path resolution
  |     +-- chat                -- AI backend interface
  |-- scitex-ui                 -- React/TS component library
  +-- figrecipe                 -- reference app (figures)

What this package owns:

• App scaffolding, validation, and submission (scitex-app app init/validate/submit)
• Dev-install workflow (scitex-app app dev-install)
• FilesBackend protocol and implementations (filesystem, cloud, custom)
• ScitexAppConfig Django base class (from scitex_app._django import ScitexAppConfig)
• AppValidator for security and privilege checking
• Path resolution utilities for project/workspace discovery

What this package does NOT own:

• Frontend components -- see scitex-ui
• Platform server APIs -- see scitex-cloud
• Core compute (io, stats, plt) -- see scitex

Part of SciTeX

App SDK is part of SciTeX. When used inside the SciTeX framework, the SDK is available via scitex.app:

import scitex

# Access files through the unified SDK
files = scitex.app.get_files("./project")
content = files.read("recipes/scatter.yaml")
files.write("output/figure.png", png_bytes)

Apps built with scitex-app work in all three modes:

• Standalone: pip install figrecipe runs locally with filesystem backend
• Cloud: Deploy to scitex.ai — cloud backend injected automatically
• Self-hosted: Run your own instance with custom backends

The SciTeX system follows the Four Freedoms for Research below, inspired by the Free Software Definition:

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.

---