Roadmap: Client SDKs and Developer Experience

Gap Statement: Three Good Protocols, Zero Client Libraries

Wikantik exposes a robust set of REST APIs (/api/bundle, /api/briefing, /api/changes), two Model Context Protocol (MCP) servers, and an OpenAPI 3.1 tool surface. However, it currently ships absolutely no client SDK, no framework adapters, no quickstart templates, and no hosted playground. In the fast-paced ecosystem of 2026, a Retrieval-Augmented Generation (RAG) platform's discoverability and traction run almost exclusively through the major agent-framework ecosystems. Developers adopt the solutions that drop into their existing LangChain, LlamaIndex, or Semantic Kernel codebases with minimal integration effort.

The retriever adapter is the genuine quick win here. Building an adapter takes a fraction of the time compared to overhauling a platform, yet it yields immediate discoverability. However, the full developer-experience (DX) program—comprising two native SDKs, seamless key management, and a dedicated, interactive documentation site—is a substantial, multi-session effort. It is imperative not to conflate the quick win of an adapter with the long-term investment in a holistic developer ecosystem.

The Economics and Strategic Value of SDKs

Investing in a first-class developer experience is not merely a technical luxury; it is a fundamental economic driver for platform adoption. When an engineering team evaluates a RAG solution, the integration overhead often dictates the purchasing decision. A platform lacking native SDKs forces developers to write boilerplate API clients, handle pagination, manage connection pooling, and implement retry logic. This friction translates to direct labor costs.

For a mid-sized enterprise, implementing a custom integration against raw REST endpoints can easily consume two weeks of senior engineering time, costing roughly $10K to $15K in fully loaded labor. Scaled across a target market of thousands of potential customers, the cumulative friction is massive. In contrast, if the platform vendor invests roughly $150K to build, document, and maintain high-quality SDKs and adapters, they can eliminate this friction entirely. Removing the $15K integration tax accelerates the sales cycle, reduces time-to-value, and dramatically lowers the barrier to entry. Companies that have prioritized DX often see their customer acquisition cost (CAC) drop significantly, enabling them to reallocate budgets that might otherwise be spent on direct sales (often running well over $2.5M annually) into further product development.

Market Grounding and Competitor Ecosystem

To understand the urgency of this roadmap, we must look at the current market dynamics:

Bedrock Knowledge Bases: Amazon integrates natively with LangChain, CrewAI, LlamaIndex, and Strands Agents. Crucially, it is discoverable as an MCP tool via AgentCore Gateway without any custom code. This ubiquity makes Bedrock a default choice for teams already within the AWS ecosystem.
LlamaIndex and LlamaCloud: This ecosystem pairs over 160 connectors with enterprise deployment options, including private VPCs, Role-Based Access Control (RBAC), and Single Sign-On (SSO). The framework ecosystem acts as both a distribution channel and a formidable competitor.
The MCP Tailwind: Practitioners are increasingly letting the foundational models drive retrieval natively through the Model Context Protocol rather than wiring up rigid server-side pipelines. Wikantik's MCP servers are already positioned correctly for this architectural shift. However, SDKs remain critical to extend reach to the massive population of legacy and framework-based applications that do not yet speak MCP natively.
Real-World Impact: A notable LinkedIn case study on their MCP-based agent knowledge base reported an approximate 20% lift in AI coding adoption and a staggering 70% reduction in issue triage time. While this is a single-company claim and should be treated as directional motivation rather than an independent benchmark, it underscores the transformative potential of deeply integrated knowledge surfaces.

Current Wikantik State and Architecture

Before executing the roadmap, we must acknowledge the current state of the platform:

API Surfaces:
- GET /api/bundle?q=: Returns ranked, de-duplicated, and version-pinned cited sections, along with a comprehensive coverage block.
- GET /api/briefing: Provides highly budgeted, session-start context to prime an agent's context window.
- /api/changes?since=: An incremental synchronization feed for cache invalidation and mirror updates.
- /wiki/{slug}?format=md|json: Delivers raw page content.
- MCP & Tools: 21-tool knowledge MCP server, 26-tool administrative MCP server, and a comprehensive /tools/* OpenAPI specification for non-MCP clients.
Authentication: The system currently relies on static API keys or bearer tokens (backed by a relational api_keys table) for both MCP and tools surfaces. There is no self-service key management user interface.
Packaging and Documentation: There is no published API versioning or stability contract. The platform lacks a presence on package managers like PyPI or npm. Documentation is scattered across the internal wiki and the GitHub repository, rather than unified in a dedicated developer portal. The primary marketing site (www.wikantik.com) lacks a developer section entirely.

Mathematical Foundations of Retrieval Integration

When we build a retriever adapter for a framework like LangChain, we are bridging the gap between the framework's generalized query representation and Wikantik's specialized search architecture. Wikantik's /api/bundle endpoint leverages a hybrid search mechanism, combining dense vector embeddings with sparse BM25 lexical scoring.

Understanding the mathematics of this retrieval process is crucial for developers who need to tune the alpha parameter that weights these two signals. The final relevance score $S$ for a given document chunk $d$ against a query $q$ is computed as a convex combination of the normalized dense cosine similarity and the normalized sparse BM25 score:

S(q, d) = \alpha \cdot \text{norm}\left( \frac{\mathbf{v}_q \cdot \mathbf{v}_d}{\|\mathbf{v}_q\| \|\mathbf{v}_d\|} \right) + (1 - \alpha) \cdot \text{norm}\left( \sum_{i=1}^{n} IDF(q_i) \cdot \frac{TF(q_i, d) \cdot (k_1 + 1)}{TF(q_i, d) + k_1 \cdot \left(1 - b + b \cdot \frac{|d|}{avgdl}\right)} \right)

Where:

$\mathbf{v}_q$ and $\mathbf{v}_d$ are the dense vector embeddings of the query and document, respectively.
$TF(q_i, d)$ is the term frequency of query term $i$ in document $d$ .
$IDF(q_i)$ is the inverse document frequency of term $i$ .
$|d|$ is the length of the document, and $avgdl$ is the average document length across the corpus.
$k_1$ and $b$ are standard BM25 tunable parameters (typically $k_1 \approx 1.2$ and $b \approx 0.75$ ).

When the LangChain WikantikRetriever invokes the API, it must accurately propagate these tuning parameters if the user specifies them, ensuring that the mathematical rigor of the underlying search engine is exposed through the Python interface.

Proposed Direction and Phased Rollout

To systematically address the DX gap, we will execute the following phased rollout:

Python SDK First (wikantik-client on PyPI): We will build a thin, strictly typed Python client covering the bundle, briefing, changes, and search endpoints. Crucially, this package will include WikantikRetriever adapters for LangChain and LlamaIndex. These adapters will map the rich bundle sections returned by the API into the standard document types expected by these frameworks, ensuring that citation metadata is perfectly preserved. The "no-synthesis" bundle contract is an excellent fit for retriever semantics—frameworks want raw, cited documents, not pre-synthesized answers.
TypeScript Client Second: Once the Python client has proven the architectural model, we will replicate the shape in TypeScript. This will serve the rapidly growing ecosystem of Node.js and Next.js agent applications.
Interactive Quickstarts: We will author a series of "RAG over your wiki in 10 minutes" guides. These will feature a simple docker compose up command, a script to seed test pages, and a retriever snippet using LangChain or LlamaIndex. Additionally, we will provide an MCP-specific quickstart showcasing the assemble_bundle and get_briefing tools as the differentiated, agent-native path.
Self-Service Key Management: We will introduce API-key management into the existing administrative UI, allowing users to create, rotate, and scope their keys. This is an absolute prerequisite for any mature external developer story.
Developer Documentation Portal: We will launch a dedicated developer section on the marketing site. This portal will be generated directly from our OpenAPI specifications and MCP tool registries, guaranteeing that it remains perfectly in sync with the codebase. It will feature a clearly stated API stability and versioning policy.

Phase 1 Scope and Detailed Acceptance Criteria

First Session Scope: The immediate deliverable is a Python package containing a thin wrapper around the /api/bundle client, coupled exclusively with the LangChain retriever adapter. LlamaIndex support, TypeScript clients, the key-management UI, and the dedicated documentation site are explicitly out of scope for Phase 1.

Phase 1 is considered complete when the following criteria are met:

Metadata Preservation: An integration test running against a local Docker deployment must demonstrate that the LangChain retriever returns Document objects whose metadata dictionaries carry canonicalId, version, headingPath, and spanSha256 absolutely intact. A subsequent test must prove that this citation metadata survives a full RetrievalQA-style chain end-to-end. This empirically validates our assumption that the bundle format maps perfectly onto retriever semantics.
Frictionless Quickstart: The README quickstart must execute flawlessly from a pristine virtual environment against a fresh docker compose up instance.
Strict Client-Side Boundary: Zero server-side changes must be required. If the implementation of the adapter attempts to force an API change, development must halt and the issue must be escalated. Modifying the API to accommodate an adapter is an [OWNER]-level versioning decision, not an implementation detail of the SDK.
Local Build Integrity: The package must build and install locally without errors. Publishing the package to PyPI remains a separate, explicitly [OWNER]-gated step to protect the namespace ownership.

Verification Before Design

We must rigorously verify our assumptions before committing them to the architectural design:

The maxims that "developers adopt what drops in in five lines" and "the bundle maps perfectly onto retriever semantics" are plausible hypotheses, not established facts. Acceptance criterion #1 exists precisely to verify the latter mathematically and programmatically. The former will be tested by the real-world reception of the quickstart.
The LinkedIn CAPT outcome figures (~20% adoption lift, ~70% triage reduction) serve as excellent internal motivation but must never be presented in Wikantik marketing copy as if they were independently measured, universally applicable benchmarks.
We must manually verify the availability of the wikantik-client and wikantik namespaces on PyPI and npm before authoring the setup metadata.

Non-Goals

To maintain focus, the following items are strictly non-goals for this roadmap phase:

No Client-Side Synthesis: The SDK will not perform answer synthesis or include proprietary prompt templates. The SDK's sole responsibility is to return cleanly cited evidence, strictly adhering to the principles outlined in ADR-0001.
No Write-Path Support: There will be no SDK coverage of administrative or write-path MCP surfaces in Phase 1. The focus is entirely on read-path retrieval.
No Premature Generation: We will not attempt to generate the client automatically from OpenAPI until the /api/* endpoints have complete and robust specification coverage. Currently, only the /tools/* spec exists. We will hand-write the thin client first to control the developer experience, and explore code generation only in later phases.

Investigation Starting Points

To kickstart this initiative, the following investigations must be undertaken immediately:

API Contract Audit ([AGENT]): Before publishing any client code, we must audit which response fields of /api/bundle and /api/briefing are contractually stable versus those that are incidental implementation details. This will produce a "freeze list" that the [OWNER] must ratify as part of the formal API-stability contract (e.g., deciding between URL-based vs. Header-based versioning).
LlamaIndex Mapping ([AGENT]): Investigate the mapping of Wikantik bundles to LlamaIndex's NodeWithScore constructs. This will require the same shape of citation-survival testing as the LangChain integration.
Key Scoping Model ([AGENT]): Analyze the requirements for read-only retrieval keys versus full administrative keys. Determine what the existing api_keys schema supports and what migrations are necessary. The [OWNER] must approve the scoping design before any external keys are issued.
SDK Maintenance Cost ([AGENT]): Evaluate the long-term feasibility of generating clients from OpenAPI specifications once coverage is complete, aiming to keep the maintenance burden strictly bounded for a single developer.
Namespace Publishing ([OWNER]): Finalize PyPI and npm namespace ownership decisions and approve the Continuous Integration (CI) publishing pipelines once they are drafted by the [AGENT].