Feature: typeid explain — Human-Readable Explanations from ID Schemas #46
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
…introspection and optional schema support Changes: - Introduced a new CLI command: `typeid explain`, enabling human-readable and machine-readable (JSON) explanations for TypeID values. - Enhanced documentation in README.md with detailed usage, configuration, and design principles for the new explain feature. - Added support for schema-based explanations via JSON (default) and YAML (optional extra dependency). - Described schema discovery rules, including support for both local and user config directory schemas. - Updated `pyproject.toml` and `poetry.lock` to define a new optional extra dependency group: `yaml` (using PyYAML). - Registered the `yaml` extra in [tool.poetry.extras], enabling users to install YAML support as needed. - Added explanation formatting utilities and proper schema loading logic in CLI, robustly handling both errors and absence of schema. - Provided new examples in documentation for using explain with and without schema, and illustrating output formats. - Ensured backward compatibility by preserving all existing APIs and CLI commands.
llalyeva
approved these changes
Dec 20, 2025
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Adds a full typeid explain feature: introduces a new explain subsystem (engine, models, registry, discovery, formatters), a CLI command, schema discovery rules, optional YAML schema support via an extra, rich examples, and comprehensive tests. The command explains TypeIDs with derived facts (UUID, timestamp, sortability), optionally enriches them from JSON/YAML schemas, supports JSON output, and remains non-breaking and offline-friendly.
#45