Metadata-Version: 2.4
Name: pycforge-sdk
Version: 0.18.0
Summary: Conversion-extension authoring SDK with an optional PySide6 desktop
License-Expression: GPL-3.0-only
Requires-Python: <3.14,>=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: gui
Requires-Dist: PySide6<7,>=6.8; extra == "gui"
Dynamic: license-file

<img src="https://res.cloudinary.com/vppzdwxg/image/upload/v1793376351/pcf_sdk_banner.png" alt="PyCForge SDK" width="640">

# PyCForge SDK 0.18.0

PyCForge SDK is for **human developers, engineers and AI programming tools** building
conversion imports for PyCForge. It provides a desktop workspace, command line
and Python API to author supported operations, write package Help, develop tests
and produce a verified `.pcfplugin` package for use through `*import`.

All three interfaces share the same services, project files and verification
rules. The SDK includes no AI model; authors define intended behavior and
independently justified test expectations.

## From New Project to a usable import

**New → Use walkthrough** organizes setup into five focused steps: starting point,
project location, package identity, export names, and review. Choose an
engine-supplied starter, customize its supported fields, and create the project.
Back navigation retains your entries. **Create directly** uses the same fields.

The optional authoring guide then leads through project details, functions,
package and function Help, fixtures, and review. Each step concentrates on its
requirements. Switch to direct editing at any time; advanced controls and full
project JSON remain available.

The workspace provides:

- **Authoring and Help:** engine-defined forms, operation explanations, searchable
  reference and offline documentation that travels with the package.
- **Fixture development:** reviewed addition, duplication, renaming and removal;
  source editing; and expected-versus-actual output, errors and exit status.
- **Checks and diagnostics:** Scan identifies work needed; Check fixtures reviews
  conversion expectations without running programs; Verify fixtures explicitly
  compiles and executes the declared native tests.
- **Packaging and handoff:** Package checks current verification before creating
  the import. Its handoff shows the namespace and a verified usage example.
  Registration with PyCForge remains a separate action.

Browsing, reviewing and moving between steps do not run fixtures or approve a
package. Observed output never automatically replaces your expectations.

## Save, pause and recover

**Save** writes project fields, Help and expectations. Fixture source has its own
save action. For unfinished work, use the appropriate checkpoint:

- **Save setup** retains New Project choices in `.pcfsetup`; **New → Open setup**
  resumes them, including offline. Changed starter data requires review.
- **File → Save project draft** retains project fields, Help, expectations and
  your authoring position in `.pcfdraft`. The fixture dialog can also save its
  unfinished inputs, and Advanced project data can save incomplete JSON.
- **File → Open project draft** reopens saved work without an engine. Review the
  original, edited and current disk data, then resume editing or explicitly save
  the reviewed project. An unfinished fixture requires its own review and apply.
- **Save repair as** in the source editor retains original and edited source in
  `.pcfrepair`. **File → Open source repair** compares it with current files before
  applying a repair.

**Review current draft** helps reconcile outside changes without discarding the
open project buffer. Save checkpoints outside the project. They are explicit
saves, not autosave or whole-project backups: later unsaved edits are not recovered.
Missing project/source files must be restored separately. Existing files and
checkpoint replacements have conflict checks; recovery performs no automatic
merge. Project and fixture saves remain separate operations.

## Capabilities supplied by PyCForge

The selected PyCForge installation supplies conversion operations, starters,
authoring forms, native profiles and import manuals through its versioned
Crucible communication files. The SDK maintains no library capability list.
**Refresh** after updating PyCForge makes compatible additions available without
a matching SDK release. Unsupported required interfaces are reported explicitly.

The SDK is installed separately. Connecting installs neither product. A library
namespace supports the operations admitted by its engine profile; registration
does not make every operation in the corresponding Python library convertible.
Use **Engine reference → Conversion coverage** and Import Help for exact limits.

## Install and connect

Use Python 3.11–3.13, install PyCForge separately, then install the SDK desktop:

```sh
python -m pip install --upgrade "./pycforge_sdk-0.18.0-py3-none-any.whl[gui]"
pycforge-sdk-ui
```

On Windows, `py` can replace `python`. Omit `[gui]` for command-line and Python
use without the desktop. PySide6 is the optional desktop dependency; the headless
SDK has no required third-party dependencies.

Startup searches for installed PyCForge environments and remembers a successful
connection. If necessary, use **Locate PyCForge** to select the installation or
environment. **Engine and tools** also accepts its interpreter directly:
`Scripts/python.exe` in a Windows virtual environment, or `bin/python` on
Linux/macOS. **This Python** selects the SDK's interpreter when both products
share an environment. PyCForge shows its interpreter under
**About → Distribution → SDK Python**.

**Continue offline** opens local projects and cached reference. Engine operations
require a compatible connection. Searches check known locations rather than
scanning entire drives; manually locate environments stored elsewhere.

## Command line, Python and AI clients

Use `pycforge-sdk manual` for the installed guide, `manual --topic api` for the
Python services and request formats, and `manual --topic diagnostics` for failure
handling. These manuals need no engine. Press **F1** for desktop Help.

The command line provides creation, draft recovery, fixture editing, conversion
checks, verification, packaging and registration. Supply `--engine-python` for a
separate engine environment and put `--json` before a command for structured
results, diagnostic codes and field locations. A nonzero exit code means the
operation did not succeed.

```python
from pycforge_sdk import SDK

sdk = SDK(engine_python="/path/to/engine/python", cache="./sdk-cache")
result = sdk.templates()
if not result.ok:
    raise RuntimeError(result.to_dict())
for starter in result.data["templates"]:
    print(starter["id"], starter["description"])
```

`SDK()` also supports local manuals, project editing and recovery without
connecting. Discover capabilities through `coverage`, `reference` and `fields`;
use the same explicit save, verify and build services as the desktop.

## Practical requirements

Native verification requires a compiler and host supported by the selected
engine's profile. The supplied qualification profile uses Linux and a GNU-style
C compiler. Windows desktop authoring and native Windows/macOS execution require
their own qualification; a portable wheel does not establish native support.
New recovery checkpoints require a filesystem supporting hard links and fail
explicitly when unavailable. Use a local supported filesystem for checkpoints.

Verification covers the declared cases. Reverify after changes to project data,
Help, sources, the SDK, engine or compiler. Failed checks preserve existing
packages and evidence; packaging requires current matching results. For PCFC11,
use the engine-supported backend query; changes to the recorded GCC backend
require fresh verification.

## License

GNU General Public License v3.0 only. The distribution includes `LICENSE`.
