Separan

Structure should be named, not guessed.

Free programmers from indentation and bracket ambiguity.

AI may write the code. Humans still need to understand it.

日本語 | English

Separan makes AI-written code easier for people to read, understand, and review. Labels turn otherwise anonymous control flow into visible intent: :validate_payment, :write_audit_log, and :retry_connection become part of the program's checked structure. A reviewer can understand what a block is for, navigate its exact boundary, and verify where an AI made changes without first reconstructing indentation or counting brackets.

This is not only about restricting AI. It is about making generated code explain its structure to the human who remains responsible for it.

Run it in 30 seconds

git clone https://github.com/mocchii2/Separan.git && cd Separan
python -m pip install separan
separan examples/hello.sep

Python 3.10 or newer is required.

Try it in five minutes

First, run a valid labeled block:

if true :check
print "ok"
endif:check

Then run the intentionally broken example:

python -m separan examples/label_mismatch.sep

The closer names a different structure:

if true :check
print "ok"
endif:wrong

Separan points to the structural mistake and tells you the exact closer it expected:

SEPARAN E104: Block label mismatch

 --> demo.sep:3:7
  |
3 | endif:wrong
  |       ^^^^^

The closing or branch label must match its opening block.

Expected:
endif:check

Actual:
endif:wrong

Opened here:
 --> demo.sep:1:10
  |
1 | if true :check
  |          ^

That diagnostic is the language in miniature: structure is named and verified, not inferred from indentation or bracket counting.

Separan is a label-structured scripting language designed for code that humans, AI systems, and development tools can inspect without guessing where a block ends. Indentation is decoration. Every block carries an explicit identity, and its opener and closer must agree.

function:main
name = "Separan"

if name != null :名前あり
print "Hello, " + name
endif:名前あり

end_function:main

Block and multiline-comment labels accept NFC-normalized Unicode identifiers. Program identifiers such as variables and function names remain ASCII-only.

Separan rejects structural mistakes before they can silently succeed:

if user.active :active_user
print "active"
endif:admin_user

SEPARAN E104: Block label mismatch

 --> demo.sep:3:7
  |
3 | endif:admin_user
  |       ^^^^^^^^^^

The closing or branch label must match its opening block.

Expected:
endif:active_user

Actual:
endif:admin_user

Opened here:
 --> demo.sep:1:17
  |
1 | if user.active :active_user
  |                 ^

The 30-second demo

Separan gives a meaningful name to the structure an AI is allowed to edit:

if user.active :active_user
print "active user"
endif:active_user

Give the AI a structural instruction instead of a line-number range:

Modify only Separan scope function:main#1/if:active_user#1

The parser verifies that the opening and closing structure agree. The v0.4 review tool extends that identity to the diff boundary:

PASS: AI edit scope verified.
Allowed changes 1, violations 0

The label is simultaneously human documentation, parser-checked structure, and a machine-verifiable edit boundary.

Function tags add a second, semantic dimension when related code is separated:

function:send_notification
@notification
@aws
send_message()
end_function:send_notification

@notification is AST metadata, so tools can enumerate the exact function set instead of asking an AI to guess what “notification-related” means.

separan-structure diff before.sep after.sep
separan-structure verify before.sep after.sep --allow active_user
separan-structure inspect . --tag notification
separan-structure verify before.sep after.sep --allow-tag notification

Use --json for CI and review bots. The VS Code v0.4 extension can compare the active file against Git HEAD and verify the label under the cursor. See the structural AI workflow.

v0.2.0-alpha.7

The current Python reference implementation includes strict label validation, detailed diagnostics, fixed inferred types, homogeneous lists, functions, main auto-start, conditionals, loops, #/## comments, strict escaped and raw strings, Function Tag metadata, and AST output. The v0.4 tooling layer adds a dependency-free LSP, rich VS Code support, structural diffs, and enforced AI edit scopes without changing v0.1 language semantics.

The standard library now covers explicit type conversion, Unicode string and homogeneous-list processing, immutable bytes, datetime and duration values, reproducible and secure randomness, filesystem and process utilities, HTTP client/server previews, authentication, capability-gated mail, YAML/XML structured data, cookies, parameter-bound SQLite, and capability-checked embedded board profiles. Built-ins use the same strict argument and type diagnostics as user-defined functions; implicit coercion remains forbidden.

One source, multiple embedded boards

The embedded preview supports Raspberry Pi Pico/Pico W/Pico 2/Pico 2 W and Arduino Nano/Nano Every through reviewed board profiles. The portable Blink example names the board LED instead of copying a physical pin number:

function:main

@embedded
@gpio
@sample

gpio_set_mode(pin.LED_BUILTIN, "output")

while true :blink_loop
gpio_write(pin.LED_BUILTIN, true)
delay_milliseconds(500)
gpio_write(pin.LED_BUILTIN, false)
delay_milliseconds(500)
endwhile:blink_loop

end_function:main

The source stays identical; only the build target changes:

separan build examples/embedded/01_blink.sep --board raspberry_pi_pico
separan build examples/embedded/01_blink.sep --board raspberry_pi_pico_w
separan build examples/embedded/01_blink.sep --board arduino_nano
separan build examples/embedded/01_blink.sep --board arduino_nano_every

pin.LED_BUILTIN resolves through the selected profile to Pico GPIO25, the Pico W wireless-controller LED, or the Nano-family board LED definition. The current command validates the complete pin/capability mapping; firmware code generation remains the next backend step.

The official embedded examples now cover portable Blink, button input, PWM fade, analog input, UART echo, and I²C scanning. The separate 01_blink_d13.sep example is intentionally board-specific: use pin.LED_BUILTIN for portable code and pin.D13 only when the target profile defines D13 with the required capability.

Higher-order collection processing uses explicit function values: map, filter, and initial-value-required reduce preserve strict callback contracts. One-level flatten, sum, average, and value count complete the core aggregates. Readable mathematics includes explicit root/log names, statistics, moving averages, base conversion, and grouped binary/octal/hexadecimal literals, with domain errors instead of silent NaN/Infinity results.

String processing includes trim, upper, lower, contains, starts_with, ends_with, split, join, replace, code-point-based substring/char_at, non-overlapping literal find_all, and a string/list-shared reverse.

The experimental temporal implementation provides distinct datetime, local_datetime, timezone, and duration values. It requires explicit zones, rejects ambiguous DST wall times, and keeps Unix units visible in function names. Run separan --timezone-version to inspect the active timezone database.

Randomness is split by purpose: seeded random_* functions use a reproducible language-defined PCG32 stream, while secure_random_* functions use the operating system's cryptographic source. Secure bytes have a distinct bytes type rather than masquerading as a number list.

Binary values are immutable and never convert to strings implicitly. Explicit UTF encodings, strict hex/Base64 codecs, slicing, byte lookup, and binary concatenation are available in the reference preview.

Authentication and cryptography use safe-purpose APIs rather than user-built cipher constructions. Host-provided secrets are a distinct automatically redacted type; HTTP auth, OAuth client credentials, HMAC, HS256 JWT, and Argon2id password hashing have experimental reference implementations.

The cryptography preview adds SHA-2/SHA-3 digests, SHA-256/SHA-512 HMAC, explicit bytes-to-hex/Base64 conversion, constant-time comparison, Argon2id key derivation, and versioned AES-256-GCM authenticated encryption. Keys cannot be strings, nonces are generated internally, decrypted secrets remain redacted, and obsolete or unauthenticated ciphers are omitted.

The mail preview composes provider-independent UTF-8 messages with To/Cc/Bcc, text/HTML bodies, file or bytes attachments, and inline content. An explicit sender selects verified STARTTLS/implicit-TLS SMTP or optional Amazon SES; credentials stay secret, Bcc never enters MIME headers, and a separate host capability controls mail delivery and address allowlists.

The structured-data preview adds strict YAML 1.2-style data conversion and a separate XML document model. YAML preserves object order, rejects duplicate keys and heterogeneous sequences, and supports multi-document streams. XML keeps elements, attributes, namespaces, and text explicit while rejecting DTD and entity declarations by default.

HTTP supports one-shot cookies and explicit stateful Cookie Jars. Cookie values, jar display, and received response cookies are redacted; domain, path, expiry, and Secure attributes control transmission.

Lists are homogeneous and zero-based. Operations such as list_append, list_remove, slice, reverse, and every sort return new lists; v0.1 exposes no mutating collection API. Stable sorting includes descending, Unicode case-folded, natural-number, and object-field variants. See the list specification.

length(value) and is_empty(value) work consistently across strings, lists, and bytes. String search, repetition, and padding operate on Unicode code points; failed index_of and last_index_of searches return null.

const name = value creates an immutable binding while ordinary assignment remains mutable. Labeled object/list data blocks, namespaced imports, capability-based I/O, explicit JSON boundary conversion, and labeled try/catch/finally handling are all available experimentally in the reference interpreter.

The accepted HTTP design keeps http_get lightweight and puts detailed status, headers, and bytes in http_request. It explicitly does not impersonate a browser: JavaScript, DOM, viewport, and navigator state belong to a future browser_open subsystem. The reference preview implements both APIs behind an explicit network capability with host, scheme, port, redirect, timeout, and body-size checks. Labeled HTTP routes and a separately capability-gated development host are also available as a server preview. The dispatcher is transport-independent so a future Lambda or production adapter can reuse the same .sep application. The database preview separates its common API from official SQLite, PostgreSQL, MySQL, Oracle, and Microsoft SQL Server adapters. SQLite is built in; the other four are optional extras. Safe ? placeholder scanning, strict single-row and scalar APIs, labeled transactions, common metadata, and redacted connections are available. Stable execution metadata is available through the reserved read-only system context; dynamic values such as time, requests, randomness, and database state remain explicit functions or scoped values.

The v0.5 Structure Explorer turns the active .sep file into a navigable block tree. Each named structure shows its direct parameters, reads, writes, and calls, plus added/modified/removed state against Git HEAD. Selecting a block jumps to its opener; moving the cursor tracks the deepest enclosing scope. The analysis is parser-backed and never executes the program. See the Structure Explorer specification.

The Language Server preview is available as separan-lsp. It provides parser and simple fixed-type diagnostics, mismatch Quick Fixes, typed Semantic Tokens, Hover, definition, scope-safe label rename, matching highlights, completion, signature help, inlay hints, labeled symbols/folding, and AST-preserving formatting. See the VS Code/LSP specification.

The strict operator set includes power, integer floor division, null fallback, compound assignment, and typed membership. See examples/operators.sep and the language specification.

External commands follow the same explicitness rule: exec passes a program and argv directly, exec_checked turns nonzero exit into a catchable error, and the separately gated shell_exec is the only API that interprets shell syntax. These process APIs now have an experimental capability-gated implementation.

The utility implementation provides versioned Unicode regexes, deterministic capability-gated glob, process-scoped environment access, and command-line helpers that keep script_path() separate from command_args(). An experimental implementation of these APIs and named function arguments is available in the reference interpreter.

Labeled object:name and list:name data blocks, user.name member access, namespaced imports, and labeled try/catch/finally/throw also have experimental reference implementations.

Monitoring dogfooding model

The runnable Separan Monitor model turns mock EC2, log, and job events into either simulated delivery or a reason-bearing suppression record. It demonstrates the four-module notify/logcheck/status/normal_check boundary, fixed suppression order, deduplication, and complete notification-candidate history using Separan code. AWS deployment is deliberately kept outside the example until strict YAML and typed AWS capability adapters exist.

python -m pip install -e .
separan examples/hello.sep
separan --ast examples/if.sep
python -m unittest discover -s tests -v

The suite currently contains more than 1,700 tests. Its dedicated negative conformance corpus checks syntax, structure, type and runtime failures, plus too few, too many, and unknown named arguments across every registered built-in.

Python 3.10 or newer is required.

Repository

Separan/
├─ spec/        Language specification
├─ reference/   Python reference implementation
├─ tests/       Conformance and diagnostic tests
├─ examples/    .sep programs
├─ vscode/      VS Code extension
├─ docs/        Philosophy and AI integration
├─ logo/        Official Separan logo and mark
├─ ROADMAP.md
└─ LICENSE

Brand assets are available as the full Separan logo and square Separan mark. The original PNG files are kept unchanged in the repository. A separately optimized 128px derivative is used as the VS Code extension icon.

Read the language specification, the design philosophy, the AI integration model, the temporal-type specification, and the roadmap. The experimental database standard documents the common API and official SQLite, PostgreSQL, MySQL, Oracle, and SQL Server adapters. The reserved system context defines normalized, read-only execution metadata and its namespace boundary. The experimental embedded board mapping adds reviewed logical-pin profiles for Raspberry Pi Pico/Pico 2 and Arduino Nano/Nano Every, plus static separan build --board capability validation. Firmware generation is not yet included.

Status

Separan is experimental software at v0.2.0-alpha.7. The syntax and diagnostics may change before v1.0. It is ready for exploration, not production use.

License

Separan is licensed under the Apache License 2.0. See NOTICE for attribution information.