ItemTooLargeError (with doc_id, namespace,
size_bytes, and limit_bytes) if one is too big. The whole call fails, so S3 Vectors
and DynamoDB never end up with half a batch.
-""" + code("""from dynavec import ItemTooLargeError
+"""
+ + code("""from dynavec import ItemTooLargeError
from dynavec.ingest import chunk_text
try:
@@ -372,72 +416,88 @@ def code(src: str) -> str:
for i, chunk in enumerate(chunk_text(long_text, chunk_size=2000))],
namespace="kb",
)
-"""))
+"""),
+)
-PAGES["update-and-lambda"] = ("Update & Lambda transforms",
+PAGES["update-and-lambda"] = (
+ "Update & Lambda transforms",
"Change text, vector, or metadata — and transform data in-account.",
"""
update() is a read-modify-write: metadata merges by default, and the vector is only
re-derived when the text changes or you pass a new vector.
Transform pipeline
Transforms are plain callables run on each document before it is written — for enrichment, redaction, or deriving vectors elsewhere.
-""" + code("""from dynavec.transforms import TransformPipeline +""" + + code("""from dynavec.transforms import TransformPipeline def redact(ctx): ctx.metadata["pii"] = False return ctx db.upsert(docs, transform=redact) # or transform=TransformPipeline([...]) -""") + """ +""") + + """Run the transform in your own AWS Lambda
LambdaTransform invokes a Lambda you own with the document payload and applies whatever it
returns — keeping custom logic in-account.
lambda:InvokeFunction on that function — see
Credentials & IAM.A source is any iterable of records. ingest() chunks, embeds, and upserts them.
From a Markdown or text directory
MarkdownSource reads UTF-8 .md and .txt files recursively.
Install dynavec[ingest] for YAML front matter support.
A Markdown file may begin with a YAML mapping between two --- lines:
Front matter becomes metadata and is removed from the text before chunking. Use storage-compatible values (strings, numbers, booleans, lists, and mappings); quote dates to keep them as strings. Malformed or unclosed front matter raises an error naming the file. Text files are read verbatim.
@@ -450,20 +510,25 @@ def redact(ctx):From any MCP server
MCPResourceSource turns an MCP server's resources (Notion, Confluence, Drive, your
own) into an embeddable corpus — no per-source code.
Chunk ids are "{record_id}#chunk{n}" with source_id / chunk
metadata, so you can group or delete a whole document later.
Provide a query string (embedded for you) or a raw vector. S3 Vectors returns the
nearest keys; dynavec hydrates the full documents from DynamoDB via BatchGetItem.
Metadata filtering
Filters use the S3 Vectors dialect — bare {"k": v} is equality; operators like
$gte, $in, $and, $or are supported. Only keys in
filterable_keys can be filtered.
Results come back as SearchResult with id, score (higher = more
similar), distance, text, and metadata. Refine ordering with
metrics & rerank, speed up repeats with
caching.
The S3 Vectors index metric is cosine or euclidean. On top of the returned candidates, dynavec can rescore with any metric — or a weighted combination — client-side.
-""" + code("""# single metric +""" + + code("""# single metric db.search("q", top_k=5, rescore="manhattan") # weighted combination (normalized per candidate set) db.search("q", top_k=5, rescore={"cosine": 0.7, "dot": 0.3}) -""") + """ +""") + + """MMR diversity rerank
Maximal Marginal Relevance balances relevance against diversity so results are not near-duplicates.
-""" + code("""db.search("q", top_k=5, rerank="mmr", mmr_lambda=0.5) # 1=relevance, 0=diversity -""") + """ +""" + + code("""db.search("q", top_k=5, rerank="mmr", mmr_lambda=0.5) # 1=relevance, 0=diversity +""") + + """Both over-fetch top_k * over_fetch candidates first. You can also fuse multiple result lists
with Reciprocal Rank Fusion:
A namespace gives each tenant an isolated view of the same dynavec index. Every vector is tagged with its @@ -515,7 +592,8 @@ def redact(ctx):
Namespace-per-tenant
Use db.namespace("tenant-id") to create a lightweight handle bound to one tenant. The same
document ID can exist in multiple namespaces because the namespace is part of the storage key.
End-to-end multi-tenant RAG
A typical RAG application maps the authenticated tenant to a namespace, retrieves context from that namespace, and passes only that context to the LLM.
-""" + code("""tenant = db.namespace(tenant_id) +""" + + code("""tenant = db.namespace(tenant_id) hits = tenant.search(user_query, top_k=5) context = "\\n\\n".join(hit.text for hit in hits) @@ -535,37 +615,47 @@ def redact(ctx): answer = llm.generate( f"Answer using only the following context:\\n{context}\\n\\nQuestion: {user_query}" ) -""") + """ +""") + + """The complete runnable recipe is available in
examples/multi_tenant_rag.py. It demonstrates two tenants using the same index, including identical
document IDs with tenant-specific content.
Runnable example
-""" + code("""pip install "dynavec[sentence-transformers]" +""" + + code("""pip install "dynavec[sentence-transformers]" python examples/multi_tenant_rag.py -""") + """ +""") + + """search_stream() is a generator: it yields one hit at a time as S3 Vectors paginates, so an agent can start
consuming the first results before the full set returns. Amazon S3 Vectors returns at most 100 vectors per response page;
dynavec follows nextToken up to the service limit of 10,000 results.
page_size (or DynavecConfig(top_k_page_size=50)) only changes how many hits are hydrated from DynamoDB per batch. It does not change the S3 Vectors page size (fixed at 100) or time-to-first-result.
Attach a cache and repeated queries are served without hitting S3 Vectors. Three backends:
-""" + code("""from dynavec import Dynavec, SemanticCache, DynamoDBCache, RedisCache +""" + + code("""from dynavec import Dynavec, SemanticCache, DynamoDBCache, RedisCache # 1) in-process semantic cache — also serves near-duplicate queries db = Dynavec(cfg, embedder=emb, cache=SemanticCache(threshold=0.97)) @@ -579,7 +669,8 @@ def redact(ctx): # 3) sub-millisecond shared cache on Redis / AWS ElastiCache db = Dynavec(cfg, embedder=emb, cache=RedisCache("redis://my-elasticache:6379/0")) -""") + """ +""") + + """| Backend | Best for |
|---|---|
SemanticCache | single process; tolerant of near-duplicate hits; zero infra |
RedisCache | many workers/hosts; lowest latency; AWS ElastiCache |
Force a fresh search per call with db.search(..., use_cache=False).
Alongside the vector index, dynavec keeps a lightweight entity-relationship graph in DynamoDB. Entities link to documents; you can traverse the graph first (cheap key lookups) to gather a candidate set, then rank only those against the query embedding. That is the DynamoDB → S3 Vectors reference join.
-""" + code("""# build the graph +""" + + code("""# build the graph db.graph_add_edge("acme", "competes_with", "globex", namespace="kb") db.graph_link("acme", ["doc-1", "doc-2"], namespace="kb") @@ -607,27 +701,32 @@ def redact(ctx): top_k=10, namespace="kb", ) -""") + """ +""") + + """Traversal helpers: graph_add_node, graph_add_edge, graph_link,
graph_neighbors.
Removing nodes and edges
Both deletes are idempotent — removing something that is already gone returns 0 — and both
return the number of edges removed.
graph_delete_node leaves linked documents and their embeddings in place; delete those with
db.delete(...) if you want them gone. Nothing indexes inbound edges, so finding them scans the
namespace (dynamodb:Scan) — fine for occasional cleanup, not for a hot path. Edge removal is a
conditional write that retries if another writer changes the adjacency list concurrently.
Amazon S3 Vectors is cheap and serverless, but it is an object-backed ANN: its per-query @@ -643,7 +742,8 @@ def redact(ctx): ever make queries faster, never wrong.
Enable it
-""" + code("""from dynavec import Dynavec, DynavecConfig +""" + + code("""from dynavec import Dynavec, DynavecConfig cfg = DynavecConfig( vector_bucket="my-vectors", index="docs", table="dynavec_docs", @@ -655,7 +755,8 @@ def redact(ctx): db.warm(namespace="default") # load from S3 Vectors -> RAM (authoritative) hits = db.search("query", top_k=5) # served from memory: no S3, no DynamoDB -print(db.hot_stats()) # {'authoritative_namespaces': ['default'], ...}""") + """ +print(db.hot_stats()) # {'authoritative_namespaces': ['default'], ...}""") + + """How it works
- warm(namespace) scans the namespace from S3 Vectors, hydrates text from
@@ -671,15 +772,18 @@ def redact(ctx):
This is how dynavec approaches Pinecone's latency without an always-on RAM cluster: keep only the hot set in memory, and let cold/bulk data stay on cheap S3 Vectors.-""") +""", +) -PAGES["quantization"] = ("Product quantization", +PAGES["quantization"] = ( + "Product quantization", "Compress cached vectors up to 32× with asymmetric distance.", """
S3 Vectors stores float32 and manages its own layout, so PQ does not change what it stores. PQ compresses the vectors dynavec caches — the in-memory hot tier and local candidate caches — turning a
-""" + code("""from dynavec import ProductQuantizer +""" + + code("""from dynavec import ProductQuantizer pq = ProductQuantizer(m=96, nbits=8).fit(training_vectors) # 768-d -> 96 bytes (32x) codes = pq.encode(vectors) # uint8 codes @@ -689,21 +793,25 @@ def redact(ctx): # Persist and reload codebooks across restarts pq.save("pq_model.npz") loaded_pq = ProductQuantizer.load("pq_model.npz") -""") + """ +""") + + """dim × 4byte vector intombytes.
-""") +""", +) -PAGES["concurrency"] = ("Concurrency", +PAGES["concurrency"] = ( + "Concurrency", "GIL-aware thread pool for I/O-bound AWS calls.", """Param Meaning mNumber of subspaces; must divide the vector dimension. nbitsBits per subquantizer (8 → 256 centroids, uint8 codes). dynavec's workload is I/O-bound (network calls to AWS), and Python releases the GIL during those calls — so a thread pool gives real parallelism without an async rewrite. Batched writes fan out across threads, and
-""" + code("""# many queries at once +""" + + code("""# many queries at once results = db.search_many(["q1", "q2", "q3"], top_k=5, namespace="kb") # tune the pool @@ -712,17 +820,21 @@ def redact(ctx): # clean up the pool (or use the client as a context manager) with Dynavec(cfg, embedder=emb) as db: ... -""") + """ +""") + + """search_manyruns several queries concurrently.A native asyncio client (-""") +""", +) -PAGES["credentials"] = ("Credentials & IAM", +PAGES["credentials"] = ( + "Credentials & IAM", "Connect to your account, with least-privilege permissions.", """aioboto3) is on the roadmap for very high concurrency.dynavec uses the standard boto3 credential chain, so exported env vars just work. You can also pass keys explicitly or assume a cross-account role.
-""" + code("""from dynavec import Dynavec, AWSCredentials +""" + + code("""from dynavec import Dynavec, AWSCredentials # explicit keys / profile / cross-account role creds = AWSCredentials( @@ -733,7 +845,8 @@ def redact(ctx): # assume_role_arn="arn:aws:iam::OTHER_ACCOUNT:role/dynavec", ) db = Dynavec(cfg, credentials=creds) -""") + """ +""") + + """Step-by-step: create the IAM user & keys
- AWS Console → IAM → Users → Create user. Name it
dynavec(programmatic access only — no console sign-in needed).
@@ -742,13 +855,17 @@ def redact(ctx):
- Open the user → Security credentials → Create access key → Application running outside AWS. Copy the access key id and secret (shown once).
- Put them in a
.envfile (below), then run any example.
Seeing red ARN errors in the JSON editor? Check the region spelling in the DynamoDB ARNs — it must be a real region such asap-south-1. A typo likeap-soute-1makes the ARN invalid and shows two errors. Thes3vectorsblock uses"*", so it is not affected.Your .env
-""" + code(ENV_SAMPLE) + """ +""" + + code(ENV_SAMPLE) + + """Load it before running —
set -a && . ./.env && set +a— or usepython-dotenv. dynavec then picks up the credentials automatically.Least-privilege IAM policy
@@ -763,40 +880,51 @@ def redact(ctx):Never commit secrets. Use-""") +""", +) -PAGES["integrations"] = ("Framework integrations", +PAGES["integrations"] = ( + "Framework integrations", "LangChain, LlamaIndex, and a tool for any agent framework.", """.env(gitignored) locally, GitHub Secrets in CI, and prefer an IAM role over long-lived keys in production.LangChain
-""" + code("""from dynavec.integrations.langchain import DynavecVectorStore +""" + + code("""from dynavec.integrations.langchain import DynavecVectorStore store = DynavecVectorStore(db, namespace="kb") retriever = store.as_retriever(search_kwargs={"k": 4}) -""") + """ +""") + + """LlamaIndex
-""" + code("""from dynavec.integrations.llamaindex import DynavecLlamaStore +""" + + code("""from dynavec.integrations.llamaindex import DynavecLlamaStore from llama_index.core import VectorStoreIndex, StorageContext store = DynavecLlamaStore(db, namespace="kb") ctx = StorageContext.from_defaults(vector_store=store) index = VectorStoreIndex.from_documents(docs, storage_context=ctx) -""") + """ +""") + + """LangGraph / CrewAI / Strands
A framework-agnostic retriever tool — just a callable that takes a query and returns text.
-""" + code("""from dynavec.integrations.tools import make_retriever_fn +""" + + code("""from dynavec.integrations.tools import make_retriever_fn retrieve = make_retriever_fn(db, top_k=4) # fn(query: str) -> str # also: as_langchain_tool(db), as_crewai_tool(db) -""") + """ +""") + + """FastMCP server (Claude Desktop, Cursor, AI agents)
Expose dynavec as an MCP server with
-""" + code("""# Install with MCP extra +""" + + code("""# Install with MCP extra pip install "dynavec[mcp]" # Launch the FastMCP server via CLI dynavec mcp -""") + """ +""") + + """dynavec_searchanddynavec_graph_searchtools. Configure via environment variables and launch over stdio:Add to your Claude Desktop / Cursor configuration (
-""" + code("""{ +""" + + code("""{ "mcpServers": { "dynavec": { "command": "uvx", @@ -813,20 +941,25 @@ def redact(ctx): } } } -""") + """ +""") + + """claude_desktop_config.json):Programmatic initialization is also supported:
-""" + code("""from dynavec.mcp import create_mcp_server +""" + + code("""from dynavec.mcp import create_mcp_server mcp = create_mcp_server(db) mcp.run(transport="stdio") -""")) +"""), +) -PAGES["benchmarking"] = ("Benchmarking", +PAGES["benchmarking"] = ( + "Benchmarking", "Recall, latency, and cost — with tables and charts.", """The suite measures recall@k and latency against a labeled dataset and models cost versus Pinecone, OpenSearch, Qdrant, Weaviate, and Milvus across dimensions and scale.
-""" + code("""pip install "dynavec[benchmark]" +""" + + code("""pip install "dynavec[benchmark]" # recall + latency (local control, or real AWS) python -m benchmarks.run_benchmark --backend local --n 50000 --dim 384 @@ -835,17 +968,22 @@ def redact(ctx): # cost comparison + charts (dimensions 384-3072, 100K -> 1B vectors) python -m benchmarks.report --qpm 1_000_000 -""") + """ +""") + + """Cost figures are cost-model estimates from public list prices. Competitor recall/latency are representative until you run the live benchmark against your own account.-""") +""", +) -PAGES["release-notes"] = ("Release notes", +PAGES["release-notes"] = ( + "Release notes", "What changed in each version of dynavec, newest first.", """dynavec follows semantic versioning. Upgrade with:
-""" + code("""pip install --upgrade dynavec -uv pip install --upgrade dynavec""") + """ +""" + + code("""pip install --upgrade dynavec +uv pip install --upgrade dynavec""") + + """The full machine-readable history lives in CHANGELOG.md, and every version is a @@ -977,10 +1115,12 @@ def redact(ctx):
Initial public release: the hybrid Amazon DynamoDB + Amazon S3 Vectors store, pluggable embedders, namespace RAG, product quantization, RRF fusion, MMR rerank, the GraphRAG layer, caching backends, framework adapters, and one-shot provisioning.
-""") +""", +) -PAGES["dashboard"] = ("Telemetry dashboard", +PAGES["dashboard"] = ( + "Telemetry dashboard", "A native, in-your-brand observability dashboard — a Langfuse-style view of real query telemetry.", """Attach a recorder to your client and every search is captured with latency, cache outcome, @@ -988,19 +1128,23 @@ def redact(ctx):
Live interactive preview: codeforstartups.github.io/dynavec/dashboard (landing-page theme).1. Expose real telemetry
Attach a recorder to your client and serve the API:
-""" + code("""from dynavec import Dynavec, DynavecConfig, SemanticCache +""" + + code("""from dynavec import Dynavec, DynavecConfig, SemanticCache from dynavec.telemetry import TelemetryRecorder from dynavec.dashboard import serve rec = TelemetryRecorder() db = Dynavec(cfg, embedder=emb, cache=SemanticCache(), telemetry=rec) # ... your app runs searches; the recorder fills automatically ... -serve(rec, port=8779) # JSON API at http://127.0.0.1:8779""") + """ +serve(rec, port=8779) # JSON API at http://127.0.0.1:8779""") + + """2. Run the dashboard
Points at that API; falls back to sample data if unset:
-""" + code("""cd dashboard +""" + + code("""cd dashboard npm install -NEXT_PUBLIC_DYNAVEC_API=http://127.0.0.1:8779 npm run dev # http://localhost:3000""") + """ +NEXT_PUBLIC_DYNAVEC_API=http://127.0.0.1:8779 npm run dev # http://localhost:3000""") + + """No AWS?
python examples/dashboard_demo.pyruns real searches against in-memory stand-ins and serves the API on:8779for the dashboard to read.Tracing view
@@ -1015,19 +1159,26 @@ def redact(ctx):
Click any row to open a detail drawer with per-call similarity scores, filter state, and error details.
-""") +""", +) + def issue(n: int) -> str: return f'#{n}' -PAGES["ecosystem"] = ("Ecosystem overview", +PAGES["ecosystem"] = ( + "Ecosystem overview", "Four projects that together cover remembering, running, observing and measuring an AI application.", """dynavec started as a vector database, and it's growing into a full agent stack that runs inside your own cloud account. The plan has four parts. Each one answers a question about an AI application: what does it know, what does it do, what happened when it ran, and how good were the results?
-This page follows the ecosystem epics (""" + issue(273) + "–" + issue(276) + """). +This page follows the ecosystem epics (""" + + issue(273) + + "–" + + issue(276) + + """). It's a living plan: the order is a proposal rather than a fixed schedule, and it will change as work lands.The four projects
@@ -1040,17 +1191,25 @@ def issue(n: int) -> str:dynaflow Build & run An orchestration engine for agents (nodes, edges, shared state, branches, loops, retries) with a visual builder where the code and the canvas describe the same graph. -In progress: chat models are available (""" + issue(285) + """), the engine is next. - Epic """ + issue(273) + """ In progress: chat models are available (""" + + issue(285) + + """), the engine is next. + Epic """ + + issue(273) + + """ dynalogs Observe Traces for each step of a run, structured logs with secrets removed, searchable run history and a metrics dashboard, all stored in your own account. -Early version: the telemetry dashboard. Epic """ + issue(274) + """ Early version: the telemetry dashboard. Epic """ + + issue(274) + + """ dynaevals Measure & improve Retrieval metrics, LLM-judged answer quality, test datasets, regression runs and CI checks that fail when quality drops. Partly available: retrieval metrics, faithfulness and answer relevance, trend tracking. - Epic """ + issue(275) + """ How they fit together
@@ -1064,7 +1223,8 @@ def issue(n: int) -> str: CI build when a score goes down.- What the scores tell you goes back into the agent: its prompts, its steps and its retrieval settings.
-""" + code(""" dynaflow --- retrieve / remember --> dynavec +""" + + code(""" dynaflow --- retrieve / remember --> dynavec (build & run) (remember) | | traces, logs @@ -1072,36 +1232,42 @@ def issue(n: int) -> str: dynalogs --- runs, traces -------> dynaevals (observe) (measure & improve) ^ | - +------- improve the agent ----------+""") + """ + +------- improve the agent ----------+""") + + """What you can use today
Some of the newer pieces have already landed in the
dynavecpackage.Chat models (dynaflow)
One interface for OpenAI, Anthropic and Amazon Bedrock. With Bedrock, the model calls stay in your AWS account like the rest of dynavec.
-""" + code("""from dynavec.chat import BedrockChatModel, Message +""" + + code("""from dynavec.chat import BedrockChatModel, Message model = BedrockChatModel(region_name="us-east-1") # or OpenAIChatModel() result = model.invoke([ Message(role="system", content="Answer in one sentence."), Message(role="user", content="What is a vector database?"), ]) -print(result.message.content)""") + """ +print(result.message.content)""") + + """Every model also has
stream(),ainvoke()andastream(), and acceptstools=for function calling.Evaluation (dynaevals)
Check how well search finds the documents you expect:
-""" + code("""from dynavec.eval import compute_mrr, compute_ndcg_at_k, compute_recall_at_k +""" + + code("""from dynavec.eval import compute_mrr, compute_ndcg_at_k, compute_recall_at_k retrieved = ["d3", "d1", "d7", "d2"] # ids returned by search, best first relevant = {"d1", "d2"} # ids you know are correct compute_recall_at_k(retrieved, relevant, k=3) # 0.5 compute_mrr(retrieved, relevant) # 0.5 -compute_ndcg_at_k(retrieved, relevant, k=3) # 0.3869""") + """ +compute_ndcg_at_k(retrieved, relevant, k=3) # 0.3869""") + + """And use an LLM as a judge to check whether an answer sticks to the retrieved context and actually answers the question:
-""" + code("""from dynavec.eval import OpenAIJudge, evaluate_rag +""" + + code("""from dynavec.eval import OpenAIJudge, evaluate_rag result = evaluate_rag( query="What powers the cell?", @@ -1109,7 +1275,8 @@ def issue(n: int) -> str: answer="The mitochondria.", judge=OpenAIJudge(model="gpt-4o-mini"), # or BedrockJudge, GeminiJudge, CustomJudge ) -print(result.faithfulness.score, result.answer_relevance.score)""") + """ +print(result.faithfulness.score, result.answer_relevance.score)""") + + """Telemetry (dynalogs)
Attach a
@@ -1121,32 +1288,65 @@ def issue(n: int) -> str:TelemetryRecorderto your client to capture latency, cache hits and scores for every search, then view them in the telemetry dashboard.Engine core The graph and state runtime, branches, loops and parallel steps, retries, saving run state to DynamoDB, and snapshots for resume and replay -""" + issue(277) + "–" + issue(281) + """ """ + + issue(277) + + "–" + + issue(281) + + """ Nodes and models A typed node schema, built-in and custom nodes, chat models (done), prompt templates and output parsers -""" + issue(282) + "–" + issue(286) + """ """ + + issue(282) + + "–" + + issue(286) + + """ Agents A tool registry with MCP connectors, a tool-calling loop and planner, multi-agent handoffs and conversation memory -""" + issue(287) + "–" + issue(290) + """ """ + + issue(287) + + "–" + + issue(290) + + """ Visual builder A drag-and-drop canvas, converting between code and canvas, watching runs live, stepping through a run, and a CLI -""" + issue(291) + "–" + issue(295) + """ """ + + issue(291) + + "–" + + issue(295) + + """ Observability Traces per step, structured logs, run history and run metrics -""" + issue(299) + "–" + issue(302) + """ """ + + issue(299) + + "–" + + issue(302) + + """ Evaluation More RAG metrics, test datasets, regression runs with CI checks, and scores shown next to traces -""" + issue(303) + "–" + issue(306) + """ """ + + issue(303) + + "–" + + issue(306) + + """ Production and multi-cloud Pausing for human approval, long-running workflows, one-command serverless deploy, and GCP and Azure backends -""" + issue(296) + "–" + issue(298) + ", " + issue(307) + "–" + issue(308) + """ """ + + issue(296) + + "–" + + issue(298) + + ", " + + issue(307) + + "–" + + issue(308) + + """ Want to help? Pick an unassigned issue, comment on it to get assigned, and follow CONTRIBUTING.md.
-""") +""", +) def render(slug: str) -> str: @@ -1154,7 +1354,9 @@ def render(slug: str) -> str: # sidebar side = ['', ' - AWS Console → IAM → Users → Create user. Name it