PseudoSmith

Turn structured pseudo-code into production-ready, idiomatic source.

PseudoSmith is an AI skill that translates UAB blueprints — a hybrid of rigid structural anchors and free-form natural language — into clean, idiomatic code for the language and platform you specify. It is an interpreter of intent, not a compiler. You describe what you want with as much or as little structure as you like; PseudoSmith bridges the gap between intent and working code.

What is UAB?

UAB (Universal Architectural Blueprint) is the input format PseudoSmith reads. It is not a formal programming language — it is a lightweight frame for an engineer to think and work in. A blueprint mixes two things:

• Structural anchors — capitalized, recognizable tokens (FUNCTION, CLASS, IF, BUTTON, DATABASE.QUERY, …) that give the AI clear guardrails and structure.
• Natural language — plain English describing behavior ("remove spaces and hyphens", "reverse the string", "show an error if the length is wrong").

Anchors are recommendations, not requirements. They exist to help both the engineer and the AI stay aligned. You can lean on them heavily for precision, or barely at all and let natural language carry the intent. PseudoSmith interprets the combination.

/*
 TARGET_LANGUAGE     : Python
 TARGET_PLATFORM     : linux_x86
 TARGET_UI_FRAMEWORK : Tkinter
 DELIVERY_MODE       : inline
*/

MODULE "CCValidator"
  PROCEDURE validateCardNumber(cardNumberString: STRING) -> BOOLEAN
    START
        // Remove spaces and hyphens, then reverse the string
        cleanString    = remove spaces and hyphens from cardNumberString
        reversedDigits = reverse the string cleanString
        ...
    END
END MODULE

The UAB header

Every blueprint begins with a header enclosed in a /* ... */ block. The header is the control plane for translation — it tells PseudoSmith what to build and how. The body describes the logic; the header decides the target.

/*
 ====
 TARGET_LANGUAGE         : Python
 TARGET_PLATFORM         : linux_x86
 TARGET_LANGUAGE_VERSION : >=3.11
 MEMORY_MODEL            : garbage_collected
 CONCURRENCY_MODEL       : async_await

 DATABASE_PROVIDER       : postgresql
 DATABASE_ACCESS         : async
 DATABASE_DRIVER         : asyncpg

 TARGET_UI_FRAMEWORK     : none

 STYLE_GUIDE             : ./styleguide.md
 NAMING_CONVENTIONS      : snake_case
 INDENTATION             : spaces:4

 GENERATE_UNIT_TESTS       : FALSE
 GENERATE_DOCSTRINGS       : FALSE
 GENERATE_DEPENDENCY_GRAPH : FALSE
 DETECT_DEAD_CODE          : FALSE

 DELIVERY_MODE           : archive
 ====
*/

Required fields

Optional core fields

Conditional fields

These become required when the blueprint implies them, and PseudoSmith will pause and ask rather than choosing silently:

Optional feature flags (opt-in)

Off by default — set the parent flag to TRUE to enable:

Value lists are extensible. Unlisted or custom:<name> values are accepted whenever PseudoSmith can reasonably generate for the target. If a value materially affects implementation and there isn't enough information to proceed safely, it pauses and asks.

Anchors vs. natural language: three styles

Anchors are optional. The same program can be expressed anywhere on a spectrum from almost pure structure to almost pure prose — PseudoSmith interprets the mix. Below, the same feature (validate a credit-card number) is written three ways.

1. Anchor-heavy — maximum structure

Best when you want tight control over shape, types, and flow.

/* TARGET_LANGUAGE: Python   TARGET_PLATFORM: linux_x86 */

MODULE "CCValidator"
  PROCEDURE validateCardNumber(cardNumber: STRING) -> BOOLEAN
    START
        clean: STRING = STRIP(cardNumber, " -")
        IF LENGTH(clean) < 13 OR LENGTH(clean) > 19 THEN
            RETURN FALSE
        ENDIF

        sum: INT   = 0
        alt: BOOL  = FALSE
        FOR digit IN REVERSE(clean)
            d: INT = TO_INT(digit)
            IF alt THEN
                d = d * 2
                IF d > 9 THEN d = d - 9 ENDIF
            ENDIF
            sum = sum + d
            alt = NOT alt
        ENDFOR

        RETURN (sum MOD 10) == 0
    END
END MODULE

2. Balanced — anchors for shape, prose for behavior

The typical sweet spot: anchors fix the skeleton, natural language fills the steps.

/* TARGET_LANGUAGE: Python   TARGET_PLATFORM: linux_x86 */

MODULE "CCValidator"
  PROCEDURE validateCardNumber(cardNumber: STRING) -> BOOLEAN
    START
        // strip spaces and hyphens; reject if not 13-19 digits
        clean = remove all spaces and hyphens from cardNumber
        IF clean is not between 13 and 19 digits THEN
            RETURN FALSE
        ENDIF

        // standard Luhn checksum over the digits
        RETURN clean passes the Luhn check
    END
END MODULE

3. Prose-heavy — minimal structure

Best for quick intent capture; PseudoSmith infers the structure.

/* TARGET_LANGUAGE: Python   TARGET_PLATFORM: linux_x86 */

MODULE "CCValidator"

Write a function validateCardNumber that takes a card number string and returns true or
false. Ignore spaces and hyphens. Reject anything that isn't 13 to 19 digits long. Otherwise
return whether it passes the standard Luhn checksum.

All three produce equivalent, idiomatic output. The difference is how much you decide explicitly vs. how much you delegate — and the more you leave to prose, the more likely a material gap is surfaced at the ambiguity checkpoint.

Core principles

• Interpreter of intent, not a compiler. PseudoSmith realizes your design; it does not invent architecture, security policy, frameworks, or product scope on your behalf.
• Scope fidelity. It fully realizes what you asked for — inferring routine helpers, error handling, glue code, and platform-native equivalents — but it will not silently add unrequested features, external services, auth flows, storage engines, CI/CD, or UI screens.
• Material ambiguity is surfaced, not guessed. When a missing detail would materially change architecture, persistence, security, dependencies, public interfaces, UI framework, or platform compatibility, PseudoSmith pauses and asks rather than choosing for you.
• Security is engineer-owned. It translates the security mechanism you specify; it never substitutes a different one silently. Under-specified security-sensitive behavior is flagged.
• Every translation produces an Implementation Report documenting decisions, inferences, substitutions, risks, and TODOs — so nothing material happens invisibly.

How it works

1. Header check — confirms the required header fields (TARGET_LANGUAGE, TARGET_PLATFORM) and any conditionally-required fields (e.g. DATABASE_PROVIDER, TARGET_UI_FRAMEWORK).
2. Material ambiguity checkpoint — runs once per session; raises only genuinely architecture-changing gaps, then proceeds.
3. Translate — generates idiomatic source for the target language/platform, preserving your comments and respecting your declared dependencies.
4. Platform compatibility audit — swaps non-native APIs for platform-correct equivalents and records the substitution.
5. Implementation Report — delivered as a distinct artefact alongside the code.

Optional, opt-in features: unit tests, docstrings, dependency graphs, and dead-code detection — each enabled only via its header flag.

Supported targets

Languages: Python, C, C++, C#, Java, Kotlin, Swift, JavaScript, TypeScript, VBA, PHP, Rust (and others — the value lists are extensible).

UI frameworks: Tkinter, WinForms, WPF, Avalonia, MAUI, SwiftUI, UIKit, AppKit, Swing, JavaFX, Android Compose, React, Qt, GTK, and more.

Databases: SQLite, Postgr