Weksa/README.md
Weksa ba42639c3b scene-in-group: rubric r1 and 98 labelled scenes (#77)
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-11-13 08:24:45 +00:00

118 lines
7.7 KiB
Markdown

# Weksa
Weksa is a procedural language engine for alien grammars grounded in concept,
culture, and constraint, and the planned lowerer that turns an agent's
meaning packet into the reader's display language.
**What is valuable here.** The interlingua standard and the lowering design: a
meaning packet owns what is meant, the scene state (live: `weksa scene put|dump`, labelled by the rule in
`docs/scene-annotation.md`; speaker documents are planned) owns the speaker's relation to the addressee, which selects register,
address and politeness, and a lowerer owns surface text and leaves a trace.
**The problem it solves.** An agent's outward speech today is one English
string the model chose, so meaning, register and voice are fused and nobody can
inspect or re-target it. Packets separate them, so the same meaning can be
lowered into English, other languages and conlangs, and the loss can be
measured.
**Entry points.**
- [Interlingua Standard](./docs/interlingua-standard.md): the packet contract.
- `crates/weksa`: the packet, inventory and corpus types, `validate`, the
derived split, the scorer (`score`: chrF, meaning cosine through an Ollama
embedder, whole output against whole reference with no mask, leak diagnostics) and the `weksa` CLI
(`weksa validate`, `corpus`, `entity`, `inventory`, `split`, `schema`);
published schemas in `schemas/cultnet/`.
- `data/corpus/corpus.cc`, `data/entity/entity.cc` and `data/interlingua/inventory.cc`: the English
corpus, its entities and the inventory, read with `weksa corpus dump`,
`weksa entity dump` and `weksa inventory dump`. `data/original/inventory.cc`
carries its own Validation-informed lexicon revisions (5 and 6) for lowering
measurements; scored runs use `data/interlingua`.
- [Lowering target](./docs/targets/interlingua-lowering.md) and
[its map](./docs/targets/interlingua-lowering-map.md): the design, scoring
and cut sequence.
- `data/`: the committed stores (corpora, entities, inventory, language ontology) and research data; there are no target-language profiles.
- `settings/`: setting-specific proving grounds for language projects.
**Live versus planned.** Live: docs, fixtures, examples, ontology data and the
packet crate `crates/weksa`, including `weksa lower` (the template lowerer for
proof fixtures) and `weksa score`, and the golf loop's round and edit-accept
cycle (`weksa loop open|round|cycle`), which encodes and lowers through the
model (a prompted Claude subagent, per staged-distill).
Planned: Score and lowering documents and the other panel languages. No
daemon runs; the earlier Node daemon is parked at tag `parked/weksa-node-body`.
## Ownership Model
- Ontology owns meaning.
- Grammar owns required expression.
- Phonology owns sound shape.
- Diachrony owns historical distortion.
- Renderer owns surface text.
- Persistent state owns durable maps, constraints, decisions, and evidence.
If a future module cannot state what it owns and what invariant it protects, it
does not get to exist. Harsh, but the alternative is a language generator with a
clipboard and delusions of nationhood.
## Scaffold
- `state/map.yaml`: canonical working map.
- `state/scratch.md`: disposable workbench.
- `schemas/`: human-facing state contract receipts.
- `docs/`: architecture, language model, and roadmap.
- `settings/`: setting-specific proving grounds for language projects.
Start with [Best Modern Approach](./docs/best-modern-approach.md) for the core
design doctrine: ontology, roots, morphology, syntax, semantics, interlingua,
diachrony, and model-assisted consistency.
See [Project Model](./docs/project-model.md) for the engine / language project /
setting split, and [Runtime and Authoring Split](./docs/runtime-authoring-split.md)
for the LLM-free hot path.
See [Interlingua Standard](./docs/interlingua-standard.md) for the shared
meaning-packet contract Weksa clients should target.
See [Verse Service Contract](./docs/verse-service-contract.md) for the planned
service contract: Weksa would own typed conversational intent, pronunciation
plans, utterance handoffs, and the typed CultMesh state that makes those
documents inspectable. No daemon runs yet.
See [Multilingual Utterance Lowering](./docs/multilingual-utterance-lowering.md)
for the shared lowering target: interlingua projected through speaker state into
English, Brazilian Portuguese, Japanese, and later target-language dialogue.
[Flavored English Lowering](./docs/flavored-english-lowering.md) remains the
target-specific English receipt.
The language ontology is `data/ontology/ontology.cc` (read it with
`weksa ontology dump`): per language, the lexicon, grammar and discourse choices a lowerer
reads for a stance, a discourse and a scene relation. Only an entry with a Scene condition names an
address or politeness level; the relation, from `data/original/speaker-state.cc`, picks it. Its
en-US and ja-JP entries and the keeper scenes are model-drafted or model-annotated, never Test evidence. Nothing yet grows them from accepted
rounds; until that mint exists they change only by a new `weksa ontology admit`. ja-JP holds Scene entries `onto:ja-JP:10` to `:13`. It holds none for an above-status out-group
addressee, and none for an above-status in-group addressee below intimacy 700 (`:12` still selects
an in-group addressee at intimacy 700 or more, whatever the status). Two entries for the above-status
cases were withdrawn: a paired measure found they made the lowerer match the reference register less
often, and they stay out until a native reader attests them.
ja-JP `:5` (hedging), `:7` (affection) and `:8` (restrained sadness) carry certainty and restraint conditions, through `AtMostOrUnset` bounds (an unrated certainty or restraint does not defeat them), so the hedging, certainty, affection, restraint and sadness entries never co-select on the pairs `:5`/`:6`, `:4`/`:7`, `:6`/`:7` and `:6`/`:8`; ja-JP `:3` (anger) carries `AtMostOrUnset` hedge and affection bounds, as en-US `:3`, so `:3`/`:5` and `:3`/`:7` never co-select; the store has no retire, so that was a rebuild of `data/ontology/ontology.cc` with the ja-JP text unchanged. en-US `:3` (blunt anger) carries `AtMostOrUnset` hedge and affection bounds, and `:5` (hedging) and `:8` (affection) each an `AtMostOrUnset` certainty bound (as ja-JP `:7`), so `:3`/`:5`, `:3`/`:8`, `:5`/`:6` and `:6`/`:8` never co-select; `:5`'s certainty clause is that condition and no longer prose; `:6` and the Scene entry `:10` still co-select and are kept apart by scoping in the text. ja-JP `:9` (surprise) states its question ending as available, not prescribed, so `:6`/`:9`, `:5`/`:9` and `:3`/`:9` stay co-selectable and are reconciled by wording, not by condition.
For the first AquaSynth speech-training handoff, see
[Tiny PanPhon v0.1 Speech Curriculum](./examples/speech-training/tiny-panphon-v0.1/README.md).
Those packets are emitted by `tools/emit_tiny_panphon_handoffs.py` and provide
the crawl-stage artifact for simple IPA sounds. Validate the checked contract
with `tools/validate_tiny_panphon_handoffs.py` before handing the batch to
AquaSynth or expanding pronunciation coverage.
## Implementation Status
The persistent state spine is live: map, scratch, schemas, docs, examples and
data. Packet types, validation and the corpus and inventory stores are live in
`crates/weksa`, and so is the scoring library. Lowering and the service are planned (see the cut
sequence in [the lowering map](./docs/targets/interlingua-lowering-map.md)).
Writing and agent state will enter Weksa as intent pressure, and typed utterance
documents will leave for AquaSynth.
[Eusocial Interbeing / Zyphos](./settings/eusocial-interbeing/README.md) is the
current higher-priority setting target. [Rust to Dust](./settings/rust-to-dust/README.md)
is preserved as an earlier proving ground, not engine doctrine.