Content Storage API Reference

interface ContentElementRepositoryInfo {
    /**
     * Number of chunks in repository
     */
    val chunkCount: Int

    /**
     * Number of root documents in repository
     */
    val documentCount: Int

    /**
     * Total number of content elements (all types)
     */
    val contentElementCount: Int

    /**
     * Whether repository stores embeddings
     */
    val hasEmbeddings: Boolean

    /**
     * Whether repository persists to disk/database
     */
    val isPersistent: Boolean
}

interface ContentElementRepository : Named {
    /**
     * Repository name
     */
    override val name: String

    /**
     * Initialize repository storage
     */
    fun provision()

    /**
     * Get repository information
     * @return Information about repository state
     */
    fun info(): ContentElementRepositoryInfo

    /**
     * Save a content element
     * @param element Element to save
     * @return Saved element (may include generated fields)
     */
    fun save(element: ContentElement): ContentElement

    /**
     * Find element by ID
     * @param id Element identifier
     * @return Element or null if not found
     */
    fun findById(id: String): ContentElement?

    /**
     * Find all elements of a specific type
     * @param clazz Element class
     * @return Iterable of matching elements
     */
    fun <C : ContentElement> findAll(clazz: Class<C>): Iterable<C>

    /**
     * Find multiple chunks by IDs
     * @param chunkIds List of chunk identifiers
     * @return Iterable of found chunks
     */
    fun findAllChunksById(chunkIds: List<String>): Iterable<Chunk>

    /**
     * Find chunks associated with an entity
     * @param entityId Entity identifier
     * @return List of related chunks
     */
    fun findChunksForEntity(entityId: String): List<Chunk>

    /**
     * Get path from root to element
     * @param element Hierarchical content element
     * @return List of IDs from root to element, or null
     */
    fun pathFromRoot(element: HierarchicalContentElement): List<String>?
}

interface ChunkingContentElementRepository : ContentElementRepository {
    /**
     * Enhancers applied to retrievables before storage
     */
    val enhancers: List<RetrievableEnhancer>

    /**
     * Write document and generate chunks
     * @param root Navigable document to process
     * @return List of chunk IDs created
     */
    fun writeAndChunkDocument(root: NavigableDocument): List<String>

    /**
     * Delete document root and all descendants
     * @param uri Document URI
     * @return Deletion result or null if not found
     */
    fun deleteRootAndDescendants(uri: String): DocumentDeletionResult?

    /**
     * Find document root by URI
     * @param uri Document URI
     * @return Content root or null if not found
     */
    fun findContentRootByUri(uri: String): ContentRoot?

    /**
     * Check if document with URI exists
     * @param uri Document URI
     * @return true if document exists
     */
    fun existsRootWithUri(uri: String): Boolean

    /**
     * Apply enhancers to a retrievable
     * @param retrievable Retrievable to enhance
     * @return Enhanced retrievable
     */
    fun <T : Retrievable> enhance(retrievable: T): T

    /**
     * Callback when new retrievables are created
     * @param retrievables List of new retrievables
     */
    fun onNewRetrievables(retrievables: List<Retrievable>)
}

data class DocumentDeletionResult(
    /**
     * URI of deleted document root
     */
    val rootUri: String,

    /**
     * Number of elements deleted
     */
    val deletedCount: Int
)

abstract class AbstractChunkingContentElementRepository :
    ChunkingContentElementRepository {

    /**
     * Callback for newly created retrievables
     * Override to add custom behavior
     */
    override fun onNewRetrievables(retrievables: List<Retrievable>)

    /**
     * Persist chunks with their embeddings
     * Must be implemented by subclasses
     * @param chunks Chunks to persist
     * @param embeddings Map of chunk ID to embedding vector
     */
    protected abstract fun persistChunksWithEmbeddings(
        chunks: List<Chunk>,
        embeddings: Map<String, FloatArray>
    )

    /**
     * Create internal relationships between document elements
     * Must be implemented by subclasses
     * @param root Document root
     */
    protected abstract fun createInternalRelationships(root: NavigableDocument)

    /**
     * Commit changes to storage
     * Must be implemented by subclasses
     */
    protected abstract fun commit()

    /**
     * Final implementation of document writing with chunking
     * Handles embedding generation and calls protected methods
     * @param root Document to write
     * @return List of chunk IDs
     */
    final override fun writeAndChunkDocument(root: NavigableDocument): List<String>
}