adk_memory_service behaviour (erlang_adk v0.7.0)

View Source

Versioned contract for cross-session long-term memory.

Version 2 makes the application/user authority explicit. Implementations must never infer a principal from caller supplied metadata. The old add/search/delete/session callbacks remain as compatibility entry points; new runtime code should feature-detect contract_version => 2 and use the scoped operations.

Summary

Types

call_options/0
entry/0
entry_input/0
filter/0
handle/0
hit/0
ingest_result/0
provenance/0
query/0
scope/0

Callbacks

add/3
add_entry/4
add_entry/5
add_events/5
add_events/6
add_session_to_memory/3
add_session_to_memory/5
capabilities/1
delete/2
delete_entry/3
delete_entry/4
delete_session/3
delete_session/4
delete_user/2
delete_user/3
search/4
search/5

Types

call_options/0

-type call_options() :: #{timeout_ms => pos_integer()}.

entry/0

-type entry() ::
          #{schema_version := pos_integer(),
            id := binary(),
            scope := scope(),
            content := binary(),
            metadata := map(),
            provenance := map(),
            digest := binary(),
            timestamp := integer()}.

entry_input/0

-type entry_input() :: #{content := binary(), metadata => map(), provenance => provenance()}.

filter/0

-type filter() :: map().

handle/0

-type handle() :: term().

hit/0

-type hit() ::
          entry() |
          #{id := binary(),
            scope := scope(),
            content := binary(),
            metadata := map(),
            provenance := map(),
            score := float(),
            score_type := lexical_overlap,
            timestamp := integer()}.

ingest_result/0

-type ingest_result() ::
          #{added := non_neg_integer(), duplicates := non_neg_integer(), skipped := non_neg_integer()}.

provenance/0

-type provenance() ::
          #{session_id => binary(), event_ids => [binary()], author => binary(), timestamp => integer()}.

query/0

-type query() :: binary().

scope/0

-type scope() :: {user, AppName :: binary(), UserId :: binary()}.

Callbacks

add/3

(optional) 
-callback add(Handle :: handle(), Content :: binary(), Metadata :: map()) ->
                 {ok, binary()} | {error, term()}.

add_entry/4

(optional) 
-callback add_entry(Handle :: handle(), Scope :: scope(), Input :: entry_input(), Opts :: map()) ->
                       {ok, entry()} | {error, term()}.

add_entry/5

(optional) 
-callback add_entry(Handle :: handle(),
                    Scope :: scope(),
                    Input :: entry_input(),
                    Opts :: map(),
                    CallOptions :: call_options()) ->
                       {ok, entry()} | {error, term()}.

add_events/5

(optional) 
-callback add_events(Handle :: handle(),
                     Scope :: scope(),
                     SessionId :: binary(),
                     Events :: [adk_event:event()],
                     Opts :: map()) ->
                        {ok, ingest_result()} | {error, term()}.

add_events/6

(optional) 
-callback add_events(Handle :: handle(),
                     Scope :: scope(),
                     SessionId :: binary(),
                     Events :: [adk_event:event()],
                     Opts :: map(),
                     CallOptions :: call_options()) ->
                        {ok, ingest_result()} | {error, term()}.

add_session_to_memory/3

(optional) 
-callback add_session_to_memory(Handle :: handle(), SessionId :: binary(), Events :: [adk_event:event()]) ->
                                   ok | {error, term()}.

add_session_to_memory/5

(optional) 
-callback add_session_to_memory(Handle :: handle(),
                                Scope :: scope(),
                                SessionId :: binary(),
                                Events :: [adk_event:event()],
                                Opts :: map()) ->
                                   {ok, ingest_result()} | {error, term()}.

capabilities/1

(optional) 
-callback capabilities(Handle :: handle()) -> map().

delete/2

(optional) 
-callback delete(Handle :: handle(), Id :: binary()) -> ok | {error, term()}.

delete_entry/3

(optional) 
-callback delete_entry(Handle :: handle(), Scope :: scope(), Id :: binary()) ->
                          ok | {error, not_found | term()}.

delete_entry/4

(optional) 
-callback delete_entry(Handle :: handle(), Scope :: scope(), Id :: binary(), CallOptions :: call_options()) ->
                          ok | {error, not_found | term()}.

delete_session/3

(optional) 
-callback delete_session(Handle :: handle(), Scope :: scope(), SessionId :: binary()) ->
                            ok | {error, not_found | term()}.

delete_session/4

(optional) 
-callback delete_session(Handle :: handle(),
                         Scope :: scope(),
                         SessionId :: binary(),
                         CallOptions :: call_options()) ->
                            ok | {error, not_found | term()}.

delete_user/2

(optional) 
-callback delete_user(Handle :: handle(), Scope :: scope()) -> ok | {error, not_found | term()}.

delete_user/3

(optional) 
-callback delete_user(Handle :: handle(), Scope :: scope(), CallOptions :: call_options()) ->
                         ok | {error, not_found | term()}.

search/4

-callback search(Handle :: handle(),
                 ScopeOrQuery :: scope() | query(),
                 QueryOrFilter :: query() | filter(),
                 OptsOrLimit :: map() | pos_integer()) ->
                    {ok, [hit()]} | {error, term()}.

search/5

(optional) 
-callback search(Handle :: handle(),
                 Scope :: scope(),
                 Query :: query(),
                 Opts :: map(),
                 CallOptions :: call_options()) ->
                    {ok, [hit()]} | {error, term()}.