Common Library

Entity Repositories

common holds the repositories that are not engine-specific: the evaluation and access-control queries, and the Elasticsearch vector search implementation that memory is built on. The engine’s own repositories are listed in Data Access.

Repository interfaces are discovered by the consuming application’s @Enable*Repositories declarations over ai.promethist.**.repository.

MongoDB

Repository Queries

Repository	Queries
`EvaluationDefinitionRepository`	Evaluation definitions by IDs, by project, by test mode, and by ref and state.
`EvaluationGroupDefinitionRepository`	Insight groups of an evaluation.
`EvaluationInsightDefinitionRepository`	Insight definitions with a fallback match, so an insight can be declared independently of a specific evaluation or project and still apply, ordered by its `order`.
`CodebookCodeRepository`	The project’s codebook entries, by project and by name.
`CodebookOccurrenceRepository`	Coded occurrences by project and user, the lookup that skips an already-classified subject, and the atomic claim that hands one growth pass a batch of unclassified texts without a second pass taking the same ones.
`DevelopmentProfileRepository`	One profile per project and user.
`EvaluationInsightResultRepository`	The reporting queries. Aggregation pipelines join results with their definitions and filter by combinations of user, project, agent ref, session, execution mode and time range — this is what backs the insight and aggregation endpoints.
`EvaluationResultRepository`	Evaluation results by session, user and project, optionally within a time range.
`FeedbackDefinitionRepository`	Feedback definitions by project, and by ID within a project.
`FeedbackQuestionDefinitionRepository`	Question definitions by IDs and by project.
`FeedbackRepository`	Feedback by session, definition and project; a user’s latest request of a definition revision, and the latest one with an answer to a given set of questions; and the existence checks for an answered and for a skipped feedback over all the revisions of a definition, given as their ids, which repeat the conditions of the derived `state`.
`AclRepository`	Access control records by tenant, project and user.
`BillingDetailsRepository`	Billing details by tenant and by payment provider customer ID.
`PricingDetailsRepository`	Pricing details by tenant.
`ChatMemoryUnitRepository`	Chat history documents.
`McpConnectorRepository`	MCP connectors, by ref.
`AuditEventRepository`	Audit events.

EvaluationDefinitionRepository

Evaluation definitions by IDs, by project, by test mode, and by ref and state.

EvaluationGroupDefinitionRepository

Insight groups of an evaluation.

EvaluationInsightDefinitionRepository

Insight definitions with a fallback match, so an insight can be declared independently of a specific evaluation or project and still apply, ordered by its order.

CodebookCodeRepository

The project’s codebook entries, by project and by name.

CodebookOccurrenceRepository

Coded occurrences by project and user, the lookup that skips an already-classified subject, and the atomic claim that hands one growth pass a batch of unclassified texts without a second pass taking the same ones.

DevelopmentProfileRepository

One profile per project and user.

EvaluationInsightResultRepository

The reporting queries. Aggregation pipelines join results with their definitions and filter by combinations of user, project, agent ref, session, execution mode and time range — this is what backs the insight and aggregation endpoints.

EvaluationResultRepository

Evaluation results by session, user and project, optionally within a time range.

FeedbackDefinitionRepository

Feedback definitions by project, and by ID within a project.

FeedbackQuestionDefinitionRepository

Question definitions by IDs and by project.

FeedbackRepository

Feedback by session, definition and project; a user’s latest request of a definition revision, and the latest one with an answer to a given set of questions; and the existence checks for an answered and for a skipped feedback over all the revisions of a definition, given as their ids, which repeat the conditions of the derived state.

AclRepository

Access control records by tenant, project and user.

BillingDetailsRepository

Billing details by tenant and by payment provider customer ID.

PricingDetailsRepository

Pricing details by tenant.

ChatMemoryUnitRepository

Chat history documents.

McpConnectorRepository

MCP connectors, by ref.

AuditEventRepository

Audit events.

Two styles appear: ReactiveMongoRepository where Mongo-specific @Query or @Aggregation annotations are needed, and the plainer ReactiveCrudRepository where derived queries suffice.

Elasticsearch

Vector search is not expressible as a derived query, so it is implemented by hand.

interface ElasticsearchRepository<T : TextuallyRepresented> :
    ReactiveElasticsearchRepository<T, ID>,
    ElasticsearchRepositoryCustom<T>

ElasticsearchRepositoryCustom adds the operations memory relies on:

Operation Purpose

Operation	Purpose
`searchByVectorWithScore`	Cosine similarity search returning the score with each hit.
`searchByVectorWithMetadataFilter`	The same, restricted by metadata (namespace, user, agent, time).
`findLatestByDynamicField`	The most recent unit for a field whose name is not known at compile time.
`getAllInTimeInterval`	Units created within an interval.
`findByUserIdAndNamespace`, `deleteByUserIdAndNamespace`	Reading and erasing one scope of one user’s memory — what memory deletion uses.
`saveDocument`, `refreshIndex`	Indexing a document, and forcing a refresh so a just-written unit is immediately searchable.

searchByVectorWithScore

Cosine similarity search returning the score with each hit.

searchByVectorWithMetadataFilter

The same, restricted by metadata (namespace, user, agent, time).

findLatestByDynamicField

The most recent unit for a field whose name is not known at compile time.

getAllInTimeInterval

Units created within an interval.

findByUserIdAndNamespace, deleteByUserIdAndNamespace

Reading and erasing one scope of one user’s memory — what memory deletion uses.

saveDocument, refreshIndex

Indexing a document, and forcing a refresh so a just-written unit is immediately searchable.

ElasticsearchRepositoryImpl implements them on ReactiveElasticsearchOperations with native queries, similarity implemented as a script score, and a single retry on timeout that is then surfaced as a knowledge search timeout — a slow search degrades the answer rather than failing the conversation.