q.ai roadmap

This checklist tracks durable behavior, not package names. A checked item has a public implementation and deterministic contract test in this repository.

Stage 0: package foundation

• Single-source qrt.__version__ from installed package metadata.
• Lazy root namespace loading with preserved dir() discovery.
• Shared actionable optional-dependency error helper.
• Standard, local, document, and aggregate installation profiles.
• Subprocess tests for every optional profile in a clean wheel environment.

Stage 1: inference core

• Immutable Client, provider, deployment, retry, media, and redaction contracts.
• Direction-specific input blocks and forward-compatible output blocks.
• Explicit model references, aliases, longest provider-prefix resolution, and LoRA lineage.
• LiteLLM sync/async generation and OpenAI-compatible endpoints.
• Lifecycle-aware sync/async text streaming with final results and cancellation state.
• Usage, finish reason, request identity, hashes, and inference provenance.
• Opt-in non-serializable raw provider response.
• Pydantic structured extraction with distinct parse and validation errors.
• QRT transport retry with jitter, rate-limit policy, and pre-output stream retry.
• Tool-call delta assembly and sanitized partial results after provider failure.
• Native-schema capability matrix and prompted repair requests with separate usage.
• Audio/file transfer resolvers with root/domain/size allowlists.

Stage 2: embeddings, vector storage, and RAG

• Hosted LiteLLM embedding result contract.
• Lazy sentence-transformers backend with BGE small as the local default.
• LanceDB create/open/add/delete/vector-search adapter.
• Required publication and ingestion timestamps with strict as_of filtering.
• DuckDB Lance extension installation/loading and namespace attachment.
• LlamaIndex sentence chunking, stable chunk IDs, retrieval, context assembly, and sources.
• Docling document-to-source adapter.
• BGE reranker adapter and provider rerank API.
• Lance full-text/hybrid search in the public vector contract.
• Qdrant and pgvector supported adapters.
• Effective-period policy, access metadata enforcement, and strict backend filter verification.
• Financial PDF/table/scan benchmark for the preferred Docling configuration.

Stage 3: prompts, tools, agents, and evaluation

• Versioned deterministic prompts and rendered-content hashes.
• Typed tool schemas, allowlisted registry, timeouts, and validated results.
• Pydantic AI-backed typed agents with request, tool-call, and token limits.
• QRT evaluation cases, scorers, reports, and Pydantic Evals conversion.
• Filing-plus-price reference agent with retrieval citations and historical price policy.
• Hard pre-request monetary agent budget using provider price events.
• Agent trajectory records, resume/inspection, and OpenTelemetry hooks.
• Built-in schema, field, citation support, retrieval recall, and latency/cost scorers.

Stage 4: batch and durable runs

• pandas, Arrow, iterable, and Pydantic-record inputs with unique stable keys.
• Row-aligned successes, failures, usage, and targeted resume.
• Exact content-addressed cache identities.
• DuckDB run/cache catalog and Parquet result/failure/usage artifacts.
• Configurable async concurrency, rate limits, ordering, back-pressure, and checkpoints.
• Dataset partition identities and atomic recovery after process interruption.
• q.ray Ray Data execution over the same run records.
• Explicit semantic-cache policy and evaluation gates.

Stage 5: local models, serving, and adaptation

• Explicit Transformers engine lifecycle and named PEFT adapter switching.
• vLLM, SGLang, and llama.cpp command specifications and health checks.
• vLLM multi-LoRA deployments addressed as stable served model IDs.
• LoRA/QLoRA training configuration with model/tokenizer/dataset lineage.
• Hugging Face and tiktoken exact tokenization contracts.
• Chat-template message generation and canonical QRT result conversion in-process.
• Outlines direct-logit structured decoding adapter.
• TRL training execution, checkpoint publishing, and evaluation handoff.
• Ray Train and Ray Serve adapters under q.ray.
• Server model/capability discovery and container configuration generation.
• GigaToken equivalence and throughput benchmark before experimental adoption.

Quality gates

• Deterministic offline contract tests for core, transport translation, RAG, tools, batch, and specs.
• Fake OpenAI-compatible HTTP server covering disconnects, cancellation, and malformed events.
• Opt-in hosted provider, vLLM base/LoRA, Transformers/PEFT, Docling, and remote vector CI.
• Secret-leak, SSRF/media-policy, unauthorized tool/model loading, and retention tests.
• Dependency matrix across supported Python versions and all installation profiles.
• Representative accuracy, latency, throughput, memory, and cost benchmark suite.