Alpha 6 — "Pull the Band-Aid"

[bashandbone]

Alpha 6 — "Pull the Band-Aid"

Overview

This is the combined Alpha 6 PR merging into main. It's not a reviewable unit — it represents months of incremental work that's already been reviewed piecemeal. I'm not expecting a full review here, only a sanity check for integration issues or glaring concerns.

This is a near-total refactor of CodeWeaver's core internals. With only a handful of users and real architectural debt accumulating, now was the right time to fix foundations before they became load-bearing problems.

---

Summary of Changes

Structure

Monorepo Readiness

In preparation for the Alpha 7 monorepo split, I realigned CodeWeaver's internal organization and significantly reduced cross-dependencies. The structure now maps cleanly to the planned package dependency ladder:

core / tokenizers / daemon → semantic → providers → engine → server

(cli remains unique — it can attach to any package with self-limiting functionality.)

Major moves:

• Eliminated common, consolidating utilities and types into core and machinery into engine
• Merged di into core
• Eliminated the top-level config package; each package now owns its own config for types relevant to it, with core types defined in core/config/core/
• Merged agent, data, embedding, reranking, and vector_stores into providers
• Merged mcp, agent_api, and middleware into server

Federated Config

The config system needed to adapt based on which packages a user has installed. To support this:

• Config is now split into package-level components
• Each package has a pydantic_settings.BaseSettings subclass in core.types.settings_model, following the dependency ladder: CodeWeaverCoreSettings → CodeWeaverProviderSettings → CodeWeaverEngineSettings → CodeWeaverSettings
• A special loader in core.config.loader resolves the most complete available settings class at runtime and assigns it the role of CodeWeaverSettings. In code, these are referenced via the type alias union CodeWeaverSettingsType.

DI — Fully Implemented

The DI system was the primary motivation for this refactor. Alpha 1-5's registry-based approach made it impossible to control state across the full pipeline — unit tests were fine, but meaningful integration testing wasn't. DI was the right fix.

The system is now fully implemented and modeled on patterns from libraries like FastAPI, with some improvements for usability. It handles:

• Sync and async contexts, functions, methods
• Fine-grained type resolution via tags
• Sequences and collections, not just individual types
• Type aliases, Annotated types, string forms, instances, data, sync and async context managers
• Granular scoping and caching
• Type-checker compatibility (not perfect, but type checkers can generally resolve underlying types)

Call site pattern:

from codeweaver.core.di import INJECTED
from codeweaver.engine.dependencies import IndexerDep

def do_indexing_thing(indexer: IndexerDep = INJECTED):
    pass  # IndexerDep is a type alias for something like:
          # Annotated[IndexingService, depends(some_factory_function, **options)]
          #
          # INJECTED is a sentinel that:
          # 1. Tells the DI infrastructure to handle the dependency
          # 2. Prevents callers from needing to supply DI dependencies directly
          # 3. Transfers type information from the annotated alias to type checkers

Registering a factory:

from codeweaver.core.di import dependency_provider

@dependency_provider(SomeType, scope="singleton", tags=["optional_tag"], collection=False)
def _create_some_type() -> SomeType:
    # factory logic
    return some_type

dependency_provider is syntactic sugar for importing the Container directly. Factory functions can themselves take injected dependencies as arguments.

Organizationally: core DI machinery lives in codeweaver.core.di; dependency factories and type aliases live in each package's dependencies module or package. This lets each package define its own internal dependencies, resolved automatically at runtime.

---

Test Fixtures — Complete Rewrite

I rewrote the majority of test fixtures from scratch to use the DI system natively — a big job, but necessary to get the state isolation the original motivation demanded. Most of the test suite was also updated to reflect new APIs and structure.

CodeWeaver now has ~1,000 unit tests and ~300 integration tests, all passing. Coverage is still below where I want it; that's a priority going forward. (Full coverage has never been a goal and isn't now.)

---

Provider Config — Ground-Up Rewrite

The Alpha 1-5 config system required translating between CodeWeaver's config objects and every SDK client, provider, and cross-provider scenario. That translation was nearly impossible to keep clean. The new system aligns the types directly:

• ClientOptions — SDK client constructor configuration. If a setting can be passed to the client's constructor (e.g. AsyncOpenAI), it's available in the corresponding ClientOptions subclass.
• ProviderConfig — Category-and-provider aligned options for a provider's core methods (e.g. an embed call for an embedding provider).
• Unified category-level settings objects — abstract the above differences for underlying config and client options.

Model capabilities are no longer hardcoded. Capabilities can now be dynamically registered and are optional — CodeWeaver trusts the user to supply correct model information. Given the pace of model releases, this prevents CodeWeaver from going stale between releases. You can use a new model on the day it ships.

Asymmetric Embedding Support

While this refactor was underway, Voyage AI released the voyage-4 series, which has a few notable properties:

1. Tops most real-world code retrieval benchmarks
2. Includes voyage-4-nano — a 300M parameter, Apache 2.0 licensed model (built on Qwen3) available on Hugging Face
3. The full family shares an embedding space — you can query with any model against embeddings generated by any other, with only a ~2-3% retrieval hit

I built native support for asymmetric model families via AsymmetricEmbeddingProviderSettings, which takes a full EmbeddingProviderSettings object for both query_config and embed_config. This means you can, for example, use FastEmbed or SentenceTransformers for voyage-4-nano locally while hitting Voyage's API for voyage-4-large in the cloud — and they'll work against the same embeddings.

voyage-4-nano also punches well above its weight on its own embeddings. For a model that runs on a consumer laptop, it outperforms most frontier models. The voyage-4 family is now CodeWeaver's default for both cloud and local inference.

Service Cards

The new ServiceCard class and registry in codeweaver.core.types.service_cards simplifies SDK client and provider instantiation and forms the backbone of providers' dependency factories. It also supports dynamic provider and client registration at runtime.

Combined with DI, provider implementations are now dramatically simpler. Previously, providers had complex __init__ logic for resolving config and setup. Now, providers receive their complete set of attributes upfront and register them as attributes. No factory logic in __init__.

Agent and Data Providers

Agent and data providers are now implemented as part of the providers refactor. Agents (internally called "context agents") will serve as resolution helpers; data providers are essentially their tools. Neither is wired up yet — that's Alpha 7.

---

Engine — Services and Management Separated

The previous engine had mixed concerns, complex stateful handling, and was hard to test and reason about. It's responsible for a lot: file discovery, AST and delimiter-based chunking, deduplication and invalidation, coordinating dense and sparse embedding, managing vector database state, and handling fallbacks for all of the above.

The new engine separates stateless services from stateful managers:

Services: chunking, config analysis (new — safely resolves configuration changes), failover, indexing, migration, reconciliation, snapshot, file watching

Managers: CheckpointManager, ManifestManager, ProgressTracker

Almost all core engine capabilities are now stateless. This also sets up a clean integration point for a new engine, likely from knitli/recoco or the flow crate in knitli/thread.

---

Failover System — Complete Redesign

The Alpha 1-5 failover system had several problems:

• Always enabled, even when using only local providers
• Sometimes required generating two sets of chunks (due to context window mismatches between primary and backup models)
• Always required maintaining a completely separate vector store
• Used an in-memory backup store persisted to JSON, ignoring Qdrant's built-in capabilities
• Required complex primary/backup config handling inside vector store providers
• Overlooked that sparse embedding providers are local and almost never need backup

Four Problems, Three Solutions

Breaking the problem down:

Problems:

1. Embedding/reranking models with small context windows require rechunking
2. Cloud dense embedding providers may be unavailable at call time
3. Cloud vector stores may similarly be unavailable
4. Generating redundant sparse embeddings is wasteful when the sparse provider is almost always local

Solutions:

1. Failover embedding and reranking models are no longer configurable. By preselecting models with sufficient context windows, the system always handles any chunk without deciding whether to generate one or two sets of chunks — eliminating the corresponding deduplication and collection resolution complexity.

2. Backup embeddings are generated with a lightweight local model only if the configured dense model is not local, does not support asymmetric embeddings (which would allow a local model to substitute), and backup is not disabled. Enabled by default when those conditions are met. Backup embeddings now live on the same point as primary embeddings — Qdrant supports arbitrary numbers of vectors per point, and with problem Fix linting errors and warnings #1 resolved, there's no risk of inconsistent data representation.

3. Cloud vector store fallback uses Qdrant's write-ahead logging and snapshots to maintain a local collection that's always available. If the cloud connection fails, the system picks up the local version and reconciles when the primary returns.

These two solutions activate independently. If your cloud embedding provider goes down but your vector store doesn't, only embedding failover activates.

Vector Store Simplification

With failover concerns removed from the vector store providers themselves, the primary/backup config and provider management complexity is gone. Resolving which embeddings are present is now a simple iteration over points: find missing vectors, ask the corresponding provider to fill the gap. This handles both the transition to backup and the return to primary cleanly.

---

Docs

The docs site was previously scaffolded but unreleased. It's ready to go live with Alpha 6 or shortly after. This included adding Griffe-based scripting for API doc generation.

---

** Related Issues**:

This PR closes or supersedes the following issues:

• closes Add LiteLLM, Cerebras, and OpenRouter embedding provider support #108
• closes Differentiate boolean defaults from explicitly set values in server config #113
• closes Add parameter validation and fix model switch test #114
• closes [DI Phase 1] Foundation + monorepo prep (tokenizers, daemon, SearchResult) #117
• closes [DI Phase 2] Core migration - Breaking 75% of circular dependencies #118
• closes [DI Phase 4] pydantic-ai integration (agents + data sources) #119
• closes [DI Phase 5] Advanced features (health, telemetry, plugins) #120
• closes [DI Phase 6] Cleanup, registry simplification, and v0.4 breaking changes #121
• closes Test and reintegrate Fastembed custom model support #122
• closes Indexing in VSCode Terminal under WSL Causes Server Timeout and Crash #135
• closes Refactor indexer into a package and modularize core responsibilities for maintainability and AI-first architecture #148
• closes [Monorepo Phase 3] Organize into clean package structure (9 packages) #204

[sourcery-ai]

Sorry, we are unable to review this pull request

The GitHub API does not allow us to fetch diffs exceeding 300 files, and this pull request has 804

[Copilot]

Copilot reviewed 132 out of 804 changed files in this pull request and generated no comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Copilot reviewed 132 out of 804 changed files in this pull request and generated no comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Copilot reviewed 132 out of 804 changed files in this pull request and generated no comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	npm/​starlight-contributor-list@​0.3.2
	npm/​@​astrojs/​starlight-tailwind@​4.0.2 ⏵ 5.0.0				+6
	npm/​starlight-page-actions@​0.2.0 ⏵ 0.5.0	+2		+2	+1
	npm/​starlight-sidebar-topics@​0.6.2 ⏵ 0.7.1			+1	+5
	npm/​starlight-changelogs@​0.2.3 ⏵ 0.5.0	+1		+1
	npm/​astro-d2@​0.8.1 ⏵ 0.10.0	+1		+1	+8
	npm/​starlight-links-validator@​0.19.2 ⏵ 0.20.1				+7
	npm/​@​astrojs/​markdoc@​0.15.11 ⏵ 1.0.0	+1		+1
	npm/​@​astrojs/​starlight@​0.37.7 ⏵ 0.38.1			+1	+1
	npm/​astro@​6.0.4

View full report

[Copilot]

Copilot reviewed 132 out of 805 changed files in this pull request and generated no comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.