Build conversion extensions through the same backend used by the Python API and console.
The copper connection panel identifies the live engine and its reference. Refresh reloads compatible capabilities after updating PyCForge. Engine and tools contains the interpreter, Find installed, This Python and the compiler used for explicit native verification. The SDK and engine may use separate environments. PyCForge’s About → Distribution → SDK Python shows its exact interpreter. Windows environments normally use Scripts/python.exe; Linux/macOS uses bin/python. A wheel or installer is not a running environment.
Discovery checks known locations without scanning drives: the SDK’s Python, active environments, Python directories on PATH, registered Windows Python installations, common virtual environments, Conda environments and pipx installations. Unusual locations may need Locate. Searches have time and candidate limits; Activity records checked candidates and failures. An explicit --engine-python selection is checked without silently substituting another installation. A failed selection does not replace the last working connection.
Command-line clients can use pycforge-sdk --json discover, optionally with --location. Python and AI clients use pycforge_sdk.discover_engines() for the same result. SDK.connect(offline=True) reads cached reference without probing an interpreter. Discovery checks live support files and compatible interfaces; cache data alone cannot authorize execution.
This guide, the bundled conversion-import manuals, authoring fields, operation choices and starter projects are supplied by the selected PyCForge installation. Use the Help topic selector to read each bundled import’s exact conversion coverage. Updating PyCForge and refreshing the SDK replaces this information together.
The installed Crucible landscape contains index.json, api.xml, authoring.json, workbench.json, workbench.schema.json and the listed HTML guides. The manifest binds every resource by size and hash. The workbench contract describes authoring forms and Help without executable UI plugins or a fixed list of library names. The engine remains responsible for conversion semantics and validation. Compatible additions use the same SDK; a new required contract feature or incompatible major version requires an explicit SDK update.
Four public authoring families are available. Compatibility profile revisions and workflow commands are not additional conversion families. Runtime methods outside these published choices cannot be added merely by naming them in a declaration.
| Family | Conversion coverage | Starting point |
|---|---|---|
| Scalar | One to four numeric inputs; float64, bool or int64 results; declared native math symbols or reviewed composite kernels. | scalar-cube-root, named-scalar, math-scalar |
| Array | Owned one-dimensional float64 arrays: creation, copying, arithmetic, concatenation and bounded reductions. | array-starter, numpy-array |
| JSON | Reviewed decoding and encoding of bounded structured values. | value-starter, json-values |
| Text | Unicode trimming, splitting, literal replacement and joining lists/tuples of strings, including named and optional arguments. | text-starter; text-replacement-starter |
Use the independent starters to choose your namespace and export names. For text, the starter exposes trim(text, chars=None), tokens(text, sep=None, maxsplit=-1) and join(sep, items). For example, compose t.join(" | ", t.tokens(t.trim(text))) after declaring *import cleantext as t. The engine supplies signatures, Unicode rules, allocation and work budgets, and cleanup; authors supply identity, names, explanations and meaningful fixtures.
Text accepts Unicode-scalar strings, including NUL. Join accepts only lists and tuples of strings. Literal split separators preserve empty fields; None groups Unicode whitespace. Strip removes a character set. Invalid types and an empty separator produce catchable errors; Runtime budget exhaustion is fatal. Inputs are unchanged, results own independent storage, failed calls release partial allocations, and live roots are required at collection boundaries.
Unsupported public authoring areas include arbitrary C injection, custom native dependencies, author-defined object layouts and callbacks, regex and normalization, streams, two-dimensional arrays, views and general broadcasting. Each family has further operation-specific limits in its displayed contract. The built-in default imports remain math, NumPy and JSON.
AI tools receive the same structured outcomes as the GUI: top-level status and diagnostics, documentation field paths, fixture source/report details, compiler stderr, and expected/actual comparisons. A stale engine, compiler, source, documentation or expectation requires fresh verification. This workflow supports correction; it is not proof that an AI-generated extension is correct for untested inputs.
Needs attention: authoring fields, Help or required fixtures need correction.
Ready to verify: authoring checks pass, but native results have not been established.
Verification needed: evidence is missing, failed, incomplete, canceled or no longer matches the project or environment.
Ready to package: every required fixture passes, every export and its linked Help example is covered, and exact project, SDK, engine, compiler and host identities match.
Scan never compiles or executes fixture programs. When checking existing evidence, it runs the compiler's version command to confirm identity. After matching evidence, the engine validates the archive in memory, including metadata; Scan writes no package file. Build repeats the same evidence gate before replacing output.
Readiness is an unsigned, local workflow result for these explicit fixtures. Source-call coverage does not prove every branch ran or every input is correct. Authors remain responsible for expected results and explanations.
Run pycforge-sdk --engine-python ENGINE_PYTHON --json templates to see starter IDs from the selected installation. Use workbench for installed defaults, operation choices, signatures and Help. Browsing uses inert reference data. Check the returned connection state before starting work.
A successful scan means the saved project can go to verification. Run verify explicitly and inspect every failed case under data.report.cases, including compiler_stderr and expected and actual output. Only readiness with data.readiness.state equal to ready-to-package approves the saved project for packaging. build checks again. The console returns a nonzero exit code for unsuccessful operations.
Array, text and structured-value forms have four fields: stable identity, editor name, operation and summary. The engine supplies signatures, types, storage and cleanup. Read the displayed operation contract before choosing it. Scalar details are in More contract settings.
Help needs an overview, usage, limitations, release notes, parameter meanings, return meaning, details and a native example for every function. Every constant needs an explanation. Tools → Add missing Help fields preserves existing prose and adds blank fields for you to complete.
Fixtures records exact expected stdout, stderr and exit code, or an expected conversion diagnostic. Save project edits before opening Edit fixture source. Source saves are separate atomic changes. Advanced project data edits the full JSON document; create new fixture files in the project before referencing them there.
Changing project fields, Help, source or expectations clears readiness. Save, scan and verify again. Changing engine or compiler clears approval. Outside file changes require Reload from disk; conflicting saves preserve existing files. Results arriving after editor changes cannot approve newer edits.
A failed refresh preserves valid cached reference with an OFFLINE label. It cannot approve conversion, verification, packaging or registration. Viewing starters or method examples never executes them.
Activity contains diagnostics. Fixture results shows each comparison; activate a fixture for expected and actual details. Evidence shows identities, coverage and scope. Failed builds preserve existing packages. Starting verification retires the prior passing report even if canceled.
Closing during work requests cancellation and stays responsive until the worker stops. Process supervision enforces deadlines and output limits. POSIX cancellation stops the process group. Windows direct-process termination remains the inherited limitation; Windows descendant-process qualification is not claimed.
On native x86-64 Linux, choose GCC or the built PCFC11 executable in Engine and tools. On the command line pass its full path with verify PROJECT --compiler PATH. Copy the PCFC11 path from PyCForge’s Build PCFC11 dialog after building it. Use that same executable for readiness and packaging. The engine’s current SDK verification profile lists Linux as its supported host. This engine provides scalar profiles, bounded one-dimensional finite float64 arrays and bounded JSON-value codecs. NumPy includes division, unary transforms, concatenation, extrema and bounded pairwise sum and mean. JSON provides loads and dumps. Choose JSON or the independent structured-data starter to author these codecs through the same verification workflow. General broadcasting, views, other dtypes, external buffers and arbitrary native dependencies remain unsupported. Read the engine reference and extension Help for exact coverage.
In PyCForge, register the conversion package, confirm Ready and select Runtime to use its *import. Packaging and registration do not publish releases. Only CC publishes.
PCFC11 uses an external GCC-compatible driver for assembly and linking. On Linux, SDK 0.6.4 with PyCForge 1.3.85 or later and PCFC11 0.2.32 or later records the selected backend path and SHA-256. Choose the intended GCC with PCFC11_LINUX_CC or use the default on PATH. After a backend change, run Verify fixtures again. A missing backend blocks packaging. SDK 0.6.3 only checks the PCFC11 executable.
Ctrl+N: New; Ctrl+O: Open; Ctrl+S: Save; F5: Scan; F6: Verify fixtures; Ctrl+B: Package; F1: Help. Standard Tab navigation, menu mnemonics and window controls are available.
Choose text-replace for function(text, old, new, count=-1). It replaces non-overlapping literal matches from left to right. Negative count replaces all; zero returns an independently stored copy. Empty old inserts at Unicode scalar boundaries, including both ends. All four arguments accept names; count accepts signed-int64 values and bool. This is Runtime-only text profile 0.2; declarations using only earlier text operations retain profile 0.1. Use text-replacement-starter for a complete independently named package and verification fixtures. Regex and normalization are outside this operation.