Package io.jmix.dynmodelai

Interface DynamicModelAgentService

All Known Implementing Classes:
DynamicModelAgentServiceImpl
public interface DynamicModelAgentService
Application API for the Dynamic Model agent. Run commands and event requests report unavailable or conflicting temporary state through AgentRequestException. Invalid arguments, access denials and infrastructure failures retain their original exception types. Asynchronous Run failures arrive in RunCompleted.

Simple v1 is used from the existing Full Access administrative interface. The agent adds no authentication, permission or ownership checks. Dynamic Model enforces its own operation and publication rules. Author fields record history; Run commands carry the caller into background work. The agent never publishes: the host transfers a Draft to its editor, and the user applies it there.

  • Method Details

    • recordEditorPublication

      ConversationMessage recordEditorPublication(UUID conversationId, @Nullable UUID baselineSettingsId, UUID publishedSettingsId)
      Records an already committed host publication. Failure here never rolls back that publication.

    • getConversations

      org.springframework.data.domain.Page<ConversationSummary> getConversations(org.springframework.data.domain.Pageable pageable)
      Returns conversations ordered by lastModifiedDate descending, then id descending. Requires an unsorted, paged request of at most 200 records; otherwise throws IllegalArgumentException. Pages are not a snapshot of live history.

    • getRunHistoryLocation

      RunHistoryLocation getRunHistoryLocation(UUID runId, int messagePageSize) throws NoSuchElementException
      Locates a Run without scanning message pages; throws when no saved message exists.
      Throws:
      NoSuchElementException

    • getConversation

      ConversationDetails getConversation(UUID conversationId) throws NoSuchElementException
      Returns information about one Conversation without loading or counting its messages.
      Throws:
      NoSuchElementException - if the Conversation does not exist

    • getConversationMessages

      org.springframework.data.domain.Page<ConversationMessage> getConversationMessages(UUID conversationId, org.springframework.data.domain.Pageable pageable) throws NoSuchElementException
      Returns persisted messages ordered by createdDate ascending, then id ascending, with their total count. Requires an unsorted, paged request of at most 200 records; otherwise throws IllegalArgumentException. The Conversation must exist; an existing empty Conversation returns an empty page. The id resolves equal timestamps deterministically, not causally. Pages are not a snapshot of live history.
      Throws:
      NoSuchElementException - if the Conversation does not exist

    • getRunHistory

      org.springframework.data.domain.Page<AgentHistoryRecord> getRunHistory(UUID conversationId, UUID runId, org.springframework.data.domain.Pageable pageable)
      Returns persisted Run events in sequence order, independently of runtime retention. Requires an unsorted page of at most 200 records. An existing Conversation with no recorded events for this Run returns an empty page, including Runs predating history recording. Reading history neither opens a session nor restores its Run or Draft. Historical sequence includes diagnostics and is independent of the live event cursor.
      Throws:
      NoSuchElementException - if the Conversation does not exist

    • getRunSnapshots

      org.springframework.data.domain.Page<AgentHistoryRecord> getRunSnapshots(UUID conversationId, UUID runId, org.springframework.data.domain.Pageable pageable)
      Saved plan and terminal snapshots only, without loading the execution trace or model diagnostics.

    • submitMessage

      AgentRun submitMessage(SubmitMessageRequest request) throws NoSuchElementException
      Starts the asynchronous conversational graph with the request's explicit plan approval mode. Repeating the call creates a new Run. A plan waiting for manual approval is cancelled and supplied as unexecuted context for the new request, which must carry the same editor snapshot. Other active Runs reject the request with RUN_STATE_CONFLICT. An editor snapshot uses fresh complete editor content, without publishing it; without a snapshot the Run starts from the published model. A successful Run replaces the previous Draft.
      Throws:
      NoSuchElementException - if a supplied Conversation id does not exist

    • isRunActive

      boolean isRunActive(AgentRun run)
      Checks whether this exact Run is still active, including waiting for plan approval. Returns false for terminal, unknown or expired Runs. Reads temporary state only, without opening a session, restoring history or refreshing its idle timeout.

    • streamEvents

      reactor.core.publisher.Flux<AgentEvent> streamEvents(AgentEventsRequest request)
      Replays retained events after the requested sequence and then emits live events until RunCompleted. A mandatory history write failure terminates this stream with an error and stops the Run. Diagnostics are available through getRunHistory(java.util.UUID, java.util.UUID, org.springframework.data.domain.Pageable), not this live stream. Unknown Runs (RUN_UNAVAILABLE) and gaps in retained history (EVENT_HISTORY_UNAVAILABLE) are rejected when this method is called, before subscription. If requested events are lost before subscription, the stream signals EVENT_HISTORY_UNAVAILABLE before delivering an event after the gap.

    • approvePlan

      void approvePlan(ApprovePlanRequest request)
      Approves the currently proposed plan. Execution starts asynchronously; repeated approval fails with RUN_STATE_CONFLICT. Unknown or expired Runs fail with RUN_UNAVAILABLE. Workspace preparation and execution happen in the resumed graph; failures end the Run through RunCompleted and clean up its workspace.

    • answerHumanInput

      AgentRun answerHumanInput(AnswerHumanInputRequest request) throws NoSuchElementException
      Answers a pending question by starting a new Run in the same Conversation. Duplicate, closed or unknown questions fail with HUMAN_INPUT_UNAVAILABLE.
      Throws:
      NoSuchElementException - if the question's Conversation no longer exists

    • cancelRun

      boolean cancelRun(CancelRunRequest request)
      Returns true only when this call cancelled an active Run, false for a retained terminal Run. If Draft completion has already started, waits for its result without undoing it. Unknown or expired Runs fail with RUN_UNAVAILABLE.

    • closeConversationSession

      void closeConversationSession(UUID conversationId)
      Ends the temporary work of one open Conversation UI. Persisted Conversation messages and Dynamic Model settings are not changed. Simple v1 expects one open Builder per Conversation. Waits for this session's registration and Draft cleanup, not for the full language-model call. Reopen the Conversation only after this command completes successfully.

    • touchConversationSession

      void touchConversationSession(UUID conversationId)
      Tells the Engine that a Builder still works with the Conversation. Every other call of the Conversation counts as well. Temporary work nobody touched for the configured idle timeout is closed by the Engine as if the Builder had been closed.

    • getDraftModel

      EditorModelSnapshot getDraftModel(DraftReviewRequest request)
      Returns the complete candidate of the exact current successful Run, including unrelated settings. Intended for atomic transfer to a shared editor after RunCompleted(DRAFT_READY). Does not publish settings.

    • reviewEditorModel

      EditorModelReview reviewEditorModel(EditorModelSnapshot snapshot)
      Validates the complete current editor, including manual changes, without creating a Run or Draft. Returns final configurations of changed entities. A successful review does not reserve the captured revision.