Package org.egothor.methodatlas

Class AiResultCache

java.lang.Object
org.egothor.methodatlas.AiResultCache
public final class AiResultCache extends Object
In-memory cache of AI results loaded from a previous MethodAtlas run, keyed by the per-class content_hash fingerprint.

Each entry (AiCacheEntry) holds the complete AI answer for one class — method classifications and any credential-triage verdicts — plus the prompt-catalogue signature that produced it. This lets one cached answer serve a later classification-only run, a later credential run, or a combined run without re-querying the model, provided the prompt signature still matches. An answer obtained under a different prompt catalogue is never reused.

Two source formats are accepted by load(Path): the unified JSON-Lines cache (the format MethodAtlas now writes) and the legacy per-method scan CSV (produced by older -content-hash runs). Legacy entries carry no prompt signature and no credential verdicts: their classifications may still be reused by content hash, but they can never satisfy a credential query.

Instances are obtained via load(Path) or the no-op empty(). Not thread-safe for the hit/miss counters; the scan loop is single-threaded.

See Also:

  • Method Summary

    Modifier and Type
    Method
    Description
    Optional<org.egothor.methodatlas.ai.AiClassSuggestion>
    classification(String contentHash, String promptSignature)
    Returns the cached classification for a class when the content hash matches and the cached answer is compatible with the current prompt catalogue.
    static AiResultCache
    empty()
    Returns an empty cache that always produces misses.
    int
    hits()
    Returns the number of successful cache lookups so far.
    boolean
    isActive()
    Returns true when this cache contains at least one entry.
    static AiResultCache
    load(Path path)
    Loads a cache from a unified JSON-Lines cache file or a legacy scan CSV, auto-detected from the file's first non-blank character.
    Optional<org.egothor.methodatlas.ai.AiClassSuggestion>
    lookup(String contentHash)
    Returns the cached AI answer for a class by content hash, ignoring the prompt signature.
    int
    misses()
    Returns the number of unsuccessful cache lookups so far.
    Optional<List<org.egothor.methodatlas.ai.CredentialTriageVerdict>>
    verdicts(String contentHash, String promptSignature)
    Returns cached credential-triage verdicts for a class when the content hash and the prompt signature both match and verdicts were actually recorded.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Method Details

    • empty

      public static AiResultCache empty()
      Returns an empty cache that always produces misses.

    • load

      public static AiResultCache load(Path path) throws IOException
      Loads a cache from a unified JSON-Lines cache file or a legacy scan CSV, auto-detected from the file's first non-blank character.
      Parameters:
      path - path to a unified cache file or a legacy MethodAtlas CSV
      Returns:
      loaded cache; never null
      Throws:
      IOException - if the file cannot be read

    • lookup

      public Optional<org.egothor.methodatlas.ai.AiClassSuggestion> lookup(String contentHash)
      Returns the cached AI answer for a class by content hash, ignoring the prompt signature.
      Parameters:
      contentHash - SHA-256 fingerprint of the class source, or null
      Returns:
      cached suggestion, or empty on a miss or null hash

    • classification

      public Optional<org.egothor.methodatlas.ai.AiClassSuggestion> classification(String contentHash, String promptSignature)
      Returns the cached classification for a class when the content hash matches and the cached answer is compatible with the current prompt catalogue.

      A unified entry must carry a matching promptSignature; a legacy entry (no signature) is served by content hash alone, preserving prior behaviour. Updates the hit/miss counters.

      Parameters:
      contentHash - SHA-256 fingerprint of the class source, or null
      promptSignature - signature of the current run's prompt catalogue
      Returns:
      cached classification, or empty on a miss

    • verdicts

      public Optional<List<org.egothor.methodatlas.ai.CredentialTriageVerdict>> verdicts(String contentHash, String promptSignature)
      Returns cached credential-triage verdicts for a class when the content hash and the prompt signature both match and verdicts were actually recorded.

      Unlike classification(String, String) this requires a non-null matching signature (a legacy entry can never satisfy a credential query) and does not touch the hit/miss counters.

      Parameters:
      contentHash - SHA-256 fingerprint of the class source, or null
      promptSignature - signature of the current run's prompt catalogue
      Returns:
      cached verdicts, or empty when none are cached for this signature

    • isActive

      public boolean isActive()
      Returns true when this cache contains at least one entry.

      When false, content hashes do not need to be computed for lookups because all results would be misses regardless.

      Returns:
      true when the cache is non-empty

    • hits

      public int hits()
      Returns the number of successful cache lookups so far.

    • misses

      public int misses()
      Returns the number of unsuccessful cache lookups so far.