com.l1fe.forge:forge-embed

import com.l1fe.forge.embed.*

public data class TextChunk(
val text: String,
val index: Int,
val startOffset: Int,
)

/**
* Interface for text splitting strategies.
*
* ANVIL Spec Section 9.5
*/
public interface TextSplitter

public interface TextSplitter

public fun split(text: String): List<TextChunk>
}

/**
* A recursive character text splitter.
*
* Splits text by trying separators in order: double newline, single newline,
* sentence-ending punctuation, space, and finally individual characters.
* Each chunk has a configurable overlap with the previous chunk.
*
* @property chunkSize The target maximum chunk size in characters.
* @property chunkOverlap The number of characters to overlap between chunks.
* @property separators The list of separators to try, in order.
*/
public class RecursiveCharacterSplitter(
public val chunkSize: Int;

public class RecursiveCharacterSplitter(
public val chunkSize: Int;

public val chunkSize: Int;

public val chunkOverlap: Int;

public val separators: List<String>;

public val DEFAULT_SEPARATORS: List<String>;

public class TokenSplitter(
public val maxTokens: Int;

public val maxTokens: Int;

public val tokenOverlap: Int;

public val charsPerToken: Int;

public data class Document(
val id: String,
val content: String,
val metadata: Map<String, String>;

public interface DocumentLoader

public suspend fun load(): List<Document>
}

/**
* A document loader that loads from raw text content.
*
* @property id The document ID.
* @property text The raw text content.
* @property metadata Optional metadata.
* @property source Optional source identifier.
*/
public class TextLoader(
private val id: String,
private val text: String,
private val metadata: Map<String, String>;

public class TextLoader(
private val id: String,
private val text: String,
private val metadata: Map<String, String>;

public class JsonLoader(
private val jsonString: String,
private val contentField: String;

public data class EmbeddingResult(
val embedding: List<Float>,
val dimensions: Int,
val model: String?;

public data class BatchEmbeddingResult(
val embeddings: List<EmbeddingResult>,
val model: String?;

public data class EmbedOptions(
val model: String?;

public interface EmbeddingProvider

public suspend fun embed(text: String, options: EmbedOptions;

public suspend fun embedMany(
texts: List<String>,
options: EmbedOptions;

public sealed class ForgeEmbedError(
message: String,
cause: Throwable?;

public class ProviderError(
public val provider: String,
public val reason: String,
cause: Throwable?;

public val provider: String,
public val reason: String,
cause: Throwable?;

public val reason: String,
cause: Throwable?;

public class DimensionMismatch(
public val expected: Int,
public val actual: Int,
public val operation: String,
) : ForgeEmbedError(
"vector dimension mismatch in $operation: expected $expected, got $actual"
)

/**
* A vector store entry was not found.
*
* @property id The entry ID that was not found.
*/
public class EntryNotFound(
public val id: String,
) : ForgeEmbedError("vector store entry '$id' not found")

/**
* The reranker returned an error.
*
* @property reason The failure reason.
*/
public class RerankError(
public val reason: String,
cause: Throwable?;

public val expected: Int,
public val actual: Int,
public val operation: String,
) : ForgeEmbedError(
"vector dimension mismatch in $operation: expected $expected, got $actual"
)

/**
* A vector store entry was not found.
*
* @property id The entry ID that was not found.
*/
public class EntryNotFound(
public val id: String,
) : ForgeEmbedError("vector store entry '$id' not found")

/**
* The reranker returned an error.
*
* @property reason The failure reason.
*/
public class RerankError(
public val reason: String,
cause: Throwable?;

public val actual: Int,
public val operation: String,
) : ForgeEmbedError(
"vector dimension mismatch in $operation: expected $expected, got $actual"
)

/**
* A vector store entry was not found.
*
* @property id The entry ID that was not found.
*/
public class EntryNotFound(
public val id: String,
) : ForgeEmbedError("vector store entry '$id' not found")

/**
* The reranker returned an error.
*
* @property reason The failure reason.
*/
public class RerankError(
public val reason: String,
cause: Throwable?;

public val operation: String,
) : ForgeEmbedError(
"vector dimension mismatch in $operation: expected $expected, got $actual"
)

/**
* A vector store entry was not found.
*
* @property id The entry ID that was not found.
*/
public class EntryNotFound(
public val id: String,
) : ForgeEmbedError("vector store entry '$id' not found")

/**
* The reranker returned an error.
*
* @property reason The failure reason.
*/
public class RerankError(
public val reason: String,
cause: Throwable?;

public class EntryNotFound(
public val id: String,
) : ForgeEmbedError("vector store entry '$id' not found")

/**
* The reranker returned an error.
*
* @property reason The failure reason.
*/
public class RerankError(
public val reason: String,
cause: Throwable?;

public val id: String,
) : ForgeEmbedError("vector store entry '$id' not found")

/**
* The reranker returned an error.
*
* @property reason The failure reason.
*/
public class RerankError(
public val reason: String,
cause: Throwable?;

public class RerankError(
public val reason: String,
cause: Throwable?;

public val reason: String,
cause: Throwable?;

public class ChunkingError(
public val reason: String,
) : ForgeEmbedError("chunking failed: $reason")

/**
* Document loading failed.
*
* @property source The source that failed to load.
* @property reason The failure reason.
*/
public class DocumentLoadError(
public val source: String,
public val reason: String,
cause: Throwable?;

public val reason: String,
) : ForgeEmbedError("chunking failed: $reason")

/**
* Document loading failed.
*
* @property source The source that failed to load.
* @property reason The failure reason.
*/
public class DocumentLoadError(
public val source: String,
public val reason: String,
cause: Throwable?;

public class DocumentLoadError(
public val source: String,
public val reason: String,
cause: Throwable?;

public val source: String,
public val reason: String,
cause: Throwable?;

public val reason: String,
cause: Throwable?;

public data class RerankResult(
val index: Int,
val score: Double,
val document: String,
)

/**
* The output of a reranking operation.
*
* @property results The reranked documents, ordered by relevance (highest first).
* @property model The reranker model used (if available).
*/
@Serializable
public data class RerankOutput(
val results: List<RerankResult>,
val model: String?;

public data class RerankOutput(
val results: List<RerankResult>,
val model: String?;

public data class RerankOptions(
val model: String?;

public interface Reranker

public suspend fun rerank(
query: String,
documents: List<String>,
options: RerankOptions;

public fun cosineSimilarity(a: List<Float>, b: List<Float>): Double

public fun euclideanDistance(a: List<Float>, b: List<Float>): Double

public fun dotProduct(a: List<Float>, b: List<Float>): Double

public data class VectorEntry(
val id: String,
val embedding: List<Float>,
val content: String,
val metadata: Map<String, String>;

public data class SearchResult(
val entry: VectorEntry,
val score: Double,
)

/**
* Options for vector store search.
*
* @property topK The maximum number of results to return.
* @property minScore The minimum similarity score threshold.
* @property metadataFilter Optional metadata key-value pairs to filter by.
*/
@Serializable
public data class SearchOptions(
val topK: Int;

public data class SearchOptions(
val topK: Int;

public interface VectorStore

public suspend fun upsert(entry: VectorEntry)

/**
* Insert or update multiple entries in a batch.
*
* @param entries The entries to upsert.
*/
public suspend fun upsertMany(entries: List<VectorEntry>)

/**
* Retrieve an entry by its ID.
*
* @param id The entry ID.
* @return The entry, or `null` if not found.
*/
public suspend fun get(id: String): VectorEntry?

/**
* Delete an entry by its ID.
*
* @param id The entry ID.
* @return `true` if the entry was deleted, `false` if not found.
*/
public suspend fun delete(id: String): Boolean

/**

public suspend fun upsertMany(entries: List<VectorEntry>)

/**
* Retrieve an entry by its ID.
*
* @param id The entry ID.
* @return The entry, or `null` if not found.
*/
public suspend fun get(id: String): VectorEntry?

/**
* Delete an entry by its ID.
*
* @param id The entry ID.
* @return `true` if the entry was deleted, `false` if not found.
*/
public suspend fun delete(id: String): Boolean

/**
* Search for entries similar to the given query vector.
*
* @param query The query embedding vector.
* @param options Search options (top-K, min score, filters).
* @return The list of search results, ordered by similarity (highest first).
*/
public suspend fun search(query: List<Float>, options: SearchOptions;

public suspend fun get(id: String): VectorEntry?

/**
* Delete an entry by its ID.
*
* @param id The entry ID.
* @return `true` if the entry was deleted, `false` if not found.
*/
public suspend fun delete(id: String): Boolean

/**
* Search for entries similar to the given query vector.
*
* @param query The query embedding vector.
* @param options Search options (top-K, min score, filters).
* @return The list of search results, ordered by similarity (highest first).
*/
public suspend fun search(query: List<Float>, options: SearchOptions;

public suspend fun delete(id: String): Boolean

/**
* Search for entries similar to the given query vector.
*
* @param query The query embedding vector.
* @param options Search options (top-K, min score, filters).
* @return The list of search results, ordered by similarity (highest first).
*/
public suspend fun search(query: List<Float>, options: SearchOptions;

public suspend fun search(query: List<Float>, options: SearchOptions;

public suspend fun size(): Int
}

/**
* An in-memory vector store using cosine similarity.
*
* Thread-safe. Suitable for development, testing, and small datasets.
* Production workloads should use a dedicated vector database.
*
* ANVIL Spec Section 9.4
*/
public class InMemoryVectorStore : VectorStore

public class InMemoryVectorStore : VectorStore

public fun clear()