Library Integration

Command and library integration

SYSTEMX can be copied as a self-contained folder or installed as the dotsystemx Python distribution, which exposes the systemx command and importable module. The package includes the same template files and uses no third-party runtime dependencies. A package installation does not initialize or alter any project.

Install into a chosen Python environment

From the public Git repository:

python3 -m venv .venv
# Activate this environment using your platform's normal command, then:
python -m pip install "git+https://github.com/WayneTechLab/dotSYSTEMX.git@v1.9.0-alpha.3"
python -I -B -m systemx setup --profile project
python -I -B -m systemx install --target "/path/to/project" --profile project

On Windows use py -3 -m venv .venv and .\.venv\Scripts\Activate.ps1 if your execution policy permits it; alternatively call that environment's Python and SYSTEMX executables directly. No policy change or administrator access is needed. Git-based pip installation requires Git. An extracted release can also be installed with python -m pip install /path/to/dotSYSTEMX, or use its published wheel without Git. The package is distributed through GitHub; no PyPI publication is implied. Select exact versions from the release history. The 1.9.0-alpha.1 tag was withdrawn after a distribution manifest mismatch; do not install or select it.

Upgrading the Python package only updates that tool environment. Each project's default version and pin remain independent. systemx update --target ... selects project defaults under the preservation contract.

The public release ID 1.9.0-alpha.3 is spelled 1.9.0a3 in Python package metadata and wheel filenames (PEP 440). They identify the same release. systemx --version shows both; status --target ... shows project defaults. The library and CLI are alpha APIs; review release policy before upgrading integrations.

The installed systemx console entry point resolves its package through the launching interpreter's import paths before it can restart in isolated mode and import the manager. It assumes those initial paths are trusted. If PYTHONPATH or the working directory is untrusted, invoke a reviewed virtual environment's Python as python -I -B -m systemx ... from the initial start. Isolation hides user site-packages, so install into that virtual environment, rather than with pip install --user. Calling from systemx import ... inside an application inherits that application's interpreter, import paths, and installed-package trust environment.

Python API

from systemx import install, update, bootstrap_refresh, status, set_policy, export_chat, alias

# Plan without touching the target, using a local reviewed distribution:
plan = install("/path/to/project", source="/path/to/template/.SYSTEMX",
               profile="project", dry_run=True)

# Apply only after choosing the intended project:
result = install("/path/to/project", source="/path/to/template/.SYSTEMX")
print(status("/path/to/project"))

# Updates require explicit unlocking of the default pin:
set_policy("/path/to/project", pin="none")
update("/path/to/project", source="/path/to/new-template/.SYSTEMX", dry_run=True)

# Export only to a new file; nothing is uploaded:
export_chat("/path/to/project", "/path/to/new-session.md", agent="agent.0")

Management functions return structured dictionaries. run and projects return subprocess.CompletedProcess; inspect returncode, stdout, and stderr. Importing the library executes the installed package in the host interpreter; it does not initialize or modify a project or contact the network. The CLI renders management results as JSON and uses exit status 2 for a rejected operation. Project command execution preserves the underlying command's exit status. Use systemx run --target ... -- <command> to invoke the selected defaults against that project's canonical records.

install defaults to the package's bundled version. Supply version to fetch a specific GitHub release, or source for offline installation. update uses the installation's selected repository unless given a local source. Downloaded files are bounded, path-checked, and fingerprint-verified; archives are never blindly extracted into a project. Existing root files are opened only for inspection or left alone, and missing files are created exclusively. A fresh install refuses preexisting .py, .sh, or .ps1 defaults whose content differs from the chosen distribution. An existing managed installation must explicitly refresh recognized stock root bootstrap files, with backups, before an update that needs them:

from systemx import bootstrap_refresh

preview = bootstrap_refresh("/path/to/project", source="/reviewed/new/.SYSTEMX")
if not preview["conflicts"] and (preview["add"] or preview["replace"]):
    bootstrap_refresh("/path/to/project", source="/reviewed/new/.SYSTEMX", apply=True)

The eight stock bootstrap and launcher files are manager.py, lifecycle.py, versions.py, systemx_paths.py, SYSTEMX.sh, SYSTEMX.ps1, INSTALL.sh, and INSTALL.ps1. A truly absent stock file can be added only when no intact retained release contained it. A file missing from the root despite appearing in a retained release, or customized or unrecognized content, blocks refresh. Only replaced files receive byte-for-byte backups; an add-only refresh has no original to back up. Review the preview and operation receipt; see installation migration.

The current library installs and newly selects only releases 1.8.7-alpha.1 or newer. It can run an already selected, verified older snapshot through an isolated compatibility shim, but the old runner retains historical behavior. Historical reselection needs a separately reviewed backup or legacy path.

For an exact remote tag, install, update, and first_run accept archive_sha256="<64-hex digest>"; the CLI spells this --archive-sha256. Use the SHA-256 of the exact GitHub codeload tag ZIP obtained from an independent trusted record, not a separately built release archive or wheel. The selected release cache must have exactly its manifest-listed inventory before execution. See installation and updates.

These functions are a possible future adapter boundary for MCP or other tools. Such an adapter would still need explicit target selection, access controls, permission handling, and evidence of writes. No server, remote endpoint, or additional authority is included by installing this library.

Packaging references: PyPA project metadata and entry points.

Exact directory casing

The API always manages the real .SYSTEMX directory beneath its target. install(target, lowercase_alias=True) optionally creates a local relative .systemx -> .SYSTEMX link. alias(target) reports the layout without writing; alias(target, create=True, dry_run=True) previews and alias(target, create=True) requests creation. Case-insensitive filesystems report filesystem-equivalent. The status response includes pathLayout. Conflicting case variants raise ValueError without merging or deleting them. See the case contract.

First run and reversible removal

from systemx import first_run, audit, uninstall, restore

first_run("/path/to/project")  # preview
first_run("/path/to/project", apply=True)
audit("/path/to/project")      # read-only, scoped footprint and operation history
uninstall("/path/to/project", backup="/path/to/new-backup")  # preview
uninstall("/path/to/project", backup="/path/to/new-backup", apply=True)
restore("/path/to/project", backup="/path/to/new-backup")    # preview
restore("/path/to/project", backup="/path/to/new-backup", apply=True)

Uninstall moves the whole .SYSTEMX folder, including user records, to an external backup on the same filesystem. It does not uninstall this Python package. Run removal/restore from an external environment or checkout. Preserve the receipt and use the cleanup guide for package removal and intentional leftovers.

SYSTEMX PROJECTS API and selected chat export

from systemx import projects, export_chat

preview = projects("/path/to/workspace", ["add", "Project-A", "--kind", "software"])
preview.check_returncode()
created = projects("/path/to/workspace", ["add", "Project-A", "--apply"])
created.check_returncode()
packet = projects("/path/to/workspace", ["context", "--project", "Project-A"])
packet.check_returncode()
print(packet.stdout)
export_chat("/path/to/workspace", "/path/to/project-a-chat.md", project="Project-A")

projects(target, arguments, *, offline=True, capture=True) runs the selected outer release's projects command. The target is the directory containing the outer .SYSTEMX, not a child's folder. Arguments are a nonempty list/tuple of strings. Scope commands require --project NAME or --root.

export_chat(..., project="Project-A") includes only that child's active records with shared default guidance. Omit project for the root packet. The equivalent CLI is systemx export-chat --target PATH --project Project-A --output NEW_FILE. It never overwrites an existing output or uploads the packet. The returned management dictionary includes project (null for root), version, output, and uploaded: false. Review private context before sharing. See SYSTEMX PROJECTS for scoping, commands, and preservation rules.

Standard role commands

from systemx import run, projects

result = run("/path/to/workspace", ["roles-init"], offline=True, capture=True)
result.check_returncode()  # preview; add --apply after reviewing the intended scope
projects("/path/to/workspace", ["agent-z", "policy", "--project", "Project-A"]).check_returncode()

run is exported by the package and returns subprocess.CompletedProcess. Arguments must be an explicit string array; they cannot override the chosen workspace's global --root. Scoped projects ... --root remains valid. Role commands perform local record operations; they do not schedule external jobs, call a model, run checks, or upload evidence. Use offline=True to suppress an independently enabled startup release check. That check reports an available version without selecting it. See Agent X, Agent Y, and Agent Z.