PyCForge SDK 0.7.0

PyCForge SDK is the development kit for creating conversion imports for PyCForge. Define supported library operations, write their documentation and examples, check the generated C, and build a .pcfplugin package for use through *import.

Designed for human developers and AI tools, the SDK offers a desktop workspace, a command-line interface, and a Python API. All three use the same project files, conversion services, and verification rules.

A workspace for conversion imports

Start with a working example: choose scalar math, named parameters, NumPy, JSON, or independently named array, structured-value and Unicode text libraries from the connected engine's starters.
Define your library: give its operations names and descriptions, using the conversion capabilities supplied by PyCForge.
Explain how to use it: include parameter descriptions, return values, practical limits, and examples in the package's searchable offline Help.
Find what needs attention: scan for incomplete fields, missing examples, and verification that needs repeating. Open a finding to reach its field.
Check the result: convert examples to C, compile and run the declared tests, and compare their results with your expectations.
Build and register: create a verified .pcfplugin package, then register it with PyCForge when you are ready to use it.

Capabilities supplied by PyCForge

PyCForge supplies the SDK's conversion operations, starter projects, authoring forms, method explanations, and Help. Its Crucible folder contains a versioned workbench definition and JSON schema, alongside the catalogue and import manuals. The SDK reads these descriptions without carrying its own list of libraries. After updating the selected PyCForge installation, reconnect the SDK to refresh that information. Compatible engine additions, including new default imports and their Help, become available without requiring a matching SDK release.

The SDK application is installed separately. Changes to its desktop, command-line tools, or support for an incompatible engine interface require a separate SDK update. Connecting refreshes information from the installed PyCForge; it does not download or install either application. Reverify your projects after updating PyCForge, the SDK, or the C compiler.

Install and open

Use Python 3.11–3.13 and install PyCForge separately. Install the SDK desktop from its wheel:

python -m pip install "./pycforge_sdk-0.7.0-py3-none-any.whl[gui]"
pycforge-sdk-ui

On Windows, py can be used in place of python. For command-line, Python API, or AI automation without the desktop, omit [gui]. The desktop includes PySide6; the SDK without the desktop has no required third-party dependencies. Add --upgrade to the install command when installing an updated SDK wheel.

The desktop looks for PyCForge when it opens. It checks your last successful connection first, then common Python installations and environment folders. A startup panel shows progress. If several installations are found, choose the version and location you want; the SDK remembers a successful connection.

If PyCForge cannot be found, choose Locate PyCForge. Select its installation, Python environment, or installed SDK support folder (pycforge/crucible/landscape). The picker provides drive shortcuts, including C: on Windows. The SDK finds and validates the matching interpreter; a source folder by itself needs a working engine installation. Continue offline opens local projects and any cached reference without connecting.

Refresh reloads the selected engine's capabilities. Engine and tools contains advanced interpreter and compiler settings, Find installed, and This Python for a shared environment. You can also select python.exe directly; Windows virtual environments keep it in Scripts, and Linux/macOS environments use bin/python. PyCForge's About dialog shows the exact interpreter under Distribution → SDK Python.

The SDK and PyCForge can use separate Python environments. Searches check known locations without scanning entire drives. Environments kept elsewhere can be selected manually. Discovery and connection install nothing.

Create your first import

Choose New, select a starter, and give the project a folder and author.
Use Edit extension to complete the project, functions, Help, and test examples. Save your changes before scanning.
Choose Scan and follow its findings. The scanner shows whether the project needs editing, verification, or is ready to package.
Choose Verify fixtures to compile and run the saved test examples. Install a C compiler supported by the selected engine before this step.
Choose Package after verification passes. Packaging checks that the project, documentation, tests, and tools still match the verified result.
Register the package through the SDK's Tools menu or PyCForge's Register Conversion Imports dialog. Select Runtime in PyCForge and use *import your_namespace as alias in the source you want to convert.

Building a package and registering it are separate actions. A registered package's Import Help explains its exact supported operations and examples.

Conversion coverage

The connected engine determines the available operations and their rules. With PyCForge 1.3.88, the supplied starters cover four useful families. Earlier engines expose their own supported choices:

Family	What you can define
Scalar operations	Numeric functions and constants, documented input and result types, checked numeric limits, and supported optional or named parameters. Starters include scalar math and independent named-parameter examples.
Array operations	One-dimensional finite `float64` arrays: creation, copies, addition, subtraction, multiplication, division, negation, absolute value, square root, concatenation, and minimum/maximum values or their first matching indices. Current engine profiles also offer bounded pairwise sum and mean. Starters include NumPy and an independent vector namespace.
Structured-value codecs	JSON loads and dumps with Unicode escaping, explicit separator options, lists/tuples and string-key dictionaries. The bounded profile uses int64, finite float64, at most 64 nested containers and 1 MiB of text; hooks and streams are unsupported. Starters include JSON and an independent record namespace.
Unicode text operations	Trim character sets or whitespace, split text into tokens, and join lists/tuples of strings. Supports Unicode including NUL, optional and named arguments, independent results, and checked Runtime work/allocation limits. The text-starter supplies an independent namespace; regex, normalization and generic iterators are outside this contract.

Array, text and structured-value definitions use four ordinary fields: operation identity, exported name, operation choice, and summary. PyCForge supplies their signatures, storage, and cleanup rules. Authors provide the explanations and test cases.

Open Engine reference → Conversion coverage in the desktop to browse the selected engine's families, authoring profiles, operation signatures, limits, and starter projects. Search for an operation or inspect its profile. The same information is available through coverage and SDK.coverage(). Older engines that omit family coverage retain their available forms and starters; the SDK labels the missing information instead of inferring support.

You can create additional library namespaces using supported operations; the SDK is not limited to math and NumPy. Each function must map to an available conversion implementation. Each package declaration selects one family; applications can compose several registered namespaces. Registering a library name does not make all of that Python library convertible. Multidimensional arrays, views, general broadcasting, other array data types, and arbitrary native dependencies are outside the supplied array contracts. Engine reference and Import Help describe the exact boundaries.

Command line and AI automation

Use pycforge-sdk --json discover to list validated engine installations. Add discover --location "/path/to/environment" to check a specific location. Python clients can call discover_engines() from pycforge_sdk for the same structured result; discovery does not replace the reference cache. Use the workbench command or SDK.workbench() to inspect engine-owned forms, bundled imports, and Help through the same public backend.

Start with coverage to see what you can author. Use coverage --profile crucible.text-declaration/0.1 to inspect the text profile when the selected engine advertises it. Add the global --json option for the versioned data.coverage report. Profile identifiers and operation choices come from the engine; a successful browse is not fixture verification or packaging approval. Cached results carry an offline connection state.

Use the command line from scripts or AI development tools. Replace /path/to/engine/python with the interpreter containing PyCForge; quote paths that contain spaces.

pycforge-sdk --engine-python /path/to/engine/python connect
pycforge-sdk --engine-python /path/to/engine/python templates
pycforge-sdk --engine-python /path/to/engine/python new ./cube-root --author "Your name"

The default starter demonstrates a cube-root conversion. Edit its project.json, documentation, test sources, and expected results for your intended use. Then run:

pycforge-sdk --engine-python /path/to/engine/python scan ./cube-root
pycforge-sdk --engine-python /path/to/engine/python verify ./cube-root --compiler gcc
pycforge-sdk --engine-python /path/to/engine/python readiness ./cube-root --compiler gcc
pycforge-sdk --engine-python /path/to/engine/python build ./cube-root --compiler gcc --output ./cube-root.pcfplugin

Register the result explicitly with register ./cube-root.pcfplugin, using the same engine selection. Use methods and describe ArrayFunction to explore the engine reference, or new --template TEMPLATE_ID to select another starter.

Pass --json before a command to receive structured results, diagnostic codes, and field locations. AI tools can inspect these results, correct project data, and repeat the same scan, verify, and package workflow used by a human author. Treat a nonzero exit code as an unsuccessful operation; do not infer approval from descriptive text. With --json, an invalid command returns SDK_ARGUMENT. A failed native fixture includes its case location and the path to the saved report. Use describe ValueFunction to inspect the connected engine’s structured-value operations. Use describe TextFunction for text choices and signatures. An unknown coverage profile returns SDK_COVERAGE_PROFILE with the available profile identifiers and a remedy; invalid arguments return SDK_ARGUMENT.

Python API

Use the same SDK service directly from Python. This example lists the starter projects available from the selected engine:

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 template in result.data["templates"]:
    print(template["id"], template["description"])

The API also provides project creation and editing, inspection, conversion, verification, packaging, and registration. Each operation returns an Outcome with an ok flag and structured results. Human and AI clients use the same checks; authors remain responsible for the intended behavior and expected test results.

Help and practical requirements

Press F1 for the searchable guide and conversion-import manuals supplied by the connected PyCForge. The topic list follows the engine's bundled imports. A small getting-started guide remains available before connection. Engine reference explains available methods, parameters, results, and examples. Cached reference remains available when the engine cannot be reached; conversion, verification, and packaging require a compatible connected engine.

Native fixture verification follows the selected engine's supported host and compiler profile. The supplied profile currently supports Linux with a GNU-style C compiler. Desktop browsing and project editing do not require running native tests. Verify fixtures explicitly compiles and executes the declared examples; browsing the reference and scanning project data do not run them.

Passing verification means the declared test cases matched their expected results. It does not establish correctness for every possible input or platform. Changes to project data, Help, tests, or the selected tools require verification again before packaging. For PCFC11, select PyCForge 1.3.85 or later and PCFC11 0.2.32 or later with the supported backend query. Verification records the selected external GCC path and its SHA-256. If the path or file changes, or GCC is missing, restore or select the intended backend and run Verify fixtures again. Earlier compatible engines can use GCC directly. Review the package's documented limits when using its conversion imports.

License

PyCForge SDK is free software under the GNU General Public License v3.0 only. The distribution includes LICENSE.