coderag-ai 0.3.0__py3-none-any.whl

coderag/db/migrations/versions/c8a40feeda41_initial_schema.py

@@ -0,0 +1,227 @@
+"""initial schema
+
+Revision ID: c8a40feeda41
+Revises: 
+Create Date: 2026-09-01 21:50:43.238620
+"""
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+import pgvector.sqlalchemy
+import sqlalchemy as sa
+from alembic import op
+from sqlalchemy.dialects import postgresql
+
+revision: str = 'c8a40feeda41'
+down_revision: str | None = None
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.create_table('evaluation_runs',
+    sa.Column('id', sa.Integer(), nullable=False),
+    sa.Column('name', sa.String(length=255), nullable=False),
+    sa.Column('dataset', sa.String(length=1024), nullable=False),
+    sa.Column('recall_at_1', sa.Float(), nullable=False),
+    sa.Column('recall_at_3', sa.Float(), nullable=False),
+    sa.Column('recall_at_5', sa.Float(), nullable=False),
+    sa.Column('recall_at_10', sa.Float(), nullable=False),
+    sa.Column('mrr', sa.Float(), nullable=False),
+    sa.Column('avg_retrieved_tokens', sa.Float(), nullable=False),
+    sa.Column('avg_context_tokens', sa.Float(), nullable=False),
+    sa.Column('avg_retrieval_latency_ms', sa.Float(), nullable=False),
+    sa.Column('config', postgresql.JSONB(astext_type=sa.Text()), nullable=True),
+    sa.Column('created_at', sa.DateTime(), server_default=sa.text('now()'), nullable=False),
+    sa.PrimaryKeyConstraint('id')
+    )
+    op.create_table('repositories',
+    sa.Column('id', sa.Integer(), nullable=False),
+    sa.Column('name', sa.String(length=255), nullable=False),
+    sa.Column('url', sa.String(length=1024), nullable=True),
+    sa.Column('local_path', sa.String(length=1024), nullable=False),
+    sa.Column('default_branch', sa.String(length=255), nullable=False),
+    sa.Column('indexed_commit_sha', sa.String(length=64), nullable=True),
+    sa.Column('created_at', sa.DateTime(), server_default=sa.text('now()'), nullable=False),
+    sa.Column('updated_at', sa.DateTime(), server_default=sa.text('now()'), nullable=False),
+    sa.PrimaryKeyConstraint('id')
+    )
+    op.create_index(op.f('ix_repositories_name'), 'repositories', ['name'], unique=True)
+    op.create_table('indexing_runs',
+    sa.Column('id', sa.Integer(), nullable=False),
+    sa.Column('repository_id', sa.Integer(), nullable=False),
+    sa.Column('mode', sa.String(length=16), nullable=False),
+    sa.Column('status', sa.String(length=16), nullable=False),
+    sa.Column('from_commit', sa.String(length=64), nullable=True),
+    sa.Column('to_commit', sa.String(length=64), nullable=True),
+    sa.Column('files_indexed', sa.Integer(), nullable=False),
+    sa.Column('files_deleted', sa.Integer(), nullable=False),
+    sa.Column('symbols_indexed', sa.Integer(), nullable=False),
+    sa.Column('symbols_deleted', sa.Integer(), nullable=False),
+    sa.Column('embeddings_created', sa.Integer(), nullable=False),
+    sa.Column('duration_seconds', sa.Float(), nullable=False),
+    sa.Column('error', sa.Text(), nullable=True),
+    sa.Column('started_at', sa.DateTime(), server_default=sa.text('now()'), nullable=False),
+    sa.Column('finished_at', sa.DateTime(), nullable=True),
+    sa.ForeignKeyConstraint(['repository_id'], ['repositories.id'], ondelete='CASCADE'),
+    sa.PrimaryKeyConstraint('id')
+    )
+    op.create_table('queries',
+    sa.Column('id', sa.Integer(), nullable=False),
+    sa.Column('repository_id', sa.Integer(), nullable=False),
+    sa.Column('query_text', sa.Text(), nullable=False),
+    sa.Column('mode', sa.String(length=16), nullable=False),
+    sa.Column('candidates_found', sa.Integer(), nullable=False),
+    sa.Column('candidates_selected', sa.Integer(), nullable=False),
+    sa.Column('candidate_tokens', sa.Integer(), nullable=False),
+    sa.Column('context_tokens', sa.Integer(), nullable=False),
+    sa.Column('dropped_tokens', sa.Integer(), nullable=False),
+    sa.Column('retrieval_latency_ms', sa.Float(), nullable=False),
+    sa.Column('created_at', sa.DateTime(), server_default=sa.text('now()'), nullable=False),
+    sa.ForeignKeyConstraint(['repository_id'], ['repositories.id'], ondelete='CASCADE'),
+    sa.PrimaryKeyConstraint('id')
+    )
+    op.create_table('source_files',
+    sa.Column('id', sa.Integer(), nullable=False),
+    sa.Column('repository_id', sa.Integer(), nullable=False),
+    sa.Column('path', sa.String(length=1024), nullable=False),
+    sa.Column('language', sa.String(length=32), nullable=False),
+    sa.Column('content_hash', sa.String(length=64), nullable=False),
+    sa.Column('size_bytes', sa.Integer(), nullable=False),
+    sa.Column('indexed_commit_sha', sa.String(length=64), nullable=True),
+    sa.Column('created_at', sa.DateTime(), server_default=sa.text('now()'), nullable=False),
+    sa.Column('updated_at', sa.DateTime(), server_default=sa.text('now()'), nullable=False),
+    sa.ForeignKeyConstraint(['repository_id'], ['repositories.id'], ondelete='CASCADE'),
+    sa.PrimaryKeyConstraint('id'),
+    sa.UniqueConstraint('repository_id', 'path', name='uq_source_files_repo_path')
+    )
+    op.create_index('ix_source_files_repo', 'source_files', ['repository_id'], unique=False)
+    op.create_table('llm_requests',
+    sa.Column('id', sa.Integer(), nullable=False),
+    sa.Column('query_id', sa.Integer(), nullable=True),
+    sa.Column('provider', sa.String(length=64), nullable=False),
+    sa.Column('model', sa.String(length=128), nullable=False),
+    sa.Column('input_tokens', sa.Integer(), nullable=False),
+    sa.Column('output_tokens', sa.Integer(), nullable=False),
+    sa.Column('cached_input_tokens', sa.Integer(), nullable=True),
+    sa.Column('latency_ms', sa.Float(), nullable=False),
+    sa.Column('success', sa.Boolean(), nullable=False),
+    sa.Column('error', sa.Text(), nullable=True),
+    sa.Column('created_at', sa.DateTime(), server_default=sa.text('now()'), nullable=False),
+    sa.ForeignKeyConstraint(['query_id'], ['queries.id'], ondelete='SET NULL'),
+    sa.PrimaryKeyConstraint('id')
+    )
+    op.create_table('symbols',
+    sa.Column('id', sa.Integer(), nullable=False),
+    sa.Column('repository_id', sa.Integer(), nullable=False),
+    sa.Column('source_file_id', sa.Integer(), nullable=False),
+    sa.Column('file_path', sa.String(length=1024), nullable=False),
+    sa.Column('language', sa.String(length=32), nullable=False),
+    sa.Column('symbol_name', sa.String(length=512), nullable=False),
+    sa.Column('qualified_name', sa.String(length=1024), nullable=False),
+    sa.Column('symbol_type', sa.String(length=32), nullable=False),
+    sa.Column('signature', sa.Text(), nullable=True),
+    sa.Column('start_line', sa.Integer(), nullable=False),
+    sa.Column('end_line', sa.Integer(), nullable=False),
+    sa.Column('parent_symbol_id', sa.Integer(), nullable=True),
+    sa.Column('source_code', sa.Text(), nullable=False),
+    sa.Column('docstring', sa.Text(), nullable=True),
+    sa.Column('source_hash', sa.String(length=64), nullable=False),
+    sa.Column('commit_sha', sa.String(length=64), nullable=True),
+    sa.Column('token_count', sa.Integer(), nullable=False),
+    sa.Column('search_document', sa.Text(), nullable=False),
+    sa.Column('fts', postgresql.TSVECTOR(), sa.Computed("to_tsvector('english', search_document)", persisted=True), nullable=False),
+    sa.Column('created_at', sa.DateTime(), server_default=sa.text('now()'), nullable=False),
+    sa.Column('updated_at', sa.DateTime(), server_default=sa.text('now()'), nullable=False),
+    sa.ForeignKeyConstraint(['parent_symbol_id'], ['symbols.id'], ondelete='CASCADE'),
+    sa.ForeignKeyConstraint(['repository_id'], ['repositories.id'], ondelete='CASCADE'),
+    sa.ForeignKeyConstraint(['source_file_id'], ['source_files.id'], ondelete='CASCADE'),
+    sa.PrimaryKeyConstraint('id')
+    )
+    op.create_index('ix_symbols_commit', 'symbols', ['commit_sha'], unique=False)
+    op.create_index('ix_symbols_fts', 'symbols', ['fts'], unique=False, postgresql_using='gin')
+    op.create_index('ix_symbols_path', 'symbols', ['repository_id', 'file_path'], unique=False)
+    op.create_index('ix_symbols_repo', 'symbols', ['repository_id'], unique=False)
+    op.create_index('ix_symbols_repo_qualified', 'symbols', ['repository_id', 'qualified_name'], unique=False)
+    op.create_index('ix_symbols_repo_type', 'symbols', ['repository_id', 'symbol_type'], unique=False)
+    op.create_index('ix_symbols_source_hash', 'symbols', ['source_hash'], unique=False)
+    op.create_table('retrieval_results',
+    sa.Column('id', sa.Integer(), nullable=False),
+    sa.Column('query_id', sa.Integer(), nullable=False),
+    sa.Column('symbol_id', sa.Integer(), nullable=False),
+    sa.Column('rank', sa.Integer(), nullable=False),
+    sa.Column('score', sa.Float(), nullable=False),
+    sa.Column('reasons', postgresql.JSONB(astext_type=sa.Text()), nullable=True),
+    sa.Column('selected', sa.Boolean(), nullable=False),
+    sa.Column('created_at', sa.DateTime(), server_default=sa.text('now()'), nullable=False),
+    sa.ForeignKeyConstraint(['query_id'], ['queries.id'], ondelete='CASCADE'),
+    sa.ForeignKeyConstraint(['symbol_id'], ['symbols.id'], ondelete='CASCADE'),
+    sa.PrimaryKeyConstraint('id')
+    )
+    op.create_index('ix_retrieval_query', 'retrieval_results', ['query_id'], unique=False)
+    op.create_table('symbol_embeddings',
+    sa.Column('id', sa.Integer(), nullable=False),
+    sa.Column('repository_id', sa.Integer(), nullable=False),
+    sa.Column('symbol_id', sa.Integer(), nullable=False),
+    sa.Column('source_hash', sa.String(length=64), nullable=False),
+    sa.Column('embedding_model', sa.String(length=255), nullable=False),
+    sa.Column('embedding_version', sa.String(length=64), nullable=False),
+    sa.Column('embedding_dimension', sa.Integer(), nullable=False),
+    sa.Column('embedding', pgvector.sqlalchemy.Vector(), nullable=False),
+    sa.Column('created_at', sa.DateTime(), server_default=sa.text('now()'), nullable=False),
+    sa.ForeignKeyConstraint(['repository_id'], ['repositories.id'], ondelete='CASCADE'),
+    sa.ForeignKeyConstraint(['symbol_id'], ['symbols.id'], ondelete='CASCADE'),
+    sa.PrimaryKeyConstraint('id'),
+    sa.UniqueConstraint('symbol_id', 'embedding_model', 'embedding_version', name='uq_embedding_symbol_model')
+    )
+    op.create_index('ix_embedding_repo', 'symbol_embeddings', ['repository_id'], unique=False)
+    op.create_table('symbol_relationships',
+    sa.Column('id', sa.Integer(), nullable=False),
+    sa.Column('repository_id', sa.Integer(), nullable=False),
+    sa.Column('source_symbol_id', sa.Integer(), nullable=False),
+    sa.Column('target_symbol_id', sa.Integer(), nullable=True),
+    sa.Column('target_name', sa.String(length=1024), nullable=True),
+    sa.Column('relationship_type', sa.String(length=32), nullable=False),
+    sa.Column('confidence', sa.Float(), nullable=False),
+    sa.Column('metadata', postgresql.JSONB(astext_type=sa.Text()), nullable=True),
+    sa.Column('created_at', sa.DateTime(), server_default=sa.text('now()'), nullable=False),
+    sa.ForeignKeyConstraint(['repository_id'], ['repositories.id'], ondelete='CASCADE'),
+    sa.ForeignKeyConstraint(['source_symbol_id'], ['symbols.id'], ondelete='CASCADE'),
+    sa.ForeignKeyConstraint(['target_symbol_id'], ['symbols.id'], ondelete='CASCADE'),
+    sa.PrimaryKeyConstraint('id')
+    )
+    op.create_index('ix_rel_repo_source', 'symbol_relationships', ['repository_id', 'source_symbol_id'], unique=False)
+    op.create_index('ix_rel_repo_target', 'symbol_relationships', ['repository_id', 'target_symbol_id'], unique=False)
+    op.create_index('ix_rel_type', 'symbol_relationships', ['relationship_type'], unique=False)
+    # ### end Alembic commands ###
+
+
+def downgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.drop_index('ix_rel_type', table_name='symbol_relationships')
+    op.drop_index('ix_rel_repo_target', table_name='symbol_relationships')
+    op.drop_index('ix_rel_repo_source', table_name='symbol_relationships')
+    op.drop_table('symbol_relationships')
+    op.drop_index('ix_embedding_repo', table_name='symbol_embeddings')
+    op.drop_table('symbol_embeddings')
+    op.drop_index('ix_retrieval_query', table_name='retrieval_results')
+    op.drop_table('retrieval_results')
+    op.drop_index('ix_symbols_source_hash', table_name='symbols')
+    op.drop_index('ix_symbols_repo_type', table_name='symbols')
+    op.drop_index('ix_symbols_repo_qualified', table_name='symbols')
+    op.drop_index('ix_symbols_repo', table_name='symbols')
+    op.drop_index('ix_symbols_path', table_name='symbols')
+    op.drop_index('ix_symbols_fts', table_name='symbols', postgresql_using='gin')
+    op.drop_index('ix_symbols_commit', table_name='symbols')
+    op.drop_table('symbols')
+    op.drop_table('llm_requests')
+    op.drop_index('ix_source_files_repo', table_name='source_files')
+    op.drop_table('source_files')
+    op.drop_table('queries')
+    op.drop_table('indexing_runs')
+    op.drop_index(op.f('ix_repositories_name'), table_name='repositories')
+    op.drop_table('repositories')
+    op.drop_table('evaluation_runs')
+    # ### end Alembic commands ###

coderag/db/models.py

@@ -0,0 +1,275 @@
+"""SQLAlchemy 2.0 ORM models — the persisted code index and telemetry.
+
+Design notes:
+  * Every retrieval-relevant table carries ``repository_id`` so queries can
+    (and must) be scoped to a single repository — see ``security/authz.py``.
+  * ``symbols.fts`` is a generated ``tsvector`` (Postgres full-text search).
+  * ``symbol_embeddings.embedding`` uses a dimension-less pgvector column so
+    the embedding model (and its dimension) can change without a schema
+    migration; the concrete dimension is recorded per row.
+"""
+
+from __future__ import annotations
+
+import datetime as dt
+
+from pgvector.sqlalchemy import Vector
+from sqlalchemy import (
+    JSON,
+    Boolean,
+    Computed,
+    Float,
+    ForeignKey,
+    Index,
+    Integer,
+    String,
+    Text,
+    UniqueConstraint,
+    func,
+)
+from sqlalchemy.dialects.postgresql import JSONB, TSVECTOR
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column, relationship
+
+
+class Base(DeclarativeBase):
+    type_annotation_map = {dict: JSON}
+
+
+TS = dt.datetime
+
+
+class Repository(Base):
+    __tablename__ = "repositories"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    name: Mapped[str] = mapped_column(String(255), unique=True, index=True)
+    url: Mapped[str | None] = mapped_column(String(1024), nullable=True)
+    local_path: Mapped[str] = mapped_column(String(1024))
+    default_branch: Mapped[str] = mapped_column(String(255), default="main")
+    indexed_commit_sha: Mapped[str | None] = mapped_column(String(64), nullable=True)
+    created_at: Mapped[TS] = mapped_column(server_default=func.now())
+    updated_at: Mapped[TS] = mapped_column(server_default=func.now(), onupdate=func.now())
+
+
+class SourceFile(Base):
+    __tablename__ = "source_files"
+    __table_args__ = (
+        UniqueConstraint("repository_id", "path", name="uq_source_files_repo_path"),
+        Index("ix_source_files_repo", "repository_id"),
+    )
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    repository_id: Mapped[int] = mapped_column(
+        ForeignKey("repositories.id", ondelete="CASCADE")
+    )
+    path: Mapped[str] = mapped_column(String(1024))
+    language: Mapped[str] = mapped_column(String(32))
+    content_hash: Mapped[str] = mapped_column(String(64))
+    size_bytes: Mapped[int] = mapped_column(Integer, default=0)
+    # Whole-file token count, recorded at index time so the "what would reading
+    # this file have cost?" baseline needs no file I/O at query time.
+    token_count: Mapped[int] = mapped_column(Integer, default=0)
+    indexed_commit_sha: Mapped[str | None] = mapped_column(String(64), nullable=True)
+    created_at: Mapped[TS] = mapped_column(server_default=func.now())
+    updated_at: Mapped[TS] = mapped_column(server_default=func.now(), onupdate=func.now())
+
+
+class Symbol(Base):
+    __tablename__ = "symbols"
+    __table_args__ = (
+        Index("ix_symbols_repo", "repository_id"),
+        Index("ix_symbols_repo_qualified", "repository_id", "qualified_name"),
+        Index("ix_symbols_repo_type", "repository_id", "symbol_type"),
+        Index("ix_symbols_path", "repository_id", "file_path"),
+        Index("ix_symbols_source_hash", "source_hash"),
+        Index("ix_symbols_commit", "commit_sha"),
+        Index("ix_symbols_fts", "fts", postgresql_using="gin"),
+    )
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    repository_id: Mapped[int] = mapped_column(
+        ForeignKey("repositories.id", ondelete="CASCADE")
+    )
+    source_file_id: Mapped[int] = mapped_column(
+        ForeignKey("source_files.id", ondelete="CASCADE")
+    )
+    file_path: Mapped[str] = mapped_column(String(1024))
+    language: Mapped[str] = mapped_column(String(32))
+
+    symbol_name: Mapped[str] = mapped_column(String(512))
+    qualified_name: Mapped[str] = mapped_column(String(1024))
+    symbol_type: Mapped[str] = mapped_column(String(32))  # module|class|function|method
+    signature: Mapped[str | None] = mapped_column(Text, nullable=True)
+
+    start_line: Mapped[int] = mapped_column(Integer)
+    end_line: Mapped[int] = mapped_column(Integer)
+    parent_symbol_id: Mapped[int | None] = mapped_column(
+        ForeignKey("symbols.id", ondelete="CASCADE"), nullable=True
+    )
+
+    source_code: Mapped[str] = mapped_column(Text)
+    docstring: Mapped[str | None] = mapped_column(Text, nullable=True)
+    source_hash: Mapped[str] = mapped_column(String(64))
+    commit_sha: Mapped[str | None] = mapped_column(String(64), nullable=True)
+    token_count: Mapped[int] = mapped_column(Integer, default=0)
+
+    # Text feeding full-text search (identifiers + signature + docstring).
+    search_document: Mapped[str] = mapped_column(Text, default="")
+    fts: Mapped[str] = mapped_column(
+        TSVECTOR,
+        Computed("to_tsvector('english', search_document)", persisted=True),
+    )
+
+    created_at: Mapped[TS] = mapped_column(server_default=func.now())
+    updated_at: Mapped[TS] = mapped_column(server_default=func.now(), onupdate=func.now())
+
+    parent: Mapped[Symbol | None] = relationship(
+        "Symbol", remote_side="Symbol.id", back_populates="children"
+    )
+    children: Mapped[list[Symbol]] = relationship(
+        "Symbol", back_populates="parent", viewonly=True
+    )
+
+
+class SymbolRelationship(Base):
+    __tablename__ = "symbol_relationships"
+    __table_args__ = (
+        Index("ix_rel_repo_source", "repository_id", "source_symbol_id"),
+        Index("ix_rel_repo_target", "repository_id", "target_symbol_id"),
+        Index("ix_rel_type", "relationship_type"),
+    )
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    repository_id: Mapped[int] = mapped_column(
+        ForeignKey("repositories.id", ondelete="CASCADE")
+    )
+    source_symbol_id: Mapped[int] = mapped_column(
+        ForeignKey("symbols.id", ondelete="CASCADE")
+    )
+    # Target may be unresolved (an external/未-indexed name), so it is nullable
+    # and we also keep the raw target_name.
+    target_symbol_id: Mapped[int | None] = mapped_column(
+        ForeignKey("symbols.id", ondelete="CASCADE"), nullable=True
+    )
+    target_name: Mapped[str | None] = mapped_column(String(1024), nullable=True)
+    relationship_type: Mapped[str] = mapped_column(String(32))
+    confidence: Mapped[float] = mapped_column(Float, default=1.0)
+    meta: Mapped[dict | None] = mapped_column("metadata", JSONB, nullable=True)
+    created_at: Mapped[TS] = mapped_column(server_default=func.now())
+
+
+class SymbolEmbedding(Base):
+    __tablename__ = "symbol_embeddings"
+    __table_args__ = (
+        UniqueConstraint(
+            "symbol_id", "embedding_model", "embedding_version",
+            name="uq_embedding_symbol_model",
+        ),
+        Index("ix_embedding_repo", "repository_id"),
+    )
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    repository_id: Mapped[int] = mapped_column(
+        ForeignKey("repositories.id", ondelete="CASCADE")
+    )
+    symbol_id: Mapped[int] = mapped_column(ForeignKey("symbols.id", ondelete="CASCADE"))
+    source_hash: Mapped[str] = mapped_column(String(64))
+    embedding_model: Mapped[str] = mapped_column(String(255))
+    embedding_version: Mapped[str] = mapped_column(String(64))
+    embedding_dimension: Mapped[int] = mapped_column(Integer)
+    embedding: Mapped[list[float]] = mapped_column(Vector())  # dimension-less
+    created_at: Mapped[TS] = mapped_column(server_default=func.now())
+
+
+class IndexingRun(Base):
+    __tablename__ = "indexing_runs"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    repository_id: Mapped[int] = mapped_column(
+        ForeignKey("repositories.id", ondelete="CASCADE")
+    )
+    mode: Mapped[str] = mapped_column(String(16))  # full|incremental
+    status: Mapped[str] = mapped_column(String(16), default="running")
+    from_commit: Mapped[str | None] = mapped_column(String(64), nullable=True)
+    to_commit: Mapped[str | None] = mapped_column(String(64), nullable=True)
+    files_indexed: Mapped[int] = mapped_column(Integer, default=0)
+    files_deleted: Mapped[int] = mapped_column(Integer, default=0)
+    symbols_indexed: Mapped[int] = mapped_column(Integer, default=0)
+    symbols_deleted: Mapped[int] = mapped_column(Integer, default=0)
+    embeddings_created: Mapped[int] = mapped_column(Integer, default=0)
+    duration_seconds: Mapped[float] = mapped_column(Float, default=0.0)
+    error: Mapped[str | None] = mapped_column(Text, nullable=True)
+    started_at: Mapped[TS] = mapped_column(server_default=func.now())
+    finished_at: Mapped[TS | None] = mapped_column(nullable=True)
+
+
+class QueryRecord(Base):
+    __tablename__ = "queries"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    repository_id: Mapped[int] = mapped_column(
+        ForeignKey("repositories.id", ondelete="CASCADE")
+    )
+    query_text: Mapped[str] = mapped_column(Text)
+    mode: Mapped[str] = mapped_column(String(16))  # search|context|ask
+    candidates_found: Mapped[int] = mapped_column(Integer, default=0)
+    candidates_selected: Mapped[int] = mapped_column(Integer, default=0)
+    candidate_tokens: Mapped[int] = mapped_column(Integer, default=0)
+    context_tokens: Mapped[int] = mapped_column(Integer, default=0)
+    dropped_tokens: Mapped[int] = mapped_column(Integer, default=0)
+    # Counterfactual: tokens it would have cost to read the whole files that the
+    # selected symbols came from (the "just open the files" baseline).
+    baseline_tokens: Mapped[int] = mapped_column(Integer, default=0)
+    baseline_files: Mapped[int] = mapped_column(Integer, default=0)
+    retrieval_latency_ms: Mapped[float] = mapped_column(Float, default=0.0)
+    created_at: Mapped[TS] = mapped_column(server_default=func.now())
+
+
+class RetrievalResult(Base):
+    __tablename__ = "retrieval_results"
+    __table_args__ = (Index("ix_retrieval_query", "query_id"),)
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    query_id: Mapped[int] = mapped_column(ForeignKey("queries.id", ondelete="CASCADE"))
+    symbol_id: Mapped[int] = mapped_column(ForeignKey("symbols.id", ondelete="CASCADE"))
+    rank: Mapped[int] = mapped_column(Integer)
+    score: Mapped[float] = mapped_column(Float)
+    reasons: Mapped[dict | None] = mapped_column(JSONB, nullable=True)
+    selected: Mapped[bool] = mapped_column(Boolean, default=False)
+    created_at: Mapped[TS] = mapped_column(server_default=func.now())
+
+
+class LLMRequest(Base):
+    __tablename__ = "llm_requests"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    query_id: Mapped[int | None] = mapped_column(
+        ForeignKey("queries.id", ondelete="SET NULL"), nullable=True
+    )
+    provider: Mapped[str] = mapped_column(String(64))
+    model: Mapped[str] = mapped_column(String(128))
+    input_tokens: Mapped[int] = mapped_column(Integer, default=0)
+    output_tokens: Mapped[int] = mapped_column(Integer, default=0)
+    cached_input_tokens: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    latency_ms: Mapped[float] = mapped_column(Float, default=0.0)
+    success: Mapped[bool] = mapped_column(Boolean, default=True)
+    error: Mapped[str | None] = mapped_column(Text, nullable=True)
+    created_at: Mapped[TS] = mapped_column(server_default=func.now())
+
+
+class EvaluationRun(Base):
+    __tablename__ = "evaluation_runs"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    name: Mapped[str] = mapped_column(String(255))
+    dataset: Mapped[str] = mapped_column(String(1024))
+    recall_at_1: Mapped[float] = mapped_column(Float, default=0.0)
+    recall_at_3: Mapped[float] = mapped_column(Float, default=0.0)
+    recall_at_5: Mapped[float] = mapped_column(Float, default=0.0)
+    recall_at_10: Mapped[float] = mapped_column(Float, default=0.0)
+    mrr: Mapped[float] = mapped_column(Float, default=0.0)
+    avg_retrieved_tokens: Mapped[float] = mapped_column(Float, default=0.0)
+    avg_context_tokens: Mapped[float] = mapped_column(Float, default=0.0)
+    avg_retrieval_latency_ms: Mapped[float] = mapped_column(Float, default=0.0)
+    config: Mapped[dict | None] = mapped_column(JSONB, nullable=True)
+    created_at: Mapped[TS] = mapped_column(server_default=func.now())

coderag/embeddings/base.py

@@ -0,0 +1,53 @@
+"""Embedding provider abstraction.
+
+No source code should need to leave company infrastructure to be embedded, so
+every provider runs locally. The default (``HashingEmbeddingProvider``) is
+deterministic and dependency-free; ``SentenceTransformerEmbeddingProvider`` uses
+a local model. Embeddings are provider-independent: each stored vector records
+its model, version, and dimension so the model can change and code can be
+re-embedded (ADR-005 / schema notes).
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+
+class EmbeddingProvider(ABC):
+    model_name: str
+    model_version: str
+    dimension: int
+
+    @abstractmethod
+    def embed_documents(self, texts: list[str]) -> list[list[float]]:
+        """Embed a batch of documents (structured symbol inputs)."""
+
+    @abstractmethod
+    def embed_query(self, text: str) -> list[float]:
+        """Embed a single query string."""
+
+
+def build_embedding_input(
+    repository_name: str,
+    file_path: str,
+    qualified_name: str,
+    symbol_type: str,
+    signature: str | None,
+    docstring: str | None,
+    source_code: str,
+    max_code_chars: int = 4000,
+) -> str:
+    """Compose an embedding input that carries structural context (spec §9)."""
+    code = source_code if len(source_code) <= max_code_chars else source_code[:max_code_chars]
+    parts = [
+        f"Repository: {repository_name}",
+        f"File: {file_path}",
+        f"Symbol: {qualified_name}",
+        f"Type: {symbol_type}",
+    ]
+    if signature:
+        parts.append(f"Signature: {signature}")
+    if docstring:
+        parts.append(f"Documentation: {docstring}")
+    parts.append(f"Code:\n{code}")
+    return "\n".join(parts)

coderag/embeddings/hashing.py

@@ -0,0 +1,43 @@
+"""Deterministic, offline embedding provider (default).
+
+Uses signed feature hashing over word-expanded identifiers: each token is hashed
+to a bucket with a +/- sign, summed, and L2-normalised. This is NOT a learned
+semantic model — similarity reflects shared vocabulary — but it is fully offline,
+deterministic, and dependency-free, which makes it ideal for tests, CI, and
+air-gapped dev. For genuine semantic matching use
+``SentenceTransformerEmbeddingProvider``.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import math
+
+from coderag.core.text import expand_query_terms
+from coderag.embeddings.base import EmbeddingProvider
+
+
+class HashingEmbeddingProvider(EmbeddingProvider):
+    model_version = "1"
+
+    def __init__(self, dimension: int = 384) -> None:
+        self.dimension = dimension
+        self.model_name = f"hashing-{dimension}"
+
+    def _embed(self, text: str) -> list[float]:
+        vec = [0.0] * self.dimension
+        for token in expand_query_terms(text):
+            digest = hashlib.md5(token.lower().encode("utf-8")).digest()  # noqa: S324
+            idx = int.from_bytes(digest[:4], "big") % self.dimension
+            sign = 1.0 if (digest[4] & 1) else -1.0
+            vec[idx] += sign
+        norm = math.sqrt(sum(v * v for v in vec))
+        if norm > 0:
+            vec = [v / norm for v in vec]
+        return vec
+
+    def embed_documents(self, texts: list[str]) -> list[list[float]]:
+        return [self._embed(t) for t in texts]
+
+    def embed_query(self, text: str) -> list[float]:
+        return self._embed(text)