DOCUMENTATION / Building Models
Design for inquiry and agent interaction
Agent interaction
Expose bounded operations that describe their effects, inputs and failure modes. Separate observation from mutation. An agent should discover capabilities without guessing implementation details.
Structure of a model suite
A suite can include executable code, datasets, documentation, algorithms, neural networks, visualization applications and validation evidence. Keep each constituent model’s purpose explicit. One model is a valid starting suite. Solar System currently combines one approximate orbital model with visualization and distance-analysis tools; it is not evidence of several composed scientific solvers. A model may expose a visual interface or run without one.
Scientific and analytical contracts
Describe what is represented, what is computed, acceptable inputs, output meaning and known failure regimes. Specify units, reference frames, time scales and uncertainty. Keep the scientific contract distinct from packaging.
State, inputs, outputs and versions
Define serializable state, input validation and reproducible outputs. Version code, datasets and interfaces. Explain migrations and which settings influence computation rather than presentation.
MCP and agent-facing interfaces
MCP is one agent-facing interface, not a required replacement for every existing API. Document lifecycle, readiness, authentication, state ownership and acknowledgements. The Solar System browser currently owns the simulation state.
Validation, documentation and provenance
Retain source identifiers, retrieval metadata, transformations and tests. Mathematical invariants and software tests are useful but do not replace independent scientific validation. Publish validation gaps explicitly.
Composition and compatibility
Compatibility requires more than matching field names. Exchange data or state only after checking scientific assumptions, interface contracts, dimensions, units, reference frames, timescales, epochs, uncertainty and versions. Generic model composition is future work.
Preparing for publication
Provide a repository, scientific description, category metadata, documentation, licensing and validation evidence. Submit for curated review. The Phase 2 catalog uses a deliberately small display-data format; it is not a finalized distribution protocol.