esoi 0.6.0__py3-none-any.whl

esoi/__init__.py

@@ -0,0 +1,246 @@
+"""esoi: Evolvable Structure that Optimizes Intent (ESOI) as a library and a command.
+
+An adopting repository keeps its intent as records (problems, ideals, solutions, implementations, metrics),
+its placement as components, and its measurements as a results log. This package checks them against each
+other (``esoi check``), runs and records evaluations (``esoi run``), ranks implementations
+(``esoi leaderboard``), resolves a selection table at run time and builds a review tracker (``esoi tracker``).
+Everything specific to a repository is configuration (``esoi.toml``).
+
+In code, declare a solution once where it lives and call it::
+
+    from esoi import solution, implementation, override
+
+    @solution("greet-a-person")
+    def greet(name): ...
+
+    @implementation("greet-a-person", "plain")
+    def plain(name): return f"Hello, {name}!"
+
+    greet("Ada")                      # the project default, from the records
+    greet("Ada", using="loud")        # this call only
+    with override("greet-a-person", "loud"): ...   # a block
+
+The public API is this module. Everything a program that embeds esoi imports is named here, so a module can move inside the package without
+breaking a caller: the flat names in ``PUBLIC`` (``from esoi import Assembler``) and the namespaces in ``NAMESPACES``
+(``from esoi import harness`` then ``harness.load_cases``). The package is four containers (``understanding``, ``structure``,
+``optimization``, ``runtime``), each one folder per solution; import from them only inside esoi. ``tests/test_public_api.py`` resolves
+every name below.
+"""
+import importlib
+import types
+from typing import Any, Dict, Tuple
+
+from esoi.runtime.implementation_selection.declare import implementation, override, register, resolve, solution
+from esoi.runtime.implementation_selection.selection_registry import SelectionError
+
+__version__ = "0.6.0"   # the package's version: pyproject.toml carries the same number (a test keeps them equal)
+
+
+# Flat public names: name -> (module, attribute). A name here may differ from the attribute when the attribute alone would be unclear.
+PUBLIC: Dict[str, Tuple[str, str]] = {
+    "AFTER": ("esoi.optimization.keep_metric_record.metric_meter", "AFTER"),
+    "Assembler": ("esoi.runtime.assemble_by_name.assemble", "Assembler"),
+    "Assembly": ("esoi.runtime.assemble_by_name.assembly", "Assembly"),
+    "AssemblyConfig": ("esoi.runtime.assemble_by_name.assembly_config", "AssemblyConfig"),
+    "AssemblyError": ("esoi.structure.intent_registry.assembly_errors", "AssemblyError"),
+    "BEFORE": ("esoi.optimization.keep_metric_record.metric_meter", "BEFORE"),
+    "BudgetExceeded": ("esoi.optimization.when_metrics_are_run.paid_gating", "BudgetExceeded"),
+    "CallMeter": ("esoi.optimization.measurement_harness.call_meter", "CallMeter"),
+    "Config": ("esoi.structure.intent_registry.config", "Config"),
+    "ConsumerOptions": ("esoi.runtime.consumer_check.consumer", "Options"),
+    "EVERY_MOMENT": ("esoi.optimization.keep_metric_record.metric_meter", "EVERY_MOMENT"),
+    "EntryError": ("esoi.runtime.assemble_by_name.entry_types", "EntryError"),
+    "FileMetricLedger": ("esoi.optimization.keep_metric_record.metric_results", "FileMetricLedger"),
+    "Lazy": ("esoi.runtime.assemble_by_name.lazy_need", "Lazy"),
+    "MAX_METRICS": ("esoi.optimization.keep_metric_record.metric_results", "MAX_METRICS"),
+    "MetricIteration": ("esoi.optimization.keep_metric_record.iteration", "MetricIteration"),
+    "MetricLedger": ("esoi.optimization.keep_metric_record.metric_results", "MetricLedger"),
+    "MetricMeter": ("esoi.optimization.keep_metric_record.metric_meter", "MetricMeter"),
+    "MetricResult": ("esoi.optimization.keep_metric_record.metric_results", "MetricResult"),
+    "NOT_RECORDED_LINE": ("esoi.optimization.keep_metric_record.metric_results", "NOT_RECORDED_LINE"),
+    "Offline": ("esoi.runtime.assemble_by_name.offline_guard", "Offline"),
+    "Pending": ("esoi.runtime.assemble_by_name.entry_types", "Pending"),
+    "READING_STATUS": ("esoi.optimization.keep_metric_record.iteration", "READING_STATUS"),
+    "Registry": ("esoi.structure.intent_registry.registry", "Registry"),
+    "RepoSliceSource": ("esoi.optimization.keep_metric_record.spec_slice", "RepoSliceSource"),
+    "RequirementEntry": ("esoi.runtime.assemble_by_name.environment_needs.declarations", "Entry"),
+    "RuleContext": ("esoi.structure.structure_check.rules.base", "Context"),
+    "RuleGroup": ("esoi.structure.structure_check.rules.base", "RuleGroup"),
+    "RunError": ("esoi.optimization.measurement_harness.run_errors", "RunError"),
+    "RunFiles": ("esoi.optimization.keep_metric_record.metric_results", "RunFiles"),
+    "SOURCES": ("esoi.optimization.keep_metric_record.metric_results", "SOURCES"),
+    "SOURCE_MEASURED": ("esoi.optimization.keep_metric_record.metric_results", "SOURCE_MEASURED"),
+    "SOURCE_NOT_APPLICABLE": ("esoi.optimization.keep_metric_record.metric_results", "SOURCE_NOT_APPLICABLE"),
+    "SOURCE_RECORDED": ("esoi.optimization.keep_metric_record.metric_results", "SOURCE_RECORDED"),
+    "SliceSource": ("esoi.optimization.keep_metric_record.spec_slice", "SliceSource"),
+    "SpecSlice": ("esoi.optimization.keep_metric_record.spec_slice", "SpecSlice"),
+    "TagTable": ("esoi.understanding.spec_search.spec_search", "TagTable"),
+    "assess_structure_quality": ("esoi.structure.structure_check.rules.structure_quality_rules", "assess_path"),
+    "assembly_plan": ("esoi.runtime.assemble_by_name.installation.assembly_plan", "assembly_plan"),
+    "call_entry": ("esoi.runtime.assemble_by_name.entry", "call_entry"),
+    "check_consumer": ("esoi.runtime.consumer_check.consumer", "check_consumer"),
+    "check_headers": ("esoi.structure.intent_registry.records", "check_headers"),
+    "check_records": ("esoi.structure.intent_registry.records", "check_records"),
+    "check_structure": ("esoi.structure.structure_check.check", "check"),
+    "compare_structure_quality": ("esoi.structure.structure_check.rules.structure_quality_rules", "compare_refs"),
+    "consumer_cases_hash": ("esoi.runtime.consumer_check.consumer", "cases_hash"),
+    "consumer_library_dir": ("esoi.runtime.consumer_check.consumer", "library_dir"),
+    "declared_entry": ("esoi.runtime.assemble_by_name.target_lookup", "declared"),
+    "describe_metric": ("esoi.optimization.keep_metric_record.spec_slice", "describe_metric"),
+    "environ_declared": ("esoi.runtime.assemble_by_name.environ_options", "environ_declared"),
+    "environ_fill": ("esoi.runtime.assemble_by_name.environ_options", "environ_fill"),
+    "environ_lacking": ("esoi.runtime.assemble_by_name.environ_options", "environ_lacking"),
+    "first_arm": ("esoi.structure.intent_registry.registry", "first_arm"),
+    "format_value": ("esoi.optimization.keep_metric_record.metric_results", "format_value"),
+    "harness_arms": ("esoi.structure.intent_registry.registry", "harness_arms"),
+    "index_tokens": ("esoi.understanding.spec_search.spec_index", "tokens"),
+    "load": ("esoi.structure.intent_registry.registry", "load"),
+    "load_cases": ("esoi.optimization.measurement_harness.case_loading", "load_cases"),
+    "load_template": ("esoi.structure.intent_registry.records", "load_template"),
+    "meters_from_names": ("esoi.optimization.keep_metric_record.metric_meter", "meters_from_names"),
+    "own_code_paths": ("esoi.optimization.when_metrics_are_run.know_what_a_result_measures.code_provenance", "own_code_paths"),
+    "parse_tags": ("esoi.structure.intent_registry.fields", "parse_tags"),
+    "payload_of": ("esoi.optimization.keep_metric_record.metric_results", "payload_of"),
+    "read_csv": ("esoi.structure.intent_registry.tables", "read_csv"),
+    "read_tree": ("esoi.structure.intent_registry.intents", "read_tree"),
+    "reconcile": ("esoi.optimization.keep_metric_record.metric_results", "reconcile"),
+    "record_fields": ("esoi.structure.intent_registry.records", "fields"),
+    "render_line": ("esoi.optimization.keep_metric_record.metric_results", "render_line"),
+    "run_entry": ("esoi.runtime.assemble_by_name.entry", "run"),
+    "served_by_solution": ("esoi.understanding.spec_search.spec_search", "served_by_solution"),
+    "split_ids": ("esoi.structure.intent_registry.tables", "ids"),
+    "stratified_sample": ("esoi.optimization.measurement_harness.case_loading", "stratified_sample"),
+    "tables_of": ("esoi.structure.intent_registry.records", "tables_of"),
+    "targets": ("esoi.runtime.assemble_by_name.entry", "targets"),
+    "terms_of": ("esoi.understanding.spec_search.spec_search", "terms_of"),
+    "views_from_index": ("esoi.understanding.spec_search.spec_search", "views_from_index"),
+    "views_from_items": ("esoi.understanding.spec_search.spec_search", "views_from_items"),
+    "without_line": ("esoi.optimization.keep_metric_record.metric_results", "without_line"),
+}
+
+# Public namespaces: ``from esoi import harness`` gives an object with just these attributes of these modules.
+NAMESPACES: Dict[str, Dict[str, Tuple[str, ...]]] = {
+    "access": {
+        "esoi.optimization.measurement_harness.access": ('violation',),
+    },
+    "cascade": {
+        "esoi.optimization.leaderboard.cascade_stages": ('load_stages', 'parse'),
+        "esoi.optimization.leaderboard.stage_standings": ('stage_index',),
+    },
+    "config": {
+        "esoi.structure.intent_registry.config": ('load',),
+    },
+    "declarations": {
+        "esoi.structure.intent_registry.specify_from_code.declarations": ('code_files', 'drift', 'scan'),
+    },
+    "entry": {
+        "esoi.runtime.assemble_by_name.entry": ('build_handle', 'prepare', 'runner'),
+        "esoi.runtime.assemble_by_name.entry_types": ('Pending',),
+        "esoi.runtime.assemble_by_name.intent_map": ('snapshot',),
+        "esoi.runtime.assemble_by_name.offline_guard": ('Offline',),
+        "esoi.runtime.assemble_by_name.readme_example": ('run_block',),
+    },
+    "evidence": {
+        "esoi.optimization.when_metrics_are_run.public_evidence.evidence_grading": ('estimates', 'lines_for_implementation'),
+        "esoi.optimization.when_metrics_are_run.public_evidence.evidence_ranking": ('rank',),
+        "esoi.optimization.when_metrics_are_run.public_evidence.evidence_records": ('EvidenceError', 'implementation_candidates', 'load', 'load_for'),
+    },
+    "evidence_table": {
+        "esoi.optimization.leaderboard.evidence_table": ('cell', 'cost_label', 'public_label', 'rate_label', 'seconds_label'),
+    },
+    "expect": {
+        "esoi.optimization.measurement_harness.expect": ('aggregate_by_kind', 'check', 'score_kind_case'),
+    },
+    "foundation": {
+        "esoi.optimization.when_metrics_are_run.know_what_a_result_measures.builds_on": ('declared', 'declared_arms', 'problems'),
+    },
+    "harness": {
+        "esoi.optimization.leaderboard.case_identity": ('cases_digest',),
+        "esoi.optimization.measurement_harness.arm_loading": ('load_impl',),
+        "esoi.optimization.measurement_harness.call_meter": ('CallMeter',),
+        "esoi.optimization.measurement_harness.case_loading": ('load_cases',),
+        "esoi.optimization.when_metrics_are_run.know_what_a_result_measures.code_provenance": ('current_sha',),
+        "esoi.optimization.measurement_harness.component_folder": ('prepare_path',),
+        "esoi.optimization.measurement_harness.record_result": ('record_result',),
+        "esoi.optimization.measurement_harness.record_slices": ('record_slices',),
+        "esoi.optimization.measurement_harness.run_component": ('run_component',),
+        "esoi.optimization.when_metrics_are_run.paid_gating": ('declares_paid', 'price_for'),
+    },
+    "hermetic": {
+        "esoi.optimization.measurement_harness.hermetic": ('from_config',),
+    },
+    "hygiene": {
+        "esoi.structure.structure_check.hygiene": ('repo_files', 'scan_repo', 'scan_text'),
+    },
+    "intents": {
+        "esoi.structure.intent_registry.intents": ('RECORD_FILES', 'discover', 'folders', 'read_rows', 'read_tree', 'tree_folders'),
+    },
+    "leaderboard": {
+        "esoi.optimization.leaderboard.arm_kinds": ('arm_kind', 'invariant_reason'),
+        "esoi.optimization.leaderboard.arm_selection": ('selected_impls',),
+        "esoi.optimization.leaderboard.case_identity": ('cases_digest',),
+        "esoi.optimization.leaderboard.held_out_parts": ('part_of', 'part_row', 'selection_leader'),
+        "esoi.optimization.leaderboard.ranking": ('pass_rate', 'passes', 'rank'),
+        "esoi.optimization.leaderboard.results_log": ('all_results', 'is_partial', 'per_case_rows', 'slice_results'),
+        "esoi.optimization.leaderboard.rival_decisions": ('best_guess', 'challengers', 'decisions'),
+        "esoi.optimization.leaderboard.switching_policy": ('Policy', 'holdout_fraction', 'policies'),
+        "esoi.optimization.leaderboard.verdict_labels": ('slice_verdicts',),
+    },
+    "lock": {
+        "esoi.runtime.implementation_selection.lock": ('diff', 'status', 'update', 'write'),
+    },
+    "registry": {
+        "esoi.structure.intent_registry.registry": ('load',),
+    },
+    "requirements": {
+        "esoi.runtime.assemble_by_name.environment_needs.checking": ('UNMET', 'check'),
+        "esoi.runtime.assemble_by_name.environment_needs.closure": ('members_pairs',),
+        "esoi.runtime.assemble_by_name.environment_needs.declarations": ('Api', 'Binary', 'Download', 'Entry', 'Env', 'Isolate', 'Python', 'Resource', 'Service', 'api', 'binary', 'declared', 'download', 'env', 'gather', 'isolatable', 'network', 'python', 'resource', 'service'),
+        "esoi.runtime.assemble_by_name.environment_needs.generated_files": ('env_template',),
+        "esoi.runtime.assemble_by_name.environment_needs.report": ('describe',),
+    },
+    "scaffold": {
+        "esoi.understanding.the_standard.scaffold": ('init',),
+    },
+    "selection": {
+        "esoi.runtime.implementation_selection.declare": ('override', 'register', 'resolve'),
+        "esoi.runtime.implementation_selection.selection_cascade": ('choose', 'env_name', 'names', 'snapshot'),
+        "esoi.runtime.implementation_selection.selection_registry": ('REGISTRY', 'SelectionError', 'entry_for'),
+    },
+    "spec_index": {
+        "esoi.understanding.spec_search.spec_index": ('build', 'cached', 'find_specs', 'of_intent', 'related', 'show', 'tokens'),
+    },
+    "spec_search": {
+        "esoi.understanding.spec_search.spec_search": ('Found', 'Gate', 'RECORD_CANDIDATE_KINDS', 'RECORD_SOURCE', 'Selection', 'TagTable', 'VectorSearch', 'View', 'fuse', 'gate_decision', 'gated', 'lexical_scored', 'render', 'search', 'terms_of', 'views_from_index', 'views_from_items'),
+    },
+    "standards_nav": {
+        "esoi.understanding.spec_search.standards_nav": ('MAX_SHOWN', 'lint', 'select_for_task'),
+    },
+}
+
+__all__ = sorted(["SelectionError", "implementation", "override", "register", "resolve", "solution", "run", "__version__", *PUBLIC, *NAMESPACES])
+
+
+def run(target, input=None, **overrides):
+    """One line for any solution or intent of esoi itself: ``esoi.run("structure-check", ".")``. Packages bind the same function
+    to their own Assembler (``entry.runner``)."""
+    from esoi.runtime.assemble_by_name.interface import own_runner
+    return own_runner()(target, input, **overrides)
+
+
+def __getattr__(name: str) -> Any:
+    if name in PUBLIC:
+        module, attribute = PUBLIC[name]
+        return getattr(importlib.import_module(module), attribute)
+    if name in NAMESPACES:
+        space = types.SimpleNamespace()
+        for module, attributes in NAMESPACES[name].items():
+            loaded = importlib.import_module(module)
+            for attribute in attributes:
+                setattr(space, attribute, getattr(loaded, attribute))
+        return space
+    raise AttributeError(f"module 'esoi' has no attribute {name!r}")
+
+
+def __dir__():
+    return sorted(set(globals()) | set(__all__))

esoi/__main__.py

@@ -0,0 +1,89 @@
+"""The ``esoi`` command line. Each subcommand is a thin call into the module that owns the behaviour.
+
+    esoi init [DIR] [--package NAME]       scaffold a passing example repository
+    esoi check [--strict] [--findings] [--for-decision] [--write-docs]   run every rule (esoi rules lists them)
+    esoi rules [--markdown]                list the rules and what each one means
+    esoi template sync|check               keep the parsed intent template in step with its source
+    esoi skill sync|check|install          the public copy of the author's skill: generate, verify, install
+    esoi records [check|sync]              check only the intent records, or write the rows the code declares and they lack
+    esoi records place|gather [--apply]    move records beside the code they describe (or into the structure folder); a dry run without --apply
+    esoi admit SOLUTION NAME --why TEXT    register a newly found technology as an implementation of a solution (a rival with no arm until its code is declared);
+                                           with --changed WHAT instead of NAME: record a justified change to the specification
+    esoi new solution ID [--intent ID]     a solution in one command: records, code with declarations, evaluation folder
+    esoi run COMPONENT --impl NAME [--record]   run and record one implementation over a component's cases
+    esoi stale --explain COMPONENT | --count   which changed files a recorded result measures, and how many rows each staleness rule calls stale
+    esoi leaderboard [--strict]            rank the implementations of every evaluated solution
+    esoi select SOLUTION [--name NAME]     show which implementation runs now, and which layer of the cascade chose it
+    esoi cascade [SOLUTION] [--strict]     a metric's cascading conditionals: each stage's results, the chosen implementation, what to run next
+    esoi evidence-table [--file F]         Markdown table of arms, Wilson intervals, paired verdicts; written between markers in F
+    esoi evidence [list|grade|rank|table]  public evidence others measured, graded A to D; complementary, never a result row
+    esoi select --promote [SOLUTION]       switch `selected` to the rival shown better on the solution's own metric
+    esoi select --snapshot FILE            write the defaults and modules for a package shipped without the records
+    esoi tracker build|check               build or verify the review tracker tabs
+    esoi consumer check --registry CSV     check a consuming repository's integration registry
+    esoi fields migrate [--apply]          split scoped_purpose into the new solution and metric fields in every records folder (dry run without --apply)
+    esoi intent migrate [--apply]          move a legacy overall layout to the intent layout (dry run without --apply)
+    esoi spec index [--out FILE]|find TEXT [-k N] [--expand N]|show ID [--tier 0|1|2]|related ID [--depth N]|intent [ID] [--cache FILE]   the specification index: find the few records a new use case needs
+    esoi spec prompt SOLUTION [--task T] [--budget N] [--with CSV] [--json]   the prompt for one solution's own consideration, formed from its network of records
+    esoi consider TEXT [--solution ID] [--max N] [--list]   one generated prompt per solution a change or candidate concerns, and per parent level (JSON)
+    esoi projects init|add|list|check|index|where   the local ESOI index (a folder named by ESOI_HOME, else ~/.esoi)
+    esoi version [--record]                the package version, the skill it follows, the template version; --record writes the template version into esoi.toml
+    esoi hygiene [--staged] [--history]    scan for secrets, machine paths and real addresses
+    esoi requirements [--package P | --scope S] [--solution ID] [--check] [--json] [--env-template FILE] [--install-script FILE]   what the implementations need from their environment
+    esoi install [--package P | --scope S] [--solution ID ...] [--assembly] [--yes]   install only what the solutions in use need (dry run without --yes)
+    esoi lock [--package P | --scope S] [--file esoi.lock.json] [--update [--safe|--latest]] [--diff] [--status] [--solution ID ...] [--json]   pin the selected implementations; see and take newer ones on your schedule
+    esoi attest COMPONENT IMPL --reason TEXT [--through SHA] [--author NAME]   record that an arm's own code changed but not what its result measures
+    esoi docs check|wiki [--out DIR] [--repo-url URL] [--push WIKI_GIT_URL]   the four-category docs standard; generate the wiki from docs/
+    esoi sheet-sync sync|push|pull|check   two-way sync of the tracker with a Google Sheet (esoi[sheets])
+
+``--config PATH`` (before the subcommand) names the configuration file or folder; by default the nearest
+``esoi.toml`` or ``[tool.esoi]`` table from the current folder upward is used.
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+from typing import List, Optional
+
+from esoi import __version__
+from esoi.optimization import commands as optimization_commands
+from esoi.runtime import commands as runtime_commands
+from esoi.structure import commands as structure_commands
+from esoi.understanding import commands as understanding_commands
+
+CONTAINERS = (understanding_commands, structure_commands, optimization_commands, runtime_commands)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="esoi", description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    parser.add_argument("--config", default=None, help="the config file, or the folder that holds it")
+    parser.add_argument("--version", action="version", version=f"esoi {__version__}")
+    parser.set_defaults(needs_config=True, package_version=__version__)   # the front door names the version; a command reads it from args
+    sub = parser.add_subparsers(dest="cmd", required=True)
+    for container in CONTAINERS:
+        container.register(sub)
+    return parser
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    argv = sys.argv[1:] if argv is None else list(argv)
+    if "run" in argv:   # everything after `run` belongs to the harness, flags included
+        position = argv.index("run")
+        args = build_parser().parse_args(argv[:position + 1])
+        args.rest = argv[position + 1:]
+    else:
+        args = build_parser().parse_args(argv)
+    config = None
+    needs = args.needs_config(args) if callable(args.needs_config) else args.needs_config
+    if needs:
+        from esoi.structure.intent_registry import config as config_module
+        try:
+            config = config_module.load(args.config)
+        except config_module.ConfigError as exc:
+            print(f"esoi: {exc}", file=sys.stderr)
+            return 2
+    return args.handler(config, args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

esoi/apply_esoi.py

@@ -0,0 +1,43 @@
+"""The root of esoi: Apply ESOI to a Project. ``esoi.run("apply-esoi", ".")`` calls the four containers in the order the work happens, each
+through its one-line entry: Understanding, Structure, Optimization, Runtime."""
+from typing import Any, Dict, Protocol, runtime_checkable
+
+from esoi.optimization.interface import Optimizing
+from esoi.runtime.assemble_by_name.lazy_need import Lazy
+from esoi.runtime.implementation_selection.declare import implementation, solution
+from esoi.structure.interface import Structuring
+from esoi.structure.intent_registry import intents
+from esoi.understanding.interface import Understanding
+from esoi.runtime.interface import RuntimeServing
+
+
+@solution("apply-esoi", kind="evaluate", entry="review", example=".")
+@runtime_checkable
+class ApplyingEsoi(Protocol):
+    """How far a project applies ESOI: one read-only report from each container."""
+
+    def review(self, project: str) -> Dict[str, Any]: ...
+
+
+@implementation("apply-esoi", "through-the-four-containers")
+class ThroughTheFourContainers:
+    """Understanding, then Structure, then Optimization, then Runtime, each called through its entry."""
+
+    def __init__(self, understanding: Lazy[Understanding], structure: Lazy[Structuring], optimization: Lazy[Optimizing], runtime: Lazy[RuntimeServing]):
+        self.understanding, self.structure, self.optimization, self.runtime = understanding, structure, optimization, runtime
+
+    def review(self, project: str) -> Dict[str, Any]:
+        with intents.session():    # the record folders are found once for the whole review
+            return {"understanding": self.understanding.review(project), "structure": self.structure.review(project),
+                    "optimization": self.optimization.review(project), "runtime": self.runtime.review()}
+
+
+@implementation("apply-esoi", "documents-only")
+class DocumentsOnly:
+    """What applying ESOI by hand needs: Understanding alone, with no checks and no measurements."""
+
+    def __init__(self, understanding: Lazy[Understanding]):
+        self.understanding = understanding
+
+    def review(self, project: str) -> Dict[str, Any]:
+        return {"understanding": self.understanding.review(project)}

esoi/command_table.py

@@ -0,0 +1,142 @@
+"""Build the sub-command parsers of a container from a text table, so each ``commands.py`` states only what is its own: the commands, their
+arguments and their handlers.
+
+A table is text. A line that starts at the left edge is a command, ``name | options | help``; each indented line under it is one argument,
+``flags | options | help``, where flags are comma-separated (``--from`` or a bare ``name`` for a positional) and options are space-separated
+``key=value`` pairs. The keys are a closed list, and a value is read by what its key means, never by how it looks:
+
+* an argument takes ``action``, ``default``, ``choices`` (a comma list, each read by the argument's ``type``), ``type`` (``int``), ``nargs`` (``?``, ``*``, ``+``,
+  ``REMAINDER`` or a whole number), ``metavar`` (a comma pair makes a tuple), ``dest``, ``required`` (``True`` or ``False``), and ``group=NAME`` to put arguments in one
+  mutually exclusive group;
+* ``default`` is the text after the ``=`` (empty for the empty string, so ``default=8`` is ``"8"`` and ``type=int`` makes ``argparse`` turn it into 8), except the two words
+  ``None`` and ``[]``, which are those values;
+* a command takes ``add_help`` and ``needs_config`` (``True`` or ``False``).
+
+A key, a value or a handler the table does not allow stops the build with a ``TableError`` that names the line. The handler of a command is the
+``run_<name>`` function of the module that owns the table (dashes become underscores).
+"""
+from __future__ import annotations
+
+import argparse
+from typing import Any, Callable, Dict, List, Optional, Tuple
+
+TYPES = {"int": int}
+ARGUMENT_KEYS = ("action", "default", "choices", "type", "nargs", "metavar", "dest", "required", "group")
+COMMAND_KEYS = ("add_help", "needs_config")
+NARGS_WORDS = {"?": "?", "*": "*", "+": "+", "REMAINDER": argparse.REMAINDER}
+DEFAULT_WORDS = {"None": None, "[]": []}
+
+
+class TableError(ValueError):
+    """A line of a command table that cannot be built; the message names the line."""
+
+
+def boolean(text: str, options: Dict[str, Any]) -> bool:
+    if text not in ("True", "False"):
+        raise TableError(f"a boolean option must be True or False, not {text!r}")
+    return text == "True"
+
+
+def type_of(text: str, options: Dict[str, Any]) -> Callable:
+    if text not in TYPES:
+        raise TableError(f"type must be one of {', '.join(TYPES)}, not {text!r}")
+    return TYPES[text]
+
+
+def nargs_of(text: str, options: Dict[str, Any]) -> Any:
+    if text in NARGS_WORDS:
+        return NARGS_WORDS[text]
+    if text.isdigit():
+        return int(text)
+    raise TableError(f"nargs must be ?, *, +, REMAINDER or a whole number, not {text!r}")
+
+
+def choices_of(text: str, options: Dict[str, Any]) -> list:
+    kind = options.get("type", str)   # write type= before choices=
+    try:
+        return [kind(part) for part in text.split(",")]
+    except ValueError:
+        raise TableError(f"choices {text!r} are not all valid for type {kind.__name__}") from None
+
+
+def metavar_of(text: str, options: Dict[str, Any]) -> Any:
+    return tuple(text.split(",")) if "," in text else text
+
+
+def default_of(text: str, options: Dict[str, Any]) -> Any:
+    return DEFAULT_WORDS.get(text, text)
+
+
+READERS: Dict[str, Callable[[str, Dict[str, Any]], Any]] = {
+    "required": boolean, "add_help": boolean, "needs_config": boolean, "type": type_of, "nargs": nargs_of, "choices": choices_of,
+    "metavar": metavar_of, "default": default_of,
+}
+
+
+def option_value(key: str, text: str, options: Dict[str, Any]) -> Any:
+    """One ``key=value`` option as ``argparse`` takes it (text unless the key says otherwise); ``options`` holds the ones read before it on the line."""
+    return READERS.get(key, lambda value, read: value)(text, options)
+
+
+def options_of(text: str, allowed: Tuple[str, ...]) -> Dict[str, Any]:
+    """The ``key=value`` pairs of an options field; a key outside ``allowed`` is an error."""
+    found: Dict[str, Any] = {}
+    for part in text.split():
+        key, equals, value = part.partition("=")
+        if not equals:
+            raise TableError(f"{part!r} is not key=value")
+        if key not in allowed:
+            raise TableError(f"unknown option {key!r} (allowed: {', '.join(allowed)})")
+        found[key] = option_value(key, value, found)
+    return found
+
+
+def split_fields(line: str) -> List[str]:
+    """The three fields of a table line: its name or flags, its options and its help."""
+    fields = [part.strip() for part in line.strip().split("|", 2)]
+    return fields + [""] * (3 - len(fields))
+
+
+def add_argument(parser: argparse.ArgumentParser, line: str, groups: Dict[str, Any]) -> None:
+    flags, text, help_text = split_fields(line)
+    options = options_of(text, ARGUMENT_KEYS)
+    target = parser
+    if "group" in options:
+        name = options.pop("group")
+        if name not in groups:
+            groups[name] = parser.add_mutually_exclusive_group()
+        target = groups[name]
+    if help_text:
+        options["help"] = help_text
+    target.add_argument(*flags.split(","), **options)
+
+
+def add_command(sub, line: str, handlers: Dict[str, Callable], extra: Optional[Dict[str, Dict[str, Any]]]):
+    """The sub-parser of one command line of the table."""
+    name, text, help_text = split_fields(line)
+    options = options_of(text, COMMAND_KEYS)
+    handler = handlers.get("run_" + name.replace("-", "_"))
+    if handler is None:
+        raise TableError(f"command {name!r} has no function run_{name.replace('-', '_')}")
+    parser = sub.add_parser(name, help=help_text, add_help=options.pop("add_help", True))
+    parser.set_defaults(handler=handler, **options, **(extra or {}).get(name, {}))
+    return parser
+
+
+def register(sub, table: str, handlers: Dict[str, Callable], extra: Optional[Dict[str, Dict[str, Any]]] = None) -> None:
+    """Add every command of ``table`` to the sub-parsers ``sub``; ``handlers`` is the owning module's namespace and ``extra`` adds
+    ``set_defaults`` values to a command by name (for a value that is code, such as a function of the parsed arguments)."""
+    parser = None
+    groups: Dict[str, Any] = {}
+    for number, line in enumerate(table.splitlines(), 1):
+        if not line.strip():
+            continue
+        try:
+            if line[0] != " ":
+                parser, groups = add_command(sub, line, handlers, extra), {}
+            elif parser is None:
+                raise TableError("an argument line comes before any command")
+            else:
+                add_argument(parser, line, groups)
+        except (TableError, argparse.ArgumentError) as exc:
+            raise TableError(f"command table line {number} ({line.strip()[:60]!r}): {exc}") from None

esoi/data/esoi_template.csv

@@ -0,0 +1,54 @@
+entity,field_key,question,group,required
+intent,definition,"In ESOI, intents are meaningful containers of a set of specifications. For human understanding, they serve as a personal category of interest or relate to a tangible container such as an organization.",meta,no
+intent,name,What is a specific phrase which distinguishes the topic of the intent from other intents?,specify,yes
+intent,vision_statement,"What is this intent manifesting in present tense? e.g. ""I am ..."" or ""The world is ..."" Any subject and verb can be used.",specify,yes
+intent,opportunities,What are potentials inspired by this intent?,specify,yes
+intent,solution_coherence,What is a paragraph which describes how all the intent's solutions fit together to accomplish the intent's vision statement?,specify,yes
+intent,solution_diagram,"How are solutions connected in the intent's implementation, what is transferred in each edge, and in what direction?",specify,no
+intent,what_it_is_not,"A general category like ""parenting"" or ""career."" An intent is also not an organization itself, rather the container of specification that clarifies why the organization exists (as a solution and implementation within an intent). In this example, different versions of the same organization can be documented as separate alternative implementations.",meta,no
+problem,definition,"A description of what motivated the intent. A challenge, difficulty, or description of how an ideal is not reached.",meta,no
+problem,problem,What is the problem?,specify,yes
+problem,who_has_it,Who or what type of person has the problem?,specify,yes
+problem,why_it_matters,Why does this problem matter?,specify,yes
+problem,why_hard,Why is the problem hard to resolve?,specify,yes
+problem,existing_attempts,What solutions or workarounds already attempt to address the problem?,specify,yes
+problem,what_it_is_not,"A decision, task, recommendation, or component, but all of these can *have* problems.",meta,no
+problem,connects_to,"Ideals that oppose at least one aspect of the problem, Solutions that would solve at least one aspect of the problem",meta,no
+solution,definition,A strategic definition of how one or more problems can be addressed to fulfill the intent.,meta,no
+solution,name,What's a name that describes the type of solution it is?,specify,yes
+solution,description,"What is the solution's unique value proposition, which justifies its existence? (Consider how it differs from other solutions, without explicitly stating anything about other solutions)",specify,yes
+solution,purpose,An inspiring sentence which clarifies the niche of utility that the solution serves without enumerating use cases. Start with a verb and name who or what it serves where relevant.,specify,yes
+solution,approach,"An inspiring sentence which clarifies how the solution solves problems, which applies to every implementation. This is also the solution's human-readable strategy statement. Start with a verb and name no actor (worded like a responsibility).",specify,yes
+solution,out_of_scope,"What type of use cases is the solution intentionally avoiding, which exclusions aren't otherwise apparent or typical? (Don't explicitly name other solutions that aren't in scope)",specify,no
+solution,milestones,"What are the solution's priorities in order? Every solution specifies at least one. Each milestone is a value of one or more metrics, which doesn't have to be the authoritative metric directly but it should relate to it. End condition (optional): Condition for the milestone to no longer be a priority (date or other circumstance), at which point it's archived. Met: Whether the milestone has been reached, and when. Target completion time (optional): Planned completion date and time (which other dependent milestones may rely on). May be a date or a specific minute of a date where precision is needed.",specify,yes
+solution,knowledge,"What knowledge informs the solution's definition or implementations? This can be a list of many items, including chosen assumptions, best guesses, evidence, theories, or perspectives which inform the solution or its implementations.",specify,no
+solution,measures_of_success,"What would indicate the solution is successful? Note: These are metric solutions, with specific fields defined there. However, humans using ESOI may specify this in natural language, which AI can then translate into fully specified metrics.",specify,yes
+solution,tags,"What classifications may be necessary to avoid risk? Risk Addressed: Every tag should name what risk it mitigates, which are linked problems, whether from the same intent as the solution or from other intents (such as R1-R4 below which are problems defined for ESOI). Tags are not problems themselves; they help mitigate structural problems such as through tagging topics or types of technology used. Note: Possible risks (structural problems): R1 (duplication): Adding a new solution that duplicates an existing one. R2 (opportunity): Not leveraging the benefits of an existing solution, such as partial overlap of purpose. R3 (dependency): Not being aware of solutions that need to change definition or implementation due to something else changing. R4 (mistake): Using a solution when it should not be for the particular use case.",specify,no
+solution,parameters,Parameters,interface,no
+solution,inputs,Inputs,interface,no
+solution,outputs,Outputs,interface,no
+solution,effects,Effects (other than outputs),interface,no
+solution,usage_notes,Other information on when and how to use the solution,interface,no
+solution,what_it_is_not,"Fully functional code or solution, but it can be an abstract class, template, or routing which a separate structure solution network defines.",meta,no
+solution,connects_to,"Implementations that build what the solution defines, Metrics that define and implement the solution's measures of success, Problems the solution addresses.",meta,no
+implementation,definition,The built structure which carries out its associated solution; also known as an alternative.,meta,no
+implementation,name,What's a name that distinguishes this implementation from other alternatives?,specify,yes
+implementation,description,"What is the implementation's unique value proposition, to achieve the purpose of its solution? (Consider how it differs from other existing or potential alternatives, without explicitly stating anything about other implementations)",specify,yes
+implementation,advantages,Advantages,specify,yes
+implementation,disadvantages,Disadvantages,specify,yes
+implementation,dependencies,Solutions that the implementation uses. Note: Ideally the ESOI framework used enables automatic dependency awareness.,specify,no
+implementation,what_it_is_not,What end users of the relevant solution directly interact with. The solution provides an interface on top of the implementation. A structure solution defines how solutions will define interfaces.,meta,no
+ideal,definition,"A definition of the future state implied by the intent, in a particular dimension or aspect.",meta,no
+ideal,name,What's a combined noun with adjective that represents the ideal's direction of interest?,specify,yes
+ideal,principle,What does this ideal ask for?,specify,yes
+ideal,state_description,Describe what it would be like to experience this ideal.,specify,yes
+ideal,hints_of_measurement,How would you know this ideal is reached?,specify,yes
+ideal,what_it_is_not,"A practical metric or solution, or technology.",meta,no
+ideal,connects_to,Problems the ideal opposes.,meta,no
+metric,definition,"A practical way to measure the distance between the implementations of a solution and an ideal which the solution was defined to achieve. Alternative implementations are compared via metrics. Consequently, every solution has only one authoritative metric, which can be a combination of multiple metrics or factors with weights that reflect the solution's ideals and purpose. Note: Metrics can also be solutions, as metrics themselves may be refined over time with alternative implementations (including dataset versions). For metrics that cost resources to run, it's recommended to define cascading conditionals.",meta,no
+metric,name,What's a name that clarifies what is being measured?,specify,yes
+metric,purpose,"A statement of what the metric ensures, specifically and comprehensively yet simply stated. This statement does not need to enumerate its current implementation, rather it encapsulates an intention to measure.",specify,yes
+metric,record,What is recorded as the metric to compare implementations?,specify,yes
+metric,disadvantages,"What can the metric not see, or what could it reward wrongly?",specify,no
+metric,cascading_conditionals,"If specified, this ordered list is used when running the authoritative metric and cheaper or prioritized metrics are earlier in the list to determine whether it's worth running subsequent metrics. Each item (conditional) in the list defines (1) the parameters of one of the solution's metrics (e.g. scale, or simulation vs real) and (2) the required value of the metric in order to move onto the next conditional, and optionally (3) other conditions required before it's worth running the metric for that stage of the list. If the metrics are reused with the same parameters across conditionals (each conditional may combine multiple metrics), then this metric is not rerun when executing the subsequent conditional.",specify,no
+metric,expiration,"When do metrics need to be rerun? Never by default, and ESOI projects can have a default which individual metrics can override.",specify,no