API Reference

Complete Python API for the SYNTHOS assistant, all 7 layers, the STC cipher, and model evaluation.

SynthosAssistant

synthos.assistant

SynthosAssistant(config=None, verbose=None)

Create the full assistant with all 7 layers, crypto, and conversation history.

Returns: SynthosAssistant

.process(user_input: str) → str

Process one message. /commands are dispatched; everything else flows through the 7-layer pipeline.

Returns: str — assistant response

.get_status() → dict

Return subsystem summary: primitive count, lattice cells, concepts, coherence, memory, etc.

Returns: dict

.history

List of {role, content} conversation turns.

Returns: list[dict]

CLI Commands

synthos.cli

synthos

Launch the interactive TUI (default command).

synthos chat

Headless Rich REPL.

synthos encrypt TEXT [-k KEY] [-m MODE] [-o FILE]

Encrypt plaintext with STC. Generates key if omitted.

Returns: hex ciphertext

synthos decrypt HEX -k KEY [-m MODE] [-o FILE]

Decrypt an STC envelope.

Returns: plaintext

synthos eval [-s SUITE] [--json]

Benchmark configured model endpoints.

Returns: leaderboard table

synthos status

Print pipeline status table.

synthos config [--edit]

Show or edit ~/.config/synthos/config.yaml.

-v / -vv

Increase verbosity (normal / verbose). Stackable.

PrimitiveRegistry (L0 LPE)

synthos.layers.lpe

PrimitiveRegistry()

Load all 48+ built-in primitives.

Returns: PrimitiveRegistry

.get_primitive(id: str) → Primitive

Lookup by ID (e.g. 'P001').

Returns: Primitive

.search_primitives(query: str) → list

Fuzzy search by name/description.

Returns: list[Primitive]

.get_primitives_by_type(ptype: PrimitiveType) → list

Filter by category.

Returns: list[Primitive]

.validate_regex_syntax(pattern: str) → (bool, str)

Check if a regex compiles.

Returns: tuple

GeometricParseLattice (L1 GPL)

synthos.layers.gpl

GeometricParseLattice(rows=4, cols=4)

Create lattice with default cells.

Returns: GeometricParseLattice

.traverse_lattice(input: str) → dict

Route input through the lattice. Returns path, matches, captures.

Returns: dict

.add_cell(cell: LatticeCell)

Add a custom cell.

Returns: None

.visualize_lattice() → str

ASCII visualization.

Returns: str

.get_lattice_statistics() → dict

Cell count, connected components, etc.

Returns: dict

SemanticConstructManifold (L2 SCM)

synthos.layers.scm

SemanticConstructManifold()

Create empty manifold.

Returns: SemanticConstructManifold

.extract_concepts_from_text(text: str) → list

Find CamelCase concepts.

Returns: list[ConceptNode]

.extract_relations_from_text(text: str) → list

Find → ⊂ ≡ etc. relations.

Returns: list[RelationEdge]

.activate_concept(id: str, strength: float)

Set activation and propagate.

Returns: None

.get_manifold_topology() → dict

Summary stats.

Returns: dict

TopologicalAttentionMesh (L3 TAM)

synthos.layers.tam

TopologicalAttentionMesh(num_heads=8)

Create mesh with default heads.

Returns: TopologicalAttentionMesh

.multi_head_attention(text: str) → dict

Run all heads. Returns concatenated output and per-head results.

Returns: dict

.add_attention_head(head: AttentionHead)

Register a custom head.

Returns: None

RecursiveGrammarEngine (L4 RGE)

synthos.layers.rge

RecursiveGrammarEngine()

Load built-in SYNTHOS grammar.

Returns: RecursiveGrammarEngine

.parse(text: str, rule: str) → ParseTree | None

Parse text starting from rule.

Returns: ParseTree or None

.validate_grammar() → dict

Check for undefined refs, unreachable rules.

Returns: dict

.add_production_rule(rule: ProductionRule)

Add a custom rule.

Returns: None

StateCrystallizationField (L5 SCF)

synthos.layers.scf

StateCrystallizationField(tensor_shape=(4,4))

Create field with given tensor dimensions.

Returns: StateCrystallizationField

.crystallize_match(pattern, match, layer) → tuple

Store a regex match in the tensor.

Returns: (layer, row, col)

.compute_coherence() → float

Check backreference consistency.

Returns: float 0–1

.apply_gate_conditions() → bool

Evaluate output gate rules.

Returns: bool

.visualize_tensor() → str

ASCII tensor display.

Returns: str

OutputProjectionSurface (L6 OPS)

synthos.layers.ops

OutputProjectionSurface()

Create surface with default chains and templates.

Returns: OutputProjectionSurface

.process_input(text, chain_name) → str

Run text through a substitution chain.

Returns: str

.render_template(type, vars) → str

Render an ASCII template.

Returns: str

.route_output(intent, vars) → str

Map intent to template and render.

Returns: str

SymbolicTopologyCipher

synthos.crypto.stc

STCKey.generate() → STCKey

Random 256-bit key.

Returns: STCKey

STCKey.from_passphrase(pass, salt) → STCKey

PBKDF2-SHA256 derivation (600k rounds).

Returns: STCKey

STCKey.from_hex(hex: str) → STCKey

Load from hex string.

Returns: STCKey

SymbolicTopologyCipher(key, mode, verbose)

Create cipher. Modes: ECB, CBC (default), CTR.

Returns: SymbolicTopologyCipher

.encrypt(plaintext, authenticate=True) → bytes

Encrypt with PKCS#7 padding and optional HMAC.

Returns: bytes envelope

.decrypt(envelope) → bytes

Decrypt and verify.

Returns: bytes plaintext

ModelBenchmark

synthos.eval.bench

ModelBenchmark(models, suites, concurrency, timeout, verbose)

Create benchmark runner.

Returns: ModelBenchmark

.run() → list[BenchResult]

Run all evals synchronously.

Returns: list[BenchResult]

ModelBenchmark.leaderboard(results) → str

ASCII leaderboard table.

Returns: str

ModelBenchmark.to_json(results) → str

JSON serialization.

Returns: str

BenchResult.score() → float

Composite: 0.35·quality + 0.30·speed + 0.20·coherence + 0.15·cost_eff.

Returns: float