Ogmi

Ogmi is a command-line interface (CLI) that queries structured language-learning descriptors and returns JSON data for educational purpose.

Teachers, schools, publishers, or learners can use it to inspect descriptor data. Coding agents can use its JSON output in lesson-planning and curriculum workflows. Pair it with Moth to design educational materials based on language-learning descriptors.

Status

Ogmi is a v0 software. The CLI, JSON structures may still change before a stable release. Source code is licensed under Apache-2.0, but descriptor specs may have separate rights. Some bundled specs are under rights review. See NOTICE and specs/README.md.

What it does

• JSON output by default for agents and automation.
• Human-readable output with --format text.
• Embedded specs by default.
• External specs override with --specs PATH or OGMI_SPECS.
• Query descriptors by corpus, level, scale, path fields, ID, and text.
• Inspect schema, scales, examples, and coverage.

Install

Go install

go install github.com/alnah/ogmi/cmd/ogmi@latest

Quick start

List available descriptor corpora:

ogmi descriptors corpora

List descriptors as JSON:

ogmi descriptors list --corpus themes --level a1 --limit 5

Print text output:

ogmi descriptors corpora --format text

Inspect fields and schema:

ogmi descriptors fields --corpus themes
ogmi descriptors schema --field level --corpus themes

Get one descriptor by ID:

ogmi descriptors get \
  --corpus themes \
  --id themes.descriptors.food.meals_food_preferences_and_basic_needs.a1

Build a coverage matrix:

ogmi descriptors coverage --corpus themes

Export bundled specs:

ogmi specs export --output ./specs

Use external specs:

ogmi --specs ./specs descriptors list --corpus themes --limit 3

Output

Data commands return JSON by default. JSON responses include a kind and schemaVersion field so agents can identify payload shape.

Example:

{
  "kind": "descriptor_corpora",
  "schemaVersion": "v1",
  "corpora": [
    {
      "name": "themes",
      "pathFields": [],
      "defaultCoverageAxes": ["corpus", "level"],
      "files": ["specs/themes/descriptors.yml"]
    }
  ]
}

Use --format text with commands that support text output.

Specs source precedence

Ogmi resolves specs in this order:

1. --specs PATH
2. OGMI_SPECS
3. embedded specs

External specs replace embedded specs. They are useful for private, licensed, experimental, or institution-specific descriptor data.

Custom specs

External specs must use the same specs/ layout as the bundled specs. Start from the bundled files, or create that layout yourself:

ogmi specs export --output ./my-specs
ogmi --specs ./my-specs descriptors list --corpus themes

Or set OGMI_SPECS for the current shell:

export OGMI_SPECS=./my-specs
ogmi descriptors list --corpus themes

Ogmi only loads these known corpus locations under the specs root:

Corpus	Loaded locations
cefr	any descriptors.yml under specs/cefr/<domain>/<subdomain>/
french	any descriptors.yml under specs/french/<domain>/
texts	any descriptors.yml under specs/texts/<domain>/
themes	specs/themes/descriptors.yml

Only files named descriptors.yml are loaded. For cefr, the first two path segments below specs/cefr/ become domain and subdomain. For french and texts, the first path segment below the corpus root becomes domain.

A descriptor file contains catalog scale rows, entries descriptor rows, or both:

catalog:
  - code: "food"
    id: "themes.descriptors.food"
    description: "Food-related descriptors."

entries:
  - scale: "food"
    level: "a1"
    code: "name_basic_foods"
    id: "themes.descriptors.food.name_basic_foods.a1"
    description: "Can name basic foods."

Top-level id and version fields are allowed in spec files, but the loader does not read them. catalog rows require code, id, and description. entries rows require scale, level, code, id, and description. Codes, scales, levels, and corpus path values are normalized to lowercase tokens. IDs keep their spelling apart from surrounding whitespace.

description must be a YAML string or a list of strings. These forms are valid in both catalog and entries rows:

# Single string.
description: "Can name basic foods."

# List of strings.
description:
  - "Can name basic foods."
  - "Can state simple preferences."

# Block scalar string.
description: |
  Can name basic foods.
  Can state simple preferences.

Ogmi trims surrounding whitespace from each description string. Empty list items are ignored. For descriptor entries, list items are joined with newlines in JSON output. For catalog scales, list items remain a JSON string array. Block scalar strings keep internal line breaks.

YAML sequence markers are not part of the text. If you want visible bullet markers in output, include them inside a block scalar:

description: |
  - Can name basic foods.
  - Can state simple preferences.

Maps and nested objects are invalid for description.

Commands

Command	Purpose
ogmi descriptors corpora	List descriptor corpora.
ogmi descriptors fields	List descriptor fields.
ogmi descriptors schema	Describe descriptor schema and field values.
ogmi descriptors list	Query descriptors with filters and pagination.
ogmi descriptors scales	Query descriptor scales.
ogmi descriptors get	Get one descriptor by ID.
ogmi descriptors compare-levels	Compare level coverage for descriptors.
ogmi descriptors coverage	Build a coverage matrix.
ogmi descriptors examples	Show example descriptor queries.
ogmi specs export	Export embedded specs to a directory.
ogmi version	Print the Ogmi version.

Run help for details:

ogmi --help
ogmi descriptors list --help

Descriptor corpora

Current bundled corpora are:

• cefr
• french
• texts
• themes

See specs/README.md before reusing bundled descriptor data. Some specs are under rights review and may not be covered by the software license.

Development

Use the Makefile for local checks:

make help
make quick
make check

Common targets:

make fmt              # format Go files and imports
make lint             # run golangci-lint
make test             # run tests
make test-race        # run race tests
make cover            # write coverage.out and print coverage summary
make govulncheck      # check reachable Go vulnerabilities
make goreleaser-check # validate GoReleaser config
make snapshot         # build local snapshot release artifacts
make clean            # remove dist/ and coverage.out

Before pushing changes:

make check

License

Ogmi software source code is licensed under the Apache License, Version 2.0. See LICENSE.

Descriptor specs are data/content and may have separate rights. Third-party material remains subject to its original rights and is not relicensed by Ogmi. See NOTICE and specs/README.md.

Services around Ogmi, such as hosting, integration, training, and support, may use separate terms.