Class Resource

java.lang.Object
uno.anahata.asi.agi.event.BasicPropertyChangeSource
uno.anahata.asi.agi.resource.Resource
All Implemented Interfaces:
ContextProvider, PropertyChangeSource, Rebindable
public class Resource extends BasicPropertyChangeSource implements Rebindable, ContextProvider
The Universal Resource Orchestrator.

Coordinates between a ResourceHandle (Source) and a ResourceView (Interpreter). Implements ContextProvider for seamless integration into the RAG pipeline.

Reactivity: This class extends BasicPropertyChangeSource to provide live state synchronization to UI components and host-aware managers.

Author:
anahata

  • Field Details

    • agi

      private Agi agi
      The parent AGI session this resource belongs to.

      Bidirectional references are managed natively by the Kryo serialization engine.

    • uuid

      private final String uuid
      The immutable unique identifier for this resource instance.

    • handle

      private final ResourceHandle handle
      The source handle providing access to raw data and metadata.

    • view

      private ResourceView view
      The interpreter view responsible for processing and presenting content.

    • refreshPolicy

      private RefreshPolicy refreshPolicy
      Policy for when to reload the content from the handle. Defaults to LIVE.

    • contextPosition

      private ContextPosition contextPosition
      The designated position for this resource in the model's prompt. Defaults to PROMPT_AUGMENTATION.

    • providing

      private boolean providing
      Whether this resource is currently providing context to the model.

    • description

      private String description
      A descriptive summary of how and when the resource was registered.

    • registrationTime

      private long registrationTime
      The epoch timestamp in milliseconds when this resource was registered. Set authoritatively by the ResourceManager.

    • lastLoadTimestamp

      private long lastLoadTimestamp
      The timestamp of the last successful content reload from the handle.

    • dirty

      private boolean dirty
      Internal flag indicating the resource or its view configuration is dirty and needs re-interpretation.

  • Constructor Details

    • Resource

      public Resource(ResourceHandle handle)
      Constructs a new Resource orchestrator.
      Parameters:
      handle - The source handle providing physical/virtual connectivity.

  • Method Details

    • getId

      public String getId()
      The uuid of the resource is the context provider id.
      Specified by:
      getId in interface ContextProvider
      Returns:
      uuid

    • asText

      public String asText() throws IOException
      Returns the full content of the resource as a String.

      Handy API: Delegates to the handle's asText() which manages streams and charsets.

      Returns:
      The full text content.
      Throws:
      IOException - if reading fails.

    • asBytes

      public byte[] asBytes() throws IOException
      Returns the full content of the resource as a byte array.
      Returns:
      The full binary content.
      Throws:
      IOException - if reading fails.

    • write

      public void write(String content) throws IOException
      Authoritatively writes text content back to the source handle and marks the resource as dirty to ensure a subsequent reload.

      Technical Purity: This is the singular entry point for mutations, managing both connectivity and state management in one weld.

      Parameters:
      content - The text to write.
      Throws:
      IOException - if the write fails.

    • isWritable

      public boolean isWritable()
      Checks if the resource is writable in the current environment.
      Returns:
      true if the underlying handle supports writing.

    • getName

      public String getName()
      Gets the human-readable name of this context provider.

      Implementation details: Delegates name resolution to the underlying handle.

      Specified by:
      getName in interface ContextProvider
      Returns:
      The provider's name.

    • getHtmlDisplayName

      public String getHtmlDisplayName()
      Returns an HTML-formatted display name.

      Purity Note: This allows the Swing layer to display IDE status (Git status, errors) while maintaining context-level identity.

      Returns:
      The HTML display name from the handle, or null.

    • markDirty

      public void markDirty()
      Marks the resource as dirty, triggering a re-interpretation during the next Turn or manual UI refresh.

    • setRefreshPolicy

      public void setRefreshPolicy(RefreshPolicy policy)
      Sets the refresh policy and fires a property change event if different.
      Parameters:
      policy - The new policy (LIVE or SNAPSHOT).

    • setContextPosition

      public void setContextPosition(ContextPosition position)
      Sets the context position and fires a property change event if different.
      Parameters:
      position - The new position (SYSTEM_INSTRUCTIONS or PROMPT_AUGMENTATION).

    • setProviding

      public void setProviding(boolean providing)
      Sets the providing status and fires a property change event if different.
      Specified by:
      setProviding in interface ContextProvider
      Parameters:
      providing - True to enable context contribution.

    • isEffectivelyProviding

      public boolean isEffectivelyProviding()
      Checks if this provider is effectively providing context, meaning it is enabled AND all its ancestors in the hierarchy are also enabled.

      Implementation details: Resources are effectively providing if they are explicitly enabled.

      Specified by:
      isEffectivelyProviding in interface ContextProvider
      Returns:
      true if effectively providing, false otherwise.

    • populateMessage

      public void populateMessage(RagMessage ragMessage) throws Exception
      Populates the given RagMessage with dynamic, just-in-time context parts. These parts are appended to the end of the user's prompt (RAG).

      Implementation details: Performs a 'Pure Sense' of the resource view. Freshness must be guaranteed by turn-level orchestration calling reloadIfNeeded() prior to RAG generation.

      Specified by:
      populateMessage in interface ContextProvider
      Parameters:
      ragMessage - The message to be augmented with context.
      Throws:
      Exception - if an error occurs during context generation.

    • getSystemInstructions

      public List<String> getSystemInstructions() throws Exception
      Gets a list of system instruction strings provided by this context provider. These are typically prepended to the conversation as high-level guidance.

      Implementation details: Performs a 'Pure Sense' of instructions. Freshness is guaranteed by turn-level orchestration.

      Specified by:
      getSystemInstructions in interface ContextProvider
      Returns:
      A list of system instruction strings.
      Throws:
      Exception - if an error occurs during instruction generation.

    • reloadIfNeeded

      public void reloadIfNeeded() throws Exception
      Synchronously reloads the resource content if it is dirty or stale.

      Loop Protection: This method clears the dirty flag and updates the load timestamp before firing events, authoritatively breaking recursive synchronization cycles.

      Throws:
      Exception - if the reload or MIME detection fails.

    • autoBindView

      private void autoBindView()
      Detects the resource capability via MIME type and binds the correct interpreter.

    • dispose

      public void dispose()
      Performs a clean shutdown of the resource, disposing of its handle.

    • getMimeType

      public String getMimeType()
      Returns the detected MIME type of the underlying source.
      Returns:
      The MIME type string.

    • getHeader

      public String getHeader()
      Generates a machine-readable header string for this context provider, used to identify the source of injected context in the final prompt.

      Implementation details: Delegates to handle and view polymorphic headers.

      Specified by:
      getHeader in interface ContextProvider
      Returns:
      A formatted header string.

    • getAgi

      public Agi getAgi()
      Gets the parent AGI session.
      Specified by:
      getAgi in interface ContextProvider
      Returns:
      The active Agi session, or null.

    • setAgi

      public void setAgi(Agi agi)
      Sets the parent AGI session.
      Parameters:
      agi - The active Agi session.

    • getSelectedModel

      public AbstractModel getSelectedModel()
      Convenience method to retrieve the currently selected model from the parent session.
      Returns:
      The active AbstractModel instance, or null if no model is selected.

    • getInstructionsTokenCount

      public int getInstructionsTokenCount()
      Calculates the token count for the system instructions provided by this instance using the active model.

      Resolves the active model from the parent AGI session and calculates token count for system instructions. Returns 0 if this resource is not in SYSTEM_INSTRUCTIONS position.

      Specified by:
      getInstructionsTokenCount in interface ContextProvider
      Returns:
      The estimated token count.

    • getRagTokenCount

      public int getRagTokenCount()
      Calculates the token count for the RAG content provided by this instance using the active model.

      Resolves the active model from the parent AGI session and sums the token counts of this resource's header and active viewport. Returns 0 if no model is selected.

      Specified by:
      getRagTokenCount in interface ContextProvider
      Returns:
      The estimated token count.

    • resetTokenCount

      public void resetTokenCount()
      Resets the cached token counts on the active view, forcing a lazy recalculation.