Package net.thevpc.naru.api.agent

Interface NaruSession

public interface NaruSession

  • Method Details

    • getVisibility

      NaruVisibility getVisibility()

    • throttleDelay

      NaruSession throttleDelay(long ms)

    • scheduler

      NaruScheduler scheduler()

    • setVisibility

      NaruSession setVisibility(NaruVisibility visibility)

    • agent

      NaruAgent agent()

    • hasMoreStatements

      boolean hasMoreStatements()

    • projectDir

      NPath projectDir()

    • terminate

      NaruSession terminate()

    • log

      void log(NaruLogMode mode, NMsg s)

    • logStream

      default void logStream(NaruLogMode mode, NMsg fragment, boolean end)
      Reports a fragment of output that is still being produced, for a user who is meant to watch it arrive. Fragments of one mode join in order; the last call for a mode passes end=true.

      The default reports through log(net.thevpc.naru.api.agent.NaruLogMode, net.thevpc.nuts.text.NMsg), so a session that has no notion of streaming still shows every fragment -- as whole messages, and in the same text. Only the output is at stake here, never the work: this is a side channel, and a consumer that cannot draw incrementally must not lose the text.

    • workingDir

      NPath workingDir()

    • setWorkingDir

      NaruSession setWorkingDir(NPath workingDir)

    • toElement

      NElement toElement()

    • uuid

      String uuid()

    • restoreSnapshot

      NaruSession restoreSnapshot()

    • load

      NaruSession load(String otherUuid)

    • reload

      NaruSession reload()

    • save

      NaruSession save()

    • saveSnapshot

      NaruSession saveSnapshot()

    • copy

      NaruSession copy()

    • reset

      NaruSession reset(boolean preserveIdentity)

    • removeModelAlias

      void removeModelAlias(String alias)

    • addModelAlias

      void addModelAlias(String alias, NaruModelConfig model)

    • findModelAlias

      NOptional<NaruModelConfig> findModelAlias(String alias)

    • creationInstant

      Instant creationInstant()

    • modificationInstant

      Instant modificationInstant()

    • name

      String name()

    • setName

      NaruSession setName(String name)

    • sessionStoreManager

      NaruSessionStoreManager sessionStoreManager()
      The catalog of sessions saved to disk in this project.

      Distinct from NaruAgent.sessions(), which is the set of sessions currently running in this JVM. Nothing here is live: these are directories under .naru/sessions/ that can be listed, restored, purged or deleted, and they are not required to have ever been started in this process.

    • registry

      NaruRegistry registry()

    • findModel

      NOptional<NaruModelConfig> findModel(String modelNameOrId)

    • listedModels

      List<NaruModelKey> listedModels()
      Snapshot of the models displayed by the last /model listing, in display order. Positional indexes (/model use <n>) are resolved against this snapshot first, so that a filtered listing such as /model --free or /model --provider=x keeps its indexes valid even though filtering renumbers the rows.
      Returns:
      last displayed models, or an empty list if no listing happened yet.

    • setListedModels

      NaruSession setListedModels(List<NaruModelKey> models)
      Records the models displayed by a /model listing so subsequent /model use <n> calls resolve indexes against the same rows.

    • modelAliases

      Map<String,NaruModelConfig> modelAliases()

    • reversedModelAliases

      Map<NaruModelConfig,List<String>> reversedModelAliases()

    • getProjectEnv

      NOptional<NElement> getProjectEnv(String key)

    • setProjectEnv

      void setProjectEnv(String key, NElement value, NaruVisibility visibility)

    • getSessionEnv

      NOptional<Object> getSessionEnv(String key)

    • unsetSessionEnv

      NaruSession unsetSessionEnv(String key)

    • setSessionEnv

      NaruSession setSessionEnv(String key, Object value)

    • tasks

      List<NaruTask> tasks()

    • newTask

      NaruTask newTask(NaruTaskSpec taskBuilder)

    • run

      NaruTask run(NaruTaskSpec spec)
      Create a task from spec, start it, and return it.

      This is the main entry point for embedding. The returned task is its own handle: wait on it, compose it as a future, or give it a completion callback, without the caller having to track the task id or re-look it up. The latter matters because a task is deregistered from the session as soon as it terminates, and stays answerable on its own afterwards.

      The session must already be running; call start() first, or use run() to do both in one step. A session stops itself when its last task ends, so a session meant to serve several requests needs one long-lived task holding it open.

      Parameters:
      spec - what to run, must not be null
      Returns:
      the new task, already started
      Throws:
      IllegalStateException - if the session is not running

    • run

      NaruTask run()
      Start the session if it is not already running, then run the task it was configured with, and return that task.

      The one-liner for the common case, where a session exists to run exactly one task: 

      
 NaruTask t = agent.newSession()
         .task(NaruTaskSpec.of().statements("/return 1+1"))
         .build()
         .run();
 t.await();
      Calling it on a session configured without a task, or calling it twice, throws: the configured task is one specific invocation, and silently running again would be a surprising way to lose a result.
      Returns:
      the configured task, already started
      Throws:
      IllegalStateException - if the session has no task configured, or already ran it

    • findTask

      NOptional<NaruTask> findTask(long tid)

    • foregroundTaskId

      long foregroundTaskId()

    • foregroundTaskId

      NaruSession foregroundTaskId(long taskId)

    • isRunning

      boolean isRunning()

    • start

      NaruSession start()

    • stop

      NaruSession stop()

    • waitFor

      NaruSession waitFor()

    • systemPrompt

      String systemPrompt()

    • systemPrompt

      NaruSession systemPrompt(String systemPrompt)

    • findTaskIdsByParent

      long[] findTaskIdsByParent(long taskId)

    • eventLog

      NaruSessionEventLog eventLog()

    • addSessionListener

      void addSessionListener(NaruSessionListener listener)

    • removeSessionListener

      void removeSessionListener(NaruSessionListener listener)

    • deliverInput

      void deliverInput(String line)
      Hands a line of user input to the session, from any thread.

      This is how a host answers a NaruInputRequest. A terminal hands over what the readline thread read; a web front end hands over what the browser posted, possibly long after the question was asked and from a different process. The line goes to the foreground task if one is blocked on input, and is treated as a session command otherwise.

    • addUsageListener

      void addUsageListener(NaruSessionUsageListener listener)
      Registers a listener for model-call usage and provider rate limits. Notifications are delivered on the thread that made the call, so a listener must not block.

    • removeUsageListener

      void removeUsageListener(NaruSessionUsageListener listener)

    • reportProviderRateLimits

      void reportProviderRateLimits(NaruProviderRateLimitInfo info)
      Announces a provider's self-reported rate limits to every NaruSessionUsageListener. Called by model protocols that receive limit headers; providers that send none never call it. Observers that throw are ignored.

    • routines

      List<NaruResourceInfo> routines()

    • routine

      NOptional<NaruRoutine> routine(String nameOrPath, NaruTask task, boolean orCreate)

    • getSessionEnv

      Map<String,Object> getSessionEnv()

    • loadModelConfig

      NOptional<NaruModelConfig> loadModelConfig(String modelName)

    • saveModelConfig

      void saveModelConfig(String modelName, NaruModelConfig config)