Skip to content

v0.5.0

Choose a tag to compare

View all tags
@PaulArgoud PaulArgoud released this 09 Jun 17:17
· 35 commits to main since this release
v0.5.0
75cef1f

Documentation reorganisation + internal refactor. No behaviour change, no
data migration, public API stable — safe drop-in upgrade from 0.4.0.

Changed (docs)

  • README trimmed from 354 → 144 lines. Onboarding stays in the README
    (badges, why, features, requirements, install, quick start, doc index,
    roadmap, limitations). Reference content moved to dedicated files so the
    front page is scannable in 60 s.
  • New ARCHITECTURE.md with two Mermaid diagrams (rendered natively
    by GitHub):
    • Flowchart of the two integration paths (Option A — filter override;
      Option B — Pinecone wire-protocol proxy).
    • Sequence diagram of a full query lifecycle (User → MxChat → adapter →
      query cache → vector store → DuckDB → dedup → rerank → metrics).
    • Plus the file layout and the five design conventions contributors
      should follow.
  • New docs/CONFIGURATION.md — every option in mxchat_duckdb_options,
    every sidecar option (proxy tokens, metrics, reprocess state, migration
    state), where data is stored, dimension/storage change guards.
  • New docs/HOOKS.md — all 9 filters with full signatures and PHP
    examples (Cohere/BGE reranker integration, ACF-aware post content,
    multi-bot bot_id derivation, rate-limit override, etc.).
  • New docs/CLI.md — every wp mxchat-duckdb subcommand with sample
    stdout and exit-code contract.
  • New docs/USAGE.md — howtos for the 5 specialised workflows: async
    reprocess (with monitoring + cancel), Pinecone migration (full semantics
    • resumption), Parquet backup/restore, INT8 quantization (when to use,
      switching layout), /health endpoint, end-to-end verification.
  • CONTRIBUTING.md updated to point new contributors at the right doc
    file for each kind of change (option → CONFIGURATION, filter → HOOKS,
    CLI subcommand → CLI).

Changed (internal refactor — no behaviour change)

  • Vector_Store split (858 → 323 lines). The 858-line monolith is now
    three coordinated classes sharing a trait:

    • MxChat_DuckDB_Vector_Store_Schema — migration runner + meta table +
      ensure_schema() + table_info(). Owns the per-request memoisation
      cache.
    • MxChat_DuckDB_Vector_Store_Query — top-K read path: cache lookup,
      vector + hybrid BM25 SQL, filter compiler, score normalisation, dedup,
      rerank hook, slow-query log.
    • MxChat_DuckDB_Vector_Store (façade) — keeps the public API stable
      (constructor + ensure_schema / query_pinecone_shape /
      upsert / delete_* / count / list_ids / fetch_by_ids /
      export_parquet / import_parquet / storage_estimate), delegating
      schema and query work to the two new classes.
    • MxChat_DuckDB_SQL_Helpers_Trait — shared quote_ident,
      literal_string, literal_for, literal_int_or_float_array,
      embedding_column_type, embedding_as_float_sql. Lives in
      includes/trait-duckdb-sql-helpers.php.

    Public API and option layout are unchanged; call-sites (sync, REST proxy,
    admin, CLI, async-reprocess, compactor, tests) all keep compiling without
    modification. Tests targeting the moved private statics
    (compile_filter, normalize_scores, dedup_per_source, cache_key)
    now reflect against Vector_Store_Query.

  • Sync split (453 → 76-line façade + 236 MySQL pipeline + 197 post
    reprocessor).     The orthogonal pipelines that lived together are now
    three classes:

    • MxChat_DuckDB_Mysql_Sync — full_sync, incremental_sync,
      cascade_delete_handler, vector_id_for_row (public static),
      detect_kb_columns, row_to_vector.
    • MxChat_DuckDB_Post_Reprocessor — reprocess_posts,
      reprocess_single_post, build_post_content,
      map_post_type_to_content_type, resolve_embedding_api_key.
    • MxChat_DuckDB_Sync (façade) — keeps instance(), register_hooks(),
      full_sync, incremental_sync, reprocess_posts,
      reprocess_single_post, cascade_delete_handler, and the public
      static vector_id_for_row for callers in the compactor and tests.

  • admin/views/settings.php split (369 → 73-line shell + 7 partials).
    Each <h2> section moved to its own file under
    admin/views/partials/:

    • section-activation.php
    • section-motherduck.php
    • section-embedded.php
    • section-vector-schema.php
    • section-retrieval-quality.php
    • section-performance.php
    • section-diagnostics.php

    The shell handles the page header, the last-error notice, the
    PECL/CLI performance warning, then includes each partial in order.
    Adding a new section is now one new file plus one new include line.

Notes

  • Largest PHP file went from 858 lines (class-duckdb-vector-store.php)
    to 332 lines (class-duckdb-cli.php, idiomatic command pattern).
  • No new public filters, no new options, no schema migration.
Assets 2
Loading