module-kit

module
v0.1.18 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 5, 2026 License: Apache-2.0

README

module-kit

CI Release CodeQL Latest release Go version Coverage OpenSSF Scorecard License

Code Smells Reliability Rating Security Rating Maintainability Rating Vulnerabilities

The NovaTrail module format in code: the one Go library that holds the format's semantics, and the authors' CLI on top of it. It reads an author's module and checks it — the schema, a skill graph without cycles, references, the shared taxonomy, keys by solver and fallback texts by leak check — builds the module package and the module index, and compares a new version of a module with every published one by the format's rules of versions. It also fills seeded task templates and runs their solvers in a Starlark sandbox, and for the platform's service it builds the open view of a task, joins two readings of a learner's work into one observation and runs the check kinds on it, admits a verdict only by the provenance of its key and trusts a package by the chain of digests from a pinned index; signatures it leaves to spec's release-verify. It never calls an AI model: the library makes no network calls, the CLI only reads and writes a module's files, and neither holds learners' data.

A component of NovaTrail, a universal open platform for adaptive learning, interactive lessons and AI tutoring. It belongs to stage 1, Format and core, with spec, modules, learner-model, engine and sim; together with modules it tries the module format v0 on two unlike subjects at once.

Status

Detailing is done. The documents came first: the first epic of RUN.md, now archived in docs/plan/E1.md, decided what the component's card left open, and the code follows in the order RUN.md sets. The code here so far is the skeleton of the CLI, module-kit --version, which the author had written ahead of the format so that the shared Go checks of .github have code to be tried on (R04), and the library's packages, each saying what it will hold (R20). The first code of the format is the reader of YAML: it reads a module's file into its JSON value and refuses one that breaks a rule yaml.*, on go-yaml v4 with passes of its own around it wherever go-yaml reads otherwise than YAML 1.2.2 (R21). On it stands the check of a module: its folder as the format lays it out, the rules module.*, and the format version its manifest names, which the check reads before anything else and refuses outside 0.3 (R22). Each file of a part is checked against the JSON Schema 2020-12 schema of its part, by santhosh-tekuri/jsonschema over a copy of the format's schemas that a test holds to spec's, and a breach of a schema names its keyword and its place as the format's examples do (R23). From the marks x-open in the same schemas the library builds the open view of each part, what the learner's app receives, into the types of spec's formatv0/open (R24). On the files that their schemas accept, the check runs the rules of the manifest, the skill graph and the catalogs, and the library computes the tiers of the skills that the package will hold (R25); it runs the rules of a task and of a lesson too, those that need no check kind, no leak check and no template (R26). The library gives the verdict of an answer slot and of an item on the values read in them, by the check kinds number, fraction and choice and their normalization, with the trap of a wrong value, and the check of a module reads by those verdicts the rules of a task that a check sees itself (R27). The normalization follows Unicode 17.0.0, which a release names in verdict.UnicodeVersion and on the second line of module-kit --version. A predicate runs in the Starlark sandbox, on go.starlark.net at the version the format names, in the format's one dialect, with its limit of steps and module-kit's clock, and the check of a module holds that its expression names nothing but value and the dialect's built-in names (R28). The package observation holds what module-kit does with spec's observation, novatrail.observation.v1: which one is valid, how the readings of two readers join into one answer slot by answer slot, and the verdict on the joined one with the options tapped beside it, or how an essay's submission ends; an observation that is not valid is no observation, and every answer slot that AI reads gets unchecked (R29). The leak check finds the keys and the leak phrases of a task in a text: in the tutor's words before api sends them, and in the texts of a module that a learner sees before solving, which the check of a module holds by task.no-leaks and lesson.no-leaks, a template aside until its instances come. It normalizes a text as the verdict normalizes a value, by code that has moved into a package of its own for both (R30). The generator of the format is module-kit's own code, written from the constants of the format's text, with an error on an argument outside a function's domain and Go's math/rand/v2 and hash/fnv as its reference in the tests alone; by it the library picks which instance of a template an attempt gets from the attempt's seed (R31). A test walks every example and test vector of the format and of the observation, which the code takes from spec's Go modules at the submodule's tag, and lists each one module-kit does not pass yet (R20). The code of the format comes in the current epic, E2 in RUN.md, on the module format 0.3 that spec defines in its format/, and its first release that others take is the first of the line 0.2.

Documents

The documents are in Russian.

  • docs/architecture.md — the component: what it does and does not do, its data and links, and what is still to decide.
  • docs/decisions.md — the decision log: what was decided, why, and what was rejected.
  • RUN.md — the work plan, in epics.

The working rules, for people and coding agents alike, are in CLAUDE.md and AGENTS.md. The platform's shared vocabulary, formats, contracts and decisions are in spec, checked out here as a git submodule at v0.9.2: clone this repository with git clone --recurse-submodules.

License

Apache-2.0.

Directories

Path Synopsis
cmd
module-kit command
Command module-kit is the authors' CLI of NovaTrail's module format.
Command module-kit is the authors' CLI of NovaTrail's module format.
internal
canonical
Package canonical writes the canonical text of a JSON value — of a package, a module index and an open view — and stops with an error on a value the format cannot hold (format/README.md, section 25; R09).
Package canonical writes the canonical text of a JSON value — of a package, a module index and an open view — and stops with an error on a value the format cannot hold (format/README.md, section 25; R09).
normal
Package normal normalizes a text as the check kinds of the module format and its leak check do, and reads a number in the notation that a kind takes (format/README.md, sections 15 and 20): the steps 1 to 7 of a number and the units of step 6, the normal form of a choice, and a number in notation as an exact rational.
Package normal normalizes a text as the check kinds of the module format and its leak check do, and reads a number in the notation that a kind takes (format/README.md, sections 15 and 20): the steps 1 to 7 of a number and the units of step 6, the normal form of a choice, and a number in notation as an exact rational.
random
Package random is the generator of the format and its places of randomness, written from the constants of the format's text rather than taken from math/rand/v2, with an error on an argument outside a function's domain (format/README.md, section 22; R59 spec; R10).
Package random is the generator of the format and its places of randomness, written from the constants of the format's text rather than taken from math/rand/v2, with an error on an argument outside a function's domain (format/README.md, section 22; R59 spec; R10).
sandbox
Package sandbox runs the Starlark of the format — the predicate of a check, the expressions of a template and its solver — in go.starlark.net at the version the format names, in its one dialect, with the format's limits of steps and module-kit's clocks, on the caller's goroutine and with its context (format/README.md, sections 15, 23 and 24; R88 spec; R11; architecture 3.4).
Package sandbox runs the Starlark of the format — the predicate of a check, the expressions of a template and its solver — in go.starlark.net at the version the format names, in its one dialect, with the format's limits of steps and module-kit's clocks, on the caller's goroutine and with its context (format/README.md, sections 15, 23 and 24; R88 spec; R11; architecture 3.4).
schema
Package schema checks a value against the JSON Schema 2020-12 schemas of the format version the library reads, reporting every keyword that fails with its place (format/README.md, sections 5 and 8), and builds the open view of a value from the marks x-open in the same schemas (section 6).
Package schema checks a value against the JSON Schema 2020-12 schemas of the format version the library reads, reporting every keyword that fails with its place (format/README.md, sections 5 and 8), and builds the open view of a value from the marks x-open in the same schemas (section 6).
vectors
Package vectors runs every example and test vector of the module format — spec.Format, at the version go.mod requires — and the vectors of the observation, observation/v1/ of contracts.Vectors, against module-kit: an implementation that does not pass them does not conform (format/README.md, sections 1, 8 and 9; contracts/README.md, section 10).
Package vectors runs every example and test vector of the module format — spec.Format, at the version go.mod requires — and the vectors of the observation, observation/v1/ of contracts.Vectors, against module-kit: an implementation that does not pass them does not conform (format/README.md, sections 1, 8 and 9; contracts/README.md, section 10).
yaml
Package yaml reads a file of a module, YAML 1.2.2 under its Core schema, into a JSON value, and refuses a file that breaks a rule yaml.*, naming the rule and its place, or that is not YAML 1.2.2 at all (format/README.md, section 4; R45 spec).
Package yaml reads a file of a module, YAML 1.2.2 under its Core schema, into a JSON value, and refuses a file that breaks a rule yaml.*, naming the rule and its place, or that is not YAML 1.2.2 at all (format/README.md, section 4; R45 spec).
Package leak finds the keys and the leak phrases of a task in a text: in the tutor's words before they reach the device, for api, and in the texts of a module that a learner sees before solving, for the check of a module, which holds task.no-leaks and lesson.no-leaks by it (format/README.md, section 20; R54 spec, R57 spec; R30).
Package leak finds the keys and the leak phrases of a task in a text: in the tutor's words before they reach the device, for api, and in the texts of a module that a learner sees before solving, for the check of a module, which holds task.no-leaks and lesson.no-leaks by it (format/README.md, section 20; R54 spec, R57 spec; R30).
Package module reads an author's module and checks it as the module format says: its layout and the version of the format it names, each file against the schema of its part, and the format rules of each part, between parts and of the whole module — the tiers of the skill graph, the templates with every instance and solver, and the leak check of the texts a learner sees before solving among them (format/README.md, sections 2 and 4–24).
Package module reads an author's module and checks it as the module format says: its layout and the version of the format it names, each file against the schema of its part, and the format rules of each part, between parts and of the whole module — the tiers of the skill graph, the templates with every instance and solver, and the leak check of the texts a learner sees before solving among them (format/README.md, sections 2 and 4–24).
Package moduleindex builds the module index of a release from the previous index, the release's packages, its tag and its withdrawals, refusing by the rules module-index.*; reads an index of any version of the format by the places every version keeps; and picks the version of a module for a new attempt: the newest by semver that is not withdrawn and lies in the format's window (format/README.md, sections 2 and 26; R63 spec; R16).
Package moduleindex builds the module index of a release from the previous index, the release's packages, its tag and its withdrawals, refusing by the rules module-index.*; reads an index of any version of the format by the places every version keeps; and picks the version of a module for a new attempt: the newest by semver that is not withdrawn and lies in the format's window (format/README.md, sections 2 and 26; R63 spec; R16).
Package modulepackage builds the package of a checked module — its canonical view, the listing of its device part and its inventory, with their digests — and reads a package as files by the chain of digests from the digest an index gives: inventory, then parts, then files (format/README.md, section 25; R62 spec).
Package modulepackage builds the package of a checked module — its canonical view, the listing of its device part and its inventory, with their digests — and reads a package as files by the chain of digests from the digest an index gives: inventory, then parts, then files (format/README.md, section 25; R62 spec).
Package moduleversion compares a new version of a module with every published one: it finds the part of the version that the change asks for and holds the rules module-version.*, and it reads a package of an earlier version of the format by the places every version keeps (format/README.md, sections 2 and 27; R89 spec, R101 spec; R13).
Package moduleversion compares a new version of a module with every published one: it finds the part of the version that the change asks for and holds the rules module-version.*, and it reads a package of an earlier version of the format by the places every version keeps (format/README.md, sections 2 and 27; R89 spec, R101 spec; R13).
Package observation holds what module-kit does with an observation, novatrail.observation.v1: which one is valid, how the observations of two readers join into one, answer slot by answer slot, which verdict the observation gives with the options tapped beside it, and how the submission of an essay ends (contracts/README.md, section 10; R86 spec; R29).
Package observation holds what module-kit does with an observation, novatrail.observation.v1: which one is valid, how the observations of two readers join into one, answer slot by answer slot, which verdict the observation gives with the options tapped beside it, and how the submission of an essay ends (contracts/README.md, section 10; R86 spec; R29).
Package openview builds the open view of a part of a module and of an instance of a template — what the learner's app receives: the part without its closed fields — from the marks x-open in the schemas of the format, and the digest of the open view of a task and of an instance (format/README.md, section 6; R05 spec; R93 spec).
Package openview builds the open view of a part of a module and of an instance of a template — what the learner's app receives: the part without its closed fields — from the marks x-open in the schemas of the format, and the digest of the open view of a task and of an instance (format/README.md, section 6; R05 spec; R93 spec).
Package template fills the templates of tasks: it counts the instances of a template, builds each one with its numbers and the results of its solver, and picks the instance of an attempt from the attempt's seed (format/README.md, sections 22–24; R60 spec, R61 spec).
Package template fills the templates of tasks: it counts the instances of a template, builds each one with its numbers and the results of its solver, and picks the instance of an attempt from the attempt's seed (format/README.md, sections 22–24; R60 spec, R61 spec).
Package verdict gives the verdict of an answer slot and of an item on the values read in them, by the check kinds of the module format and their normalization, with the reason of a value that cannot be read and the trap of a wrong one (format/README.md, section 15).
Package verdict gives the verdict of an answer slot and of an item on the values read in them, by the check kinds of the module format and their normalization, with the reason of a value that cannot be read and the trap of a wrong one (format/README.md, section 15).

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL