A fluent knowledge assistant
AI.project builds an Assistant through documents, model, embedder, vector-store and retrieval options. Configuration methods compose; index, ask, evaluate and deploy execute the corresponding stages.
01 / THE IDEA
A closer look.
A Python library with a shared interface for model providers, retrieval, agents, tools, workflows, evaluation and deployment. Its knowledge-assistant path composes document ingestion, hybrid search, reranking and source-linked answers, with an offline mock model and local hashing embedder available from the start.
A model call is one stage in a larger system. aire exposes the contracts around it—data, retrieval, tools, safety and evaluation—so the same application structure can be exercised locally and connected to configured providers.
Hybrid retrieval with explicit mechanics
The Retriever embeds the query, searches vectors and conditionally adds keyword hits. Reciprocal Rank Fusion combines rankings; retrieval then applies access filters and reranking before context assembly.
Provider-neutral model contracts
provider:name references resolve through a model registry and plugins. Models return structured generation objects, while AireError exposes stable codes, context and retryability.
Offline development and inspectable components
mock:echo and local:hashing support a credential-free local loop. describe surfaces report component configuration and capabilities; intentionally incomplete media surfaces identify stub behavior.
02 / UNDER THE SURFACE
Inside the knowledge-assistant pipeline
Trace ingestion and query-time retrieval before following the provider call.
DRAG TO PAN · SELECT A NODE · + / − TO ZOOM
Read the architecture as text
- AI.project — The AI facade exposes namespaces for models, retrieval, agents and other capabilities. AI.project creates the fluent knowledge-assistant builder.
- Assistant builder — Assistant stores document sources, provider references and retrieval options. knowledge materializes its underlying Knowledge object when needed.
- Document loading — Loaders turn configured source inputs into documents. Their text and metadata supply the chunking and source-identity stages.
- Overlapping chunks — FixedChunker advances by size minus overlap and records start/end spans. Other supplied strategies include recursive, sentence and embedding-semantic chunking.
- Embedding contract — ModelRegistry resolves the configured embedding provider. The Assistant resolves the embedder before ingestion or asking a question.
- Vector + text store — LocalVectorStore holds Chunk records in a dictionary with optional JSON persistence. Vector search uses cosine similarity; text search uses a BM25-style term score.
- Query + rewrite — Knowledge.retrieve can rewrite a query into several queries. Hits are deduplicated by chunk ID, preserving the best score before reranking.
- Hybrid retrieval — Retriever searches vector candidates and uses keyword search only when the store declares keyword-search support. RRF avoids directly mixing incomparable raw score scales.
- Rank fusion — Each result contributes weight/(rrf_k + rank + 1); contributions for the same chunk are accumulated and sorted. Default vector and keyword weights are 1.0 and 0.7.
- ACL + reranking — Merged filters constrain retrieval, and filter_hits applies default ACL before the final reranker. The chosen reranker returns the requested k chunks.
- Context assembly — ask applies optional input guardrails, retrieves hits and compresses context to a character budget. The prompt template combines that context with the question.
- Provider registry — The answering model is resolved independently of the embedder. A string reference chooses a configured provider implementation.
- Generate request — GenerationRequest.of packages the prompt and generation options. A provider-neutral Model produces text plus usage and model metadata.
- Answer + citations — The Answer contains text, model reference, retrieved count and usage. Citation objects preserve each retrieved chunk’s source, ID, excerpt, score and index.
- Evaluate + serve — The builder can evaluate its question-answering target against a dataset or wrap the Knowledge pipeline in a FastAPI app when the serving extra is installed.
03 / INTERACTIVE STUDY
Shape the retrieval window
Explore how chunk size, overlap and top-k change a synthetic document’s indexing and retrieval footprint.
CHANGE THE INPUTS
Illustrative chunking/retrieval model using synthetic text. It does not run aire, create embeddings or measure answer quality. The real library offers multiple chunkers, stores and rerankers.
ILLUSTRATIVE MODELLIVE
04 / ENGINEERING CHOICES
Why it works this way.
Use rank fusion for hybrid search
Vector and keyword scores have different numerical meanings. Weighted reciprocal ranks provide a shared combination method; hybrid fusion is skipped when the store lacks keyword-search capability.
Separate configuration from execution
Fluent methods store choices while index and ask execute them. Sync wrappers and async entrypoints support different calling environments without changing the pipeline’s conceptual structure.
Make incomplete surfaces visible
The README calls the library alpha and documents honest stubs for parts of vision, audio and training. Component descriptions and return flags help avoid mistaking a placeholder for a production model.
05 / OPEN THE SOURCE
Trace it back.
Implementation details, examples, and project documentation.
Fluent project builder
Inspected configuration, index, ask, evaluation and deployment methods.
Hybrid rank fusion
Inspected candidate collection, capability gating and RRF.
Retrieval-to-answer pipeline
Access filtering, context compression, generation and citations.
Local search implementation
Cosine similarity, BM25-style text ranking and optional persistence.
Scope & limitations
- The repository explicitly labels v0.3.x alpha; APIs can change, and portions of vision, audio and foundation/training support are intentionally incomplete or stubbed.
- Local hashing and mock:echo make a reproducible offline path, but they do not establish semantic retrieval quality or production answer quality. Retrieved-source citations alone do not prove factual grounding.
Architecture and descriptions reflect the linked repository snapshot. The playground explains a mechanism; it does not execute the repository or report measured performance.