API Reference

scitex-app — Write-once interface for local + cloud SciTeX apps.

Standalone package. Zero dependencies (pure stdlib). When used with scitex, integration is automatic via scitex.app.

Public API (3 functions):

from scitex_app.sdk import get_files, register_backend, FilesBackend

# Get a file backend (auto-detects local vs cloud)
files = get_files("./project")

# Read/write files
content = files.read("data/config.yaml")
files.write("output/result.csv", csv_text)

# Register a custom backend
register_backend("s3", my_s3_factory)

scitex_app.get_files(root=None, *, backend=None, **kwargs)[source]

Get a files backend instance.

Auto-detection logic:

If backend is specified, use that.
If SCITEX_API_TOKEN env var is set and “cloud” backend is registered, use cloud.
Otherwise, use filesystem (default).

Parameters:

root (str or Path, optional) – Root directory for filesystem backend. Defaults to cwd.
backend (str, optional) – Explicit backend name. If None, auto-detected.
kwargs (Any)

Returns:

A backend instance.

Return type:

FilesBackend

Raises:

KeyError – If the requested backend is not registered.

scitex_app.register_backend(name, factory)[source]

Register a files backend factory.

Parameters:

name (str) – Backend identifier (e.g., “cloud”, “s3”).
factory (callable) – Callable(root, **kwargs) -> FilesBackend instance.

Return type:

None

scitex_app.build_tree(backend, directory='', *, extensions=None, skip_hidden=True, max_depth=10)[source]

Build a nested tree structure from a FilesBackend.

Parameters:

backend (FilesBackend) – A file storage backend implementing the FilesBackend protocol.
directory (str) – Starting directory (relative to backend root). Default: root.
extensions (list of str, optional) – Filter files by extension (e.g., [“.yaml”, “.png”]). Directories are always included for traversal.
skip_hidden (bool) – Skip files/directories starting with “.”. Default: True.
max_depth (int) – Maximum recursion depth to prevent runaway traversal. Default: 10.

Returns:

Nested tree structure:

[
    {"path": "subdir", "name": "subdir", "type": "directory",
     "children": [...]},
    {"path": "file.yaml", "name": "file.yaml", "type": "file"},
]

Return type:

list of dict

scitex_app.read_file(path, *, root='.', binary=False)[source]

Read a single file via the resolved FilesBackend.

Equivalent to get_files(root).read(path, binary=binary); mirrors the app_read_file MCP tool.

Return type:

Union[str, bytes]

Parameters:

path (str)
root (str | Path)
binary (bool)

scitex_app.write_file(path, content, *, root='.')[source]

Write a file via the resolved FilesBackend.

Mirrors the app_write_file MCP tool.

Return type:

None

Parameters:

path (str)
content (str | bytes)
root (str | Path)

scitex_app.list_files(directory='', *, root='.', extensions=None)[source]

List file paths under directory.

Mirrors the app_list_files MCP tool.

Return type:

List[str]

Parameters:

directory (str)
root (str | Path)
extensions (List[str] | None)

scitex_app.file_exists(path, *, root='.')[source]

Return whether path exists in the resolved backend.

Mirrors the app_file_exists MCP tool.

Return type:

bool

Parameters:

path (str)
root (str | Path)

scitex_app.delete_file(path, *, root='.')[source]

Delete path in the resolved backend.

Mirrors the app_delete_file MCP tool.

Return type:

None

Parameters:

path (str)
root (str | Path)

scitex_app.copy_file(src_path, dest_path, *, root='.')[source]

Copy src_path to dest_path within the resolved backend.

Mirrors the app_copy_file MCP tool.

Return type:

None

Parameters:

src_path (str)
dest_path (str)
root (str | Path)

scitex_app.rename_file(old_path, new_path, *, root='.')[source]

Rename old_path to new_path within the resolved backend.

Mirrors the app_rename_file MCP tool.

Return type:

None

Parameters:

old_path (str)
new_path (str)
root (str | Path)

scitex_app.scaffold(target_dir='.', *, name=None, label=None, icon='fas fa-puzzle-piece', description='', frontend='html', overwrite=False)[source]

Generate a new SciTeX workspace app skeleton.

Mirrors the app_scaffold MCP tool. Auto-appends _app / -app to name (matching the MCP tool’s behaviour) so Python and MCP callers see the same result for the same inputs.

Return type:

List[Path]

Parameters:

target_dir (str | Path)
name (str | None)
label (str | None)
icon (str)
description (str)
frontend (str)
overwrite (bool)

scitex_app.validate(app_dir='.')[source]

Audit a SciTeX app for cloud-submission readiness.

Mirrors the app_validate MCP tool. Returns the list of errors (empty when the app is ready).

Return type:: List[str]
Parameters:: app_dir (str | Path)

SDK Module

App SDK — write-once interface for local + cloud SciTeX apps.

Usage (standalone / local):

from scitex_app.sdk import get_files

files = get_files(“./my_project”) content = files.read(“recipes/my_recipe.yaml”) files.write(“output/result.png”, png_bytes)

Usage (cloud, auto-detected via SCITEX_API_TOKEN):

files = get_files() # routes through cloud REST API

Usage (remote local, via SCITEX_API_URL):

import os os.environ[“SCITEX_API_TOKEN”] = “your-token” os.environ[“SCITEX_API_URL”] = “https://scitex.ai” files = get_files() # routes to remote cloud

scitex_app.sdk.get_files(root=None, *, backend=None, **kwargs)[source]

Get a files backend instance.

Auto-detection logic:

If backend is specified, use that.
If SCITEX_API_TOKEN env var is set and “cloud” backend is registered, use cloud.
Otherwise, use filesystem (default).

Parameters:

root (str or Path, optional) – Root directory for filesystem backend. Defaults to cwd.
backend (str, optional) – Explicit backend name. If None, auto-detected.
kwargs (Any)

Returns:

A backend instance.

Return type:

FilesBackend

Raises:

KeyError – If the requested backend is not registered.

scitex_app.sdk.register_backend(name, factory)[source]

Register a files backend factory.

Parameters:

name (str) – Backend identifier (e.g., “cloud”, “s3”).
factory (callable) – Callable(root, **kwargs) -> FilesBackend instance.

Return type:

None

scitex_app.sdk.build_tree(backend, directory='', *, extensions=None, skip_hidden=True, max_depth=10)[source]

Build a nested tree structure from a FilesBackend.

Parameters:

backend (FilesBackend) – A file storage backend implementing the FilesBackend protocol.
directory (str) – Starting directory (relative to backend root). Default: root.
extensions (list of str, optional) – Filter files by extension (e.g., [“.yaml”, “.png”]). Directories are always included for traversal.
skip_hidden (bool) – Skip files/directories starting with “.”. Default: True.
max_depth (int) – Maximum recursion depth to prevent runaway traversal. Default: 10.

Returns:

Nested tree structure:

[
    {"path": "subdir", "name": "subdir", "type": "directory",
     "children": [...]},
    {"path": "file.yaml", "name": "file.yaml", "type": "file"},
]

Return type:

list of dict

FilesBackend Protocol

class scitex_app.sdk._protocol.FilesBackend(*args, **kwargs)[source]

File storage backend protocol.

Implementations must provide these 7 methods. Uses typing.Protocol for structural subtyping — backends just implement the methods, no inheritance required.

Implementations

FileSystemBackend — local pathlib (ships with scitex-app)
CloudFilesBackend — HTTP via scitex_hub (provided at runtime)

read(path, *, binary=False)[source]

Read file content.

Parameters:

path (str) – Relative path within the backend’s namespace.
binary (bool) – If True, return bytes; otherwise return str.

Raises:

FileNotFoundError – If the file does not exist.

Return type:

Union[str, bytes]

write(path, content)[source]

Write content to a file, creating parent dirs as needed.

Parameters:

path (str) – Relative path within the backend’s namespace.
content (str or bytes) – Text or binary content.

Return type:

None

list(directory='', *, extensions=None)[source]

List file paths in a directory.

Parameters:

directory (str) – Relative directory path (”” = root).
extensions (list of str, optional) – Filter by extension, e.g. [“.yaml”, “.png”].

Returns:

Relative file paths.

Return type:

list of str

exists(path)[source]

Check if a file exists.

Return type:: bool
Parameters:: path (str)

delete(path)[source]

Delete a file.

Raises:: FileNotFoundError – If the file does not exist.
Return type:: None
Parameters:: path (str)

rename(old_path, new_path)[source]

Rename/move a file within the namespace.

Raises:

FileNotFoundError – If old_path does not exist.
FileExistsError – If new_path already exists.

Return type:

None

Parameters:

old_path (str)
new_path (str)

copy(src_path, dest_path)[source]

Copy a file within the namespace.

Raises:

FileNotFoundError – If src_path does not exist.

Return type:

None

Parameters:

src_path (str)
dest_path (str)

FileSystemBackend

class scitex_app.sdk._filesystem.FileSystemBackend(root)[source]

Local filesystem implementation of FilesBackend.

All paths are relative to a root directory. Path traversal outside root is prevented.

Parameters:: root (str or Path) – Root directory for all file operations.

property root: Path: Root directory.

read(path, *, binary=False)[source]

Read file content.

Return type:

Union[str, bytes]

Parameters:

path (str)
binary (bool)

write(path, content)[source]

Write content to a file, creating parent dirs as needed.

Return type:

None

Parameters:

path (str)
content (str | bytes)

list(directory='', *, extensions=None)[source]

List file paths in a directory.

Return type:

List[str]

Parameters:

directory (str)
extensions (List[str] | None)

exists(path)[source]

Check if a file exists.

Return type:: bool
Parameters:: path (str)

delete(path)[source]

Delete a file.

Return type:: None
Parameters:: path (str)

rename(old_path, new_path)[source]

Rename/move a file.

Return type:

None

Parameters:

old_path (str)
new_path (str)

copy(src_path, dest_path)[source]

Copy a file.

Return type:

None

Parameters:

src_path (str)
dest_path (str)