Metadata-Version: 2.4
Name: pycforge-sdk
Version: 0.7.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.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:

```sh
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

1. Choose **New**, select a starter, and give the project a folder and author.
2. Use **Edit extension** to complete the project, functions, Help, and test
   examples. Save your changes before scanning.
3. Choose **Scan** and follow its findings. The scanner shows whether the project
   needs editing, verification, or is ready to package.
4. Choose **Verify fixtures** to compile and run the saved test examples. Install
   a C compiler supported by the selected engine before this step.
5. Choose **Package** after verification passes. Packaging checks that the project,
   documentation, tests, and tools still match the verified result.
6. 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.

```sh
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:

```sh
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:

```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 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`.
