Project

Namespaces

Public Vars

com.rpl.agent-o-rama.store

Store API for accessing persistent storage within agent nodes.

This namespace provides a unified interface for working with different types of persistent storage in agent-o-rama. Stores are obtained via get-store within agent node functions and provide distributed, persistent, replicated storage that agents can use to maintain state across executions.

Store types:

  • Key-value stores: Simple typed storage with automatic partitioning
  • Document stores: Schema-flexible storage for nested data
  • PState stores: Direct access to Rama’s built-in storage capabilities

All store operations are automatically traced and included in agent execution traces for debugging and monitoring purposes.

Example:

(fn [agent-node input]
  (let [store (aor/get-store agent-node "$$user-cache")]
    (store/put! store :user-id "12345")
    (store/put! store :last-seen (System/currentTimeMillis))
    (let [user-id (store/get store :user-id)
          last-seen (store/get store :last-seen)]
      (aor/result! agent-node {:user-id user-id :last-seen last-seen}))))

contains-document-field?

(contains-document-field? store k doc-key)

Checks if a specific field exists in a document.

Args:

  • store - Document store instance obtained from get-store
  • k - Document key (primary key)
  • doc-key - Field name to check for existence

Returns:

  • Boolean - True if the field exists in the document

Example:

(let [doc-store (aor/get-store agent-node "$$user-docs")]
  (when (store/contains-document-field? doc-store :user-123 :email)
    (store/get-document-field doc-store :user-123 :email)))

contains?

(contains? store k)

Checks if a key exists in a key-value store.

Args:

  • store - Store instance obtained from get-store
  • k - Key to check for existence

Returns:

  • Boolean - True if the key exists in the store

Example:

(let [store (aor/get-store agent-node "$$cache")]
  (when (store/contains? store :user-id)
    (store/get store :user-id)))

get

(get store k)(get store k default-value)

Gets a value from a key-value store.

Retrieves the value associated with the given key from the store. If the key doesn’t exist, returns the default value (or nil if not provided).

Args:

  • store - Store instance obtained from get-store
  • k - Key to look up
  • default-value - Value to return if key doesn’t exist (optional, defaults to nil)

Returns:

  • The value associated with the key, or default-value if key doesn’t exist

Example:

(let [store (aor/get-store agent-node "$$cache")]
  (store/get store :user-id "unknown")
  (store/get store :count 0))

get-document-field

(get-document-field store k doc-key)(get-document-field store k doc-key default-value)

Gets a specific field from a document in a document store.

Document stores allow accessing individual fields of nested data structures without loading the entire document.

Args:

  • store - Document store instance obtained from get-store
  • k - Document key (primary key)
  • doc-key - Field name within the document
  • default-value - Value to return if field doesn’t exist (optional, defaults to nil)

Returns:

  • The value of the specified field, or default-value if field doesn’t exist

Example:

(let [doc-store (aor/get-store agent-node "$$user-docs")]
  (store/get-document-field doc-store :user-123 :email "unknown@example.com")
  (store/get-document-field doc-store :user-123 :preferences {}))

pstate-select

macro

(pstate-select apath store)(pstate-select apath store partitioning-key)

Selects data from a PState store using Rama path expressions.

PState stores provide direct access to Rama’s built-in storage capabilities with powerful querying using path expressions. This function returns a collection of all matching values.

Args:

  • apath - Rama path expression
  • store - PState store instance obtained from get-store
  • partitioning-key - Optional partitioning key for the query. Mandatory if the path does not begin with key navigation.

Returns:

  • Collection of all values matching the path expression

Example:

(let [pstate (aor/get-store agent-node "$$analytics")]
  (store/pstate-select [:user-id ALL] pstate)
  (store/pstate-select [ALL (selected? :active)] pstate :some-partition-key))

pstate-select-one

macro

(pstate-select-one apath store)(pstate-select-one apath store partitioning-key)

Selects a single value from a PState store using Rama path expressions.

Similar to pstate-select but returns only the first matching value. Useful when you know the path will match exactly one item.

Args:

  • apath - Rama path expression
  • store - PState store instance obtained from get-store
  • partitioning-key - Optional partitioning key for the query. Mandatory if the path does not begin with key navigation.

Returns:

  • The first value matching the path expression, or nil if no match

Example:

(let [pstate (aor/get-store agent-node "$$config")]
  (store/pstate-select-one [:settings :max-retries] pstate))

pstate-transform!

macro

(pstate-transform! apath store partitioning-key)

Transforms data in a PState store using Rama path expressions.

Applies a transformation function to data matching the path expression.

Args:

  • apath - Rama path expression with transformation
  • store - PState store instance obtained from get-store
  • partitioning-key - Partitioning key for the transformation

Example:

(let [pstate (aor/get-store agent-node "$$analytics")]
  (store/pstate-transform! [:alice :page-views (termval 42)] pstate :alice))

put!

(put! store k v)

Stores a key-value pair in a key-value store.

Args:

  • store - Store instance obtained from get-store
  • k - Key to store
  • v - Value to store

Example:

(let [store (aor/get-store agent-node "$$cache")]
  (store/put! store :user-id "12345")
  (store/put! store :last-seen (System/currentTimeMillis)))

put-document-field!

(put-document-field! store k doc-key value)

Sets a specific field in a document.

Args:

  • store - Document store instance obtained from get-store
  • k - Document key (primary key)
  • doc-key - Field name to set
  • value - Value to store in the field

Example:

(let [doc-store (aor/get-store agent-node "$$user-docs")]
  (store/put-document-field! doc-store :user-123 :email "user@example.com")
  (store/put-document-field! doc-store :user-123 :last-login (System/currentTimeMillis)))

update!

(update! store k afn)

Updates a value in a key-value store using a function.

Applies the function to the current value (or nil if key doesn’t exist) and stores the result back to the same key.

Args:

  • store - Store instance obtained from get-store
  • k - Key to update
  • afn - Function that takes the current value and returns the new value

Example:

(let [store (aor/get-store agent-node "$$counters")]
  (store/update! store :page-views #(inc (or % 0)))
  (store/update! store :total #(+ (or % 0) amount)))

update-document-field!

(update-document-field! store k doc-key afn)

Updates a specific field in a document using a function.

Applies the function to the current field value (or nil if field doesn’t exist) and stores the result back to the same field.

Args:

  • store - Document store instance obtained from get-store
  • k - Document key (primary key)
  • doc-key - Field name to update
  • afn - Function that takes the current field value and returns the new value

Example:

(let [doc-store (aor/get-store agent-node "$$user-docs")]
  (store/update-document-field! doc-store :user-123 :login-count #(inc (or % 0)))
  (store/update-document-field! doc-store :user-123 :preferences #(assoc % :theme "dark")))