mcmas.ispl

  1"""
  2mcmas.ispl:
  3
  4Pydantic models for holding ISPL programs and program- fragments.
  5"""
  6
  7import inspect
  8import json
  9import os
 10import sys
 11from typing import Optional
 12
 13import pydantic
 14from pydantic import Field
 15
 16import mcmas
 17
 18# from . import typing
 19from mcmas import fmtk, typing, util
 20from mcmas.logic import symbols  # noqa
 21from mcmas.models import spec
 22from mcmas.sim import SimType, Simulation
 23
 24Actions = typing.ActionsType
 25
 26LOGGER = util.get_logger(__name__)
 27
 28
 29def check_slice(*args):
 30    assert len(args) in [0, 1]
 31    slice_maybe = args and args[0]
 32    if slice_maybe == Ellipsis or isinstance(slice_maybe, (slice, tuple, type(None))):
 33        return {}
 34    elif isinstance(slice_maybe, (dict,)):
 35        return slice_maybe
 36    else:
 37        err = f"expected slice or dict for posargs, got {[args, type(args)]}"
 38        LOGGER.warning(err)
 39        raise ValueError(err)
 40
 41
 42###############################################################################
 43ObsvarsField = Field(
 44    default={},
 45    description=("Observable variables.  Can be seen by other agents"),
 46)
 47VarsField = Field(
 48    default={},
 49    description=("Private variables. Only the Environment can access"),
 50)
 51ActionsField = Field(
 52    default=[],
 53    description=(
 54        "Defines the set of actions an agent can perform."
 55        "Visible to all other agents."
 56    ),
 57)
 58ProtocolField = Field(
 59    description=(
 60        "Action selection rules; how and when an agent can perform "
 61        "specific actions based on its current state"
 62    ),
 63    default=[],
 64)
 65EvolutionField = Field(
 66    default=[],
 67    description=(
 68        "Defines how an agent's local variables change in "
 69        "response to the actions performed by all agents."
 70    ),
 71)
 72###############################################################################
 73
 74
 75class Fragment(fmtk.Fragment):
 76    """
 77    A piece of an ISPL Specification.
 78
 79    May or may not be "concrete" as of yet, i.e. this may not yet
 80    be useful for actually running a simulation!
 81    """
 82
 83    PROMPT_HINTS: typing.ClassVar = ""
 84    logger: typing.ClassVar = LOGGER
 85
 86    def __init__(self, *args, **kwargs):
 87        """
 88        
 89        """
 90        if args and args[0] and args[0] == Ellipsis:
 91            tmp = self.__class__.get_trivial().model_dump()
 92            tmp.update(**kwargs)
 93            super().__init__(**tmp)
 94        else:
 95            super().__init__(*args, **kwargs)
 96
 97    def __call__(self, **kwargs):
 98        """
 99        
100        """
101        for k, v in kwargs.items():
102            setattr(self, k, v)
103        return self
104
105    def __lt__(self, other) -> bool:
106        """
107        Specification algebra.
108        """
109        if not isinstance(other, self.__class__):
110            raise TypeError(f"Cannot compare {type(self)} and {type(other)}")
111        return self.COMPARATOR(self) < self.COMPARATOR(other)
112
113    def __gt__(self, other) -> bool:
114        """
115        Specification algebra.
116        """
117        return not self.__lt__(other)
118
119    def __class_getitem__(kls, other):
120        """
121        
122        """
123        if other == Ellipsis:
124            return kls(other)
125        else:
126            mod_name = other.__class__.__module__
127            cname = "_load_from_" + mod_name.replace(".", "_")
128            tname = "_load_from_" + type(other).__name__
129            alt = getattr(kls, tname, None)
130            constructor = getattr(kls, cname, alt)
131            if constructor is None:
132                err = (
133                    f"could not find constructor for `{kls}.{cname}` or `{kls}.{tname}`"
134                )
135                LOGGER.critical(err)
136                raise ValueError(err)
137            else:
138                LOGGER.info(f"using constructor: {constructor}")
139                return constructor(other)
140
141    @classmethod
142    def _load_from_prompt(kls, txt, **extra) -> typing.Self:
143        """
144        Create ISPL agent from the given prompt.
145        """
146        import pydantic_ai
147
148        from mcmas.ai import DEFAULT_PROMPT, config
149
150        hints = """"""
151        prompt = DEFAULT_PROMPT + kls.PROMPT_HINTS
152        LOGGER.info(f"Attempting to load object from prompt:\n\n{prompt}")
153        agent = (
154            pydantic_ai.Agent(
155                config.DEFAULT_MODEL,
156                output_type=pydantic_ai.PromptedOutput(
157                    [kls],
158                    template=prompt,
159                ),
160            )
161            .run_sync(txt)
162            .output
163        )
164        # FIXME: agent-only post-processing; move to subclass
165        if hasattr(agent, "name"):
166            agent.name = agent.name.lower()
167        agent.metadata.parser = f"{kls.__module__}.{kls.__name__}._load_from_prompt"
168        return agent
169
170    _load_from_str = _load_from_prompt
171
172    def analyze_types(self) -> typing.List[str]:
173        """
174        
175        """
176        types = []
177        types += getattr(self, "vars", {}).values()
178        types += getattr(self, "obsvars", {}).values()
179        types = sorted(list({x.strip() for x in types}))
180        return types
181
182    def analyze_complexity(self) -> typing.Dict:
183        """
184        
185        """
186        from mcmas.models import spec
187
188        return [spec.ComplexityAnalysis()]
189
190    @pydantic.validate_call
191    def update(self, data: dict) -> typing.Self:
192        """
193        
194        """
195        for k, v in self.model_dump().items():
196            setattr(self, k, v)
197        return self
198
199    @pydantic.validate_call
200    def spec_validate(self) -> typing.Dict:
201        """
202        Full validation output for this fragment (not a simple
203        bool!)
204        """
205        return dict(
206            metadata=self.metadata.model_dump(),
207            validates=self.validates,
208            advice=self.advice,
209        )
210
211    def __invert__(self):
212        """Model interpolation: returns this model"""
213        if not self.advice:
214            LOGGER.warning(f"{self} has no advice and appears complete, returning it.")
215            return self
216        else:
217            err = f"Not sure how from complete object like {self}"
218            LOGGER.critical(err)
219            raise NotImplementedError(err)
220
221
222class Environment(Fragment):
223    """
224    Python wrapper for ISPL Environments. Environments model the
225    shared information and boundary conditions that all other
226    agents can observe.
227
228    See also the relevant [ISPL reference](http://mattvonrocketstein.github.io/py-mcmas/isplref/#environment)
229    """
230
231    REQUIRED: typing.ClassVar = ["protocol", "actions"]
232    DefaultEnvironment: typing.ClassVar
233    actions: typing.ActionsType = ActionsField
234    vars: typing.VarsType = VarsField
235    obsvars: typing.ObsVarsType = ObsvarsField
236    evolution: typing.EvolType = EvolutionField
237    protocol: typing.ProtocolType = ProtocolField
238
239    def __len__(self):
240        """
241        Specification Algebra.
242
243        The length of an agent is the number of items in the
244        description length
245        """
246        return sum(
247            map(
248                len,
249                [
250                    self.actions,
251                    self.evolution,
252                    self.obsvars,
253                    self.protocol,
254                    self.vars,
255                    getattr(self, "lobsvars", []),
256                    getattr(self, "red_states", []),
257                ],
258            )
259        )
260
261    @util.classproperty
262    def DefaultEnvironment(kls):
263        return kls(...)
264
265    @classmethod
266    def get_trivial(kls, *args, **kwargs):
267        kwargs.update(check_slice(*args))
268        actions = kwargs.pop("actions", [symbols.tick])
269        protocol = kwargs.pop("protocol", dict(Other=[symbols.tick]))
270        vars = kwargs.pop("vars", dict(ticking="boolean"))
271        return kls(vars=vars, actions=actions, protocol=protocol, **kwargs)
272
273    @classmethod
274    @pydantic.validate_call
275    def load_from_source(kls, txt: str) -> typing.Self:
276        """
277        Creates an Environment from string.
278        """
279        from mcmas import parser
280
281        agents = parser.extract_agents(txt)
282        env = agents.pop("Environment", None)
283        assert env is not None
284        return Environment(**env)
285
286
287class Agent(Fragment):
288    """
289    Python wrapper for ISPL Agents.
290
291    See also the relevant [ISPL reference](http://mattvonrocketstein.github.io/py-mcmas/isplref/#agent)
292    """
293
294    COMPARATOR: typing.ClassVar = len
295    DefaultAgent: typing.ClassVar
296    REQUIRED: typing.ClassVar = ["protocol", "evolution", "actions"]
297    parser: typing.ClassVar
298
299    name: str = Field(
300        default="player",
301        description=("Name of this agent"),
302    )
303    actions: typing.ActionsType = ActionsField
304    evolution: typing.EvolType = EvolutionField
305    obsvars: typing.ObsVarsType = ObsvarsField
306    protocol: typing.ProtocolType = ProtocolField
307    vars: typing.VarsType = VarsField
308
309    lobsvars: typing.LobsvarsType = Field(
310        description="",
311        default=[],
312    )
313    red_states: typing.List[str] = Field(
314        description="",
315        default=[],
316    )
317
318    __len__ = Environment.__len__
319
320    @util.classproperty
321    def DefaultAgent(kls):
322        """
323        Returns the trivial agent.
324        """
325        return kls(...)
326
327    @classmethod
328    def _load_from_pydantic_ai_agent(kls, pagent, **extra) -> typing.Self:
329        """
330        Create ISPL agent from the given pydantic agent.
331        """
332        kls.logger.info(f"_load_from_pydantic_ai_agent: {pagent}")
333        from mcmas import util
334
335        name = pagent.name or f"Agent_{id(pagent)}"
336        actions = list(pagent._function_toolset.tools.keys())
337        tools = list(pagent._function_toolset.tools.values())
338        tool = tools[0]
339        if len(tools) > 1:
340            kls.logger.warning(f"pydantic agent `{name}` has multiple tools!")
341            kls.logger.warning(f"using just the first one: {tool}")
342        # naive conversion from function signature to ISPL types.
343        vars = util.fxn_sig.as_ispl_types(tool.function)
344        vars.pop("ctx", None)
345        return Agent(
346            name=name,
347            actions=actions,
348            vars=vars,
349            metadata=dict(
350                parser=f"{kls.__module__}.{kls.__name__}._load_from_pydantic_ai_agent",
351                file=inspect.getfile(pagent.__class__),
352            ),
353            **extra,
354        ).model_completion()
355
356    def analyze_symbols(self) -> typing.List[str]:
357        """
358        Returns symbol-related metadata including agent-names,
359        actions, variables, and type info.
360        """
361        return spec.SymbolMetadata(
362            agents=[self.name],
363            actions=self.actions,
364            vars=[k.strip() for k in list(self.lobsvars) + list(self.vars)],
365            types=self.analyze_types(),
366        )
367
368    @property
369    @pydantic.validate_call
370    def analysis(self) -> spec.Analysis:
371        """
372        Static-analysis for this Agent specification.
373
374        Returns details about symbols and logical operators.
375        """
376        return spec.Analysis(
377            symbols=self.analyze_symbols(),
378            types=self.analyze_types(),
379            complexity=self.analyze_complexity(),
380        )
381        # out.actions = [getattr(symbols, x) for x in sorted(list(set(out.actions)))]
382        # out.vars = [getattr(symbols, x) for x in sorted(list(set(out.vars)))]
383        # out.agents = [getattr(symbols, x) for x in sorted(list(set(out.agents)))]
384        # return meta
385
386    def __pow__(self, other: float = 0.1) -> typing.Self:
387        """
388        
389        """
390        from mcmas import ai
391
392        return ai.model_mutation(obj=self, model_settings=dict(top_p=other))
393
394    def __invert__(self) -> typing.Self:
395        """
396        Trigger completion for this Agent.
397
398        This is NOT backed by an LLM; see instead `mcmas.ai.agent_completion`.
399        """
400        if not self.advice:
401            err = f"{self} is already valid, returning it instead of completing"
402            LOGGER.warning(err)
403            return self
404        else:
405            tmp = self
406            trivial = DefaultAgent
407            defaults = dict(
408                protocol=trivial.protocol,
409                vars=trivial.vars,
410                evolution=trivial.evolution,
411            )
412            for x in ["protocol", "vars", "evolution"]:
413                if getattr(self, x, None):
414                    pass
415                else:
416                    LOGGER.warning(f"could not find required {x}")
417                    tmp = tmp.model_copy(update={x: defaults[x]})
418            return tmp.model_copy(
419                update=dict(actions=list(set(tmp.actions + trivial.actions)))
420            )
421
422    model_completion = __invert__
423
424    @classmethod
425    def get_trivial(kls, *args, **kwargs):
426        """
427        Smallest legal agent.
428        """
429        kwargs.update(check_slice(*args))
430        return kls(
431            name="trivial",
432            vars=dict(ticking="boolean"),
433            actions=["tick"],
434            protocol=["Other : {tick}"],
435            evolution=["ticking=true if Action=tick;"],
436        )
437
438    def model_dump_source(self):
439        """
440        Dump the source-code for this piece of the specification.
441        """
442        from mcmas import rendering
443
444        return rendering.get_template("Agent.j2").render(
445            name=self.name, agent=self.model_dump()
446        )
447
448    @util.classproperty
449    def parser(self) -> typing.Callable:
450        """
451        Return an appropriate parser for this spec-fragment.
452        """
453        from mcmas import parser
454
455        return parser.extract_agents
456
457    @classmethod
458    @pydantic.validate_call
459    def load_from_source(kls, txt, strict: bool = False) -> typing.Self:
460        """
461        Load ISPL agent from string.
462        """
463        agents = kls.parser(txt)
464        agents.pop("Environment", None)
465        if len(agents) != 1:
466            LOGGER.critical("load_from_source: more than 1 agent! returning first..")
467        return Agent(**list(agents.values())[0])
468
469    @property
470    def local_advice(self) -> list:
471        return []
472
473
474DefaultAgent = Agent.DefaultAgent
475DefaultEnvironment = Environment.DefaultEnvironment
476
477
478class ISpec(fmtk.Specification):
479    """
480    
481    """
482
483
484import functools
485import operator
486
487
488class ISPL(Fragment):
489    """
490    Python wrapper for ISPL specifications.
491
492    This permits partials or "fragments", i.e. the specification need not be complete and ready to run.
493
494    See the ISPL reference here: http://mattvonrocketstein.github.io/py-mcmas/isplref
495    """
496
497    PROMPT_HINTS: typing.ClassVar = "Individual proper nouns refer to separate agents."
498
499    def __str__(self):
500        return f"<ISPL: agents={len(self.agents)} vars={len(self.environment.vars)}>"
501
502    def analyze_types(self):
503        types = super().analyze_types()
504        for agent in self.agents.values():
505            types += agent.analyze_types()
506        return list(set(types))
507
508    @classmethod
509    def get_trivial(kls, *args, **kwargs):
510        """
511        ISPL(...) notation.  Unlike ISPL(..)
512
513        This returns the trivial specification, with just enough
514        structure to validate and run, plus any optional
515        overrides.
516        """
517        kwargs.update(check_slice(*args))
518        title = kwargs.pop("title", "Minimal valid ISPL specification")
519        agents = kwargs.pop("agents", {"DefaultAgent": DefaultAgent})
520        environment = kwargs.pop("environment", Environment(...))
521        evaluation = kwargs.pop("evaluation", ["ticking if Environment.ticking=true"])
522        init_states = kwargs.pop("init_states", ["Environment.ticking=true"])
523        formulae = kwargs.pop("formulae", ["ticking"])
524        return kls(
525            title=title,
526            environment=environment,
527            evaluation=evaluation,
528            init_states=init_states,
529            formulae=formulae,
530            agents=agents,
531            **kwargs,
532        )
533
534    # Metadata: typing.ClassVar = fmtk.SpecificationMetadata
535    COMPARATOR: typing.ClassVar = abs
536    REQUIRED: typing.ClassVar = ["agents", "evaluation", "formulae"]
537    parser: typing.ClassVar
538    title: str = Field(
539        default="Untitled Model",
540        description="Optional title.  Used as a comment at the top of the file",
541    )
542    agents: typing.Dict[str, Agent] = Field(
543        default={},
544        description="All agents involved in this specification.  A map of {name: agent_object}",
545    )
546    environment: Environment = Field(
547        default={},
548        description="The environment for this specification",
549    )
550    fairness: typing.Dict[str, typing.List[str]] = Field(
551        default={},
552        description=(
553            "Specifies conditions that must hold infinitely often along "
554            "all execution paths, used to rule out unrealistic behaviors."
555        ),
556    )
557    init_states: typing.InitStateType = Field(
558        default=[],
559        description="Initial global states of the system when verification begins.",
560    )
561    evaluation: typing.EvalType = Field(
562        default=[],
563        description="Calculations, composites, aggregates that can be referenced in formulae",
564    )
565    groups: typing.GroupsType = Field(
566        default={},
567        description=(
568            "A map of {group_name: [member1, .. ]}"
569            "Defines collections of agents for use in group-based verification formulae."
570        ),
571    )
572
573    formulae: typing.FormulaeType = Field(
574        description=(
575            "A list of formulas.\n\n"
576            "These will be partitioned into true/false categories, per the rest of the model"
577        ),
578        default=[],
579    )
580    simulation: SimType = Field(
581        default=None,
582        description=(
583            "The result of simulating this specification.  "
584            "Empty if simulation has never been run"
585        ),
586    )
587    source_code: typing.Union[str, None] = Field(
588        default=None,
589        description=(
590            "Source code for this specification.  "
591            "Only available if the specification was loaded from raw ISPL"
592        ),
593    )
594
595    def __contains__(self, other):
596        """
597        Specification algebra.
598        """
599        if isinstance(other, Agent):
600            return other in self.agents.values()
601        else:
602            raise TypeError(f"__contains__ undefined for {[type(self), type(other)]}")
603
604    def __abs__(self) -> float:
605        """
606        Specification algebra.
607
608        Used in __lt__ and __gt__. For ISPL specifications this
609        is the cumulative sum of formulae complexity
610        """
611        return sum([c.score for c in self.analyze_complexity()])
612
613    def __iadd__(self, other):
614        """
615        Specification algebra.
616
617        This is for in-place addition, i.e. `spec+=Agent(..)`
618        """
619        upd = self + other
620        self.update(upd.model_dump())
621        return self
622
623    def __sub__(self, other):
624        """
625        Specification algebra.
626
627        ISPL - agent => removes agent from this agent list, if present.
628        """
629        # if isinstance(other, (ISPL,)):
630        #     return self.model_copy(update=other.model_dump())
631        # if isinstance(other, (Environment,)):
632        #     return self.model_copy(update=dict(environment=other))
633        if isinstance(other, (Agent,)):
634            agents = {}
635            for a in self.agents.values():
636                if a.name != other.name:
637                    agents[a.name] = a
638            return self.model_copy(update=dict(agents=agents))
639        raise TypeError(f"Cannot add {type(self)} and {type(other)}")
640
641    def __add__(self, other):
642        """
643        Specification algebra.
644
645        ISPL + agent => adds agent to spec ISPL + ISPL =>
646        overrides first spec with values from 2nd
647        """
648        if isinstance(other, (ISPL,)):
649            return self.model_copy(update=other.model_dump())
650        if isinstance(other, (Environment,)):
651            return self.model_copy(update=dict(environment=other))
652        if isinstance(other, (Agent,)):
653            agents = self.agents
654            agents.update(**{other.name: other})
655            return self.model_copy(update=dict(agents=agents))
656        raise TypeError(f"Cannot add {type(self)} and {type(other)}")
657
658    def model_dump_source(self):
659        """
660        Dump the source-code for this piece of the specification.
661        """
662        # from mcmas.engine import dict2ispl
663        return util.dict2ispl(self.model_dump())
664
665    @util.classproperty
666    def parser(self):
667        """
668        Shortcut for `mcmas.parser.parse`
669        """
670        from mcmas import parser
671
672        return parser.parse
673
674    @property
675    def local_advice(self) -> list:
676        """
677        
678        """
679        out = []
680        for agent in self.agents:
681            agentish = self.agents[agent]
682            out += agentish.advice
683        return out
684
685    @classmethod
686    @pydantic.validate_call
687    def load_from_source(
688        kls, txt, strict: bool = False
689    ) -> typing.Dict[str, typing.Self]:
690        """
691        Return ISPL object from given string.
692        """
693        # from mcmas import parser
694        return kls.parser(txt)
695
696    @classmethod
697    @pydantic.validate_call
698    def load_from_ispl_file(
699        kls,
700        file: Optional[str] = None,
701    ):
702        """
703        Return ISPL object from contents of given file.
704        """
705        LOGGER.debug(f"ISPL.load_from_ispl_file: {file}")
706        metadata = dict(file=file)
707        if file:
708            assert os.path.exists(file), f"no such file: {file}"
709            if file.endswith("ispl"):
710                with open(file) as fhandle:
711                    text = fhandle.read()
712                    tmp = kls.parser(text, file=file)
713                    data = tmp.model_dump(exclude="metadata")
714                    return ISPL(metadata=ISPL.Metadata(**metadata), **data)
715            #    return ISPL(metadata=dict(file=file, engine="bonk"), **data)
716            elif file.endswith("json"):
717                raise ValueError("refusing to work with ispl file")
718            elif file in ["-", "/dev/stdin"]:
719                metadata.update(file="<<stream>>")
720                text = sys.stdin.read().strip()
721                data = kls.parser(text).model_dump(exclude="metadata")
722                return ISPL(metadata=ISPL.Metadata(**metadata), **data)
723            else:
724                LOGGER.critical(f"could not create model from {file}")
725                raise Exception(file)
726        if text:
727            LOGGER.critical("NIY")
728            raise Exception(text)
729
730    load_from_file = load_from_ispl_file
731
732    @classmethod
733    @pydantic.validate_call
734    def load_from_json_file(kls, file: Optional[str] = None, text=None):
735        """
736        Return ISPL object from the contents of given file.
737
738        File *must* be JSON encoded.
739        """
740        LOGGER.critical(f"ISPL.load_from_json_file: {file}")
741        metadata = dict(file=file)
742        if file:
743            assert os.path.exists(file), f"no such file: {file}"
744            if file.endswith("json"):
745                with open(file) as fhandle:
746                    data = json.loads(fhandle.read())
747                return ISPL(metadata=ISPL.Metadata(**metadata), **data)
748            elif file.endswith("ispl"):
749                raise ValueError("refusing to work with ispl file")
750            elif file in ["-", "/dev/stdin"]:
751                metadata.update(file="<<stream>>")
752                text = sys.stdin.read().strip()
753                data = json.loads(text)
754                return ISPL(
755                    metadata=ISPL.Metadata(**{**data.pop("metadata", {}), **metadata}),
756                    **data,
757                )
758            else:
759                LOGGER.critical(f"could not create model from {file}")
760                raise Exception(file)
761
762        if text:
763            LOGGER.critical("NIY")
764            raise Exception(text)
765
766    @property
767    @pydantic.validate_call
768    def validates(self) -> bool:
769        """
770        Asks the engine directly whether this spec validates.
771
772        Note that this is ground-truth and not heuristic like the `valid` property elsewhere!
773        """
774        return mcmas.engine.validate(model=self)
775
776    @property
777    @pydantic.validate_call
778    def analysis(self) -> spec.Analysis:
779        """
780        Static-analysis for this ISPL specification.
781
782        Returns details about symbols and logical operators.
783        """
784        ents = list(self.agents.values())
785        ents += [self.environment]
786        vars = []
787        for agent in ents:
788            if isinstance(agent, (Agent,)):
789                vars += [k.strip() for k in (agent.lobsvars or []) if k.strip()]
790            vars += [k.strip() for k in (agent.vars or []) if k.strip()]
791        vars = list(set(vars))
792        meta = dict(
793            symbols=spec.SymbolMetadata(
794                agents=[agent for agent in self.agents],
795                vars=vars,
796                actions=list(
797                    set(
798                        functools.reduce(
799                            operator.add,
800                            [self.agents[agent].actions for agent in self.agents],
801                        )
802                    )
803                ),
804            ),
805            types=self.analyze_types(),
806            complexity=self.analyze_complexity(),
807        )
808        meta = spec.Analysis(**meta)
809        return meta
810
811    def analyze_complexity(self) -> typing.List:
812        from mcmas.logic import complexity
813
814        return [
815            complexity.analyzer.analyze(f.lstrip().rstrip(), index=i)
816            for i, f in enumerate(self.formulae)
817        ]
818
819    def exec(self, strict: bool = False, **kwargs) -> typing.Self:
820        """
821        Execute this ISPL specification.
822        """
823        required = ["init_states"]
824        self.logger.debug(f"validating: {self.source_code or self.model_dump_source()}")
825
826        # check advice before execution
827        if self.advice:
828            msg = "exec: Model has non-empty advice!"
829            LOGGER.critical(msg)
830            if strict:
831                raise RuntimeError(msg)
832
833        for k in required:
834            if not getattr(self, k):
835                err = f"Validation failed.  Required key `{k}` is missing."
836                return self.model_copy(
837                    update={
838                        # "source_code": src,
839                        "simulation": Simulation(
840                            error=err,
841                            metadata=Simulation.Metadata(parsed=False, validates=False),
842                        ),
843                    }
844                )
845
846        self.logger.debug("starting..")
847        sim = mcmas.engine(text=self.model_dump_source(), output_format="model")
848        out = self.model_copy(
849            update=dict(
850                source_code=self.source_code or self.model_dump_source(),
851                simulation=sim,
852                metadata=self.metadata.model_dump(),
853            )
854        )
855        self.logger.debug("done")
856        return out
857
858    run_sim = run_simulation = exec
859
860    def repl(self):
861        """
862        Start a REPL shell with this object available as `spec`.
863        """
864        result_model = self.exec()
865        return util.repl(spec=result_model)
866
867
868DefaultISPL = ISPL(...)