Integrations

Needlepath ships a client for Python and TypeScript, and three framework adapters. Every one of them is Apache-2.0 and fails open: if the service is slow, down, or stands down, your original context goes through unchanged. The snippets on this page pin np-2026-08-r4, the newest published label. If you already run an older label, evaluate before switching.

Package	Language	Seam
`needlepath`	Python	the core client: HTTP only, no required dependencies
`@nextmoca/needlepath-sdk`	TypeScript	the core client: zero runtime dependencies
`needlepath-langchain`	Python	LangChain `AgentMiddleware`, plus the LangGraph recipe
`needlepath-litellm`	Python	LiteLLM proxy `CustomGuardrail`
`llama-index-postprocessor-needlepath`	Python	LlamaIndex `BaseNodePostprocessor`

The core client

from needlepath import NeedlepathClient, ContextRecord, TaskSpec

client = NeedlepathClient(
    api_key="np_live_...",            # or NEEDLEPATH_API_KEY
    operating_point="np-2026-08-r4",  # required, and pinned here not per call
)

result = client.select(
    records=[
        ContextRecord(text=tool_output, kind="tool_result", id="lookup-1"),
        ContextRecord(text=doc, kind="external_data", id="doc-7", title="SOP"),
    ],
    task=TaskSpec(prompt="what is the invoice total for A-1002?"),
    max_context_tokens=4000,
)

context = result.rendered_context if result.applied else my_original_context

import { NeedlepathClient } from "@nextmoca/needlepath-sdk";

const client = new NeedlepathClient({
  apiKey: "np_live_...",            // or NEEDLEPATH_API_KEY
  operatingPoint: "np-2026-08-r4",  // required, and pinned here not per call
});

const result = await client.select({
  records: [
    { text: toolOutput, kind: "tool_result", id: "lookup-1" },
    { text: doc, kind: "external_data", id: "doc-7", title: "SOP" },
  ],
  task: { prompt: "what is the invoice total for A-1002?" },
  maxContextTokens: 4000,
});

const context = result.applied
  ? result.response!.renderedContext
  : myOriginalContext;

select() never raises, and never rejects. Read result.applied; when it is false, use your original context. That is the whole integration contract, and it is why the error taxonomy in Errors is something you read when you are curious rather than something you branch on. Python is 3.9+ and installs no dependencies: the default transport is stdlib urllib, so adding the client cannot move a version you already pinned. pip install "needlepath[httpx]" adds an httpx-backed async transport, and AsyncNeedlepathClient has identical semantics either way. The TypeScript client runs on Node ≥ 20.19, Cloudflare workerd and Vercel’s Edge Runtime, and ships dual ESM + CJS.

Framework adapters

LangChain
LiteLLM
LlamaIndex

pip install needlepath-langchain

from langchain.agents import create_agent
from needlepath_langchain import NeedlepathMiddleware

agent = create_agent(
    model,
    tools,
    middleware=[NeedlepathMiddleware(operating_point="np-2026-08-r4")],
)

Two seams, and they engage on different problems. wrap_tool_call catches a single oversized tool result on the way into the message list: a tool returns 40 KB of JSON and what lands is the part answering the current step. It engages only above tool_result_max_tokens (default 2000); below that no call is made and nothing is touched.wrap_model_call selects over the tool results already accumulated in history, against the current task, and engages above history_max_tokens (default 8000). A result that mattered three steps ago and does not now collapses to a placeholder.

pip install needlepath-litellm

# config.yaml
guardrails:
  - guardrail_name: "needlepath"
    litellm_params:
      guardrail: needlepath_litellm.NeedlepathGuardrail
      mode: "pre_call"
      default_on: true
      operating_point: "np-2026-08-r4"
      history_max_tokens: 8000
      preserve_recent: 2

A proxy-level guardrail, so every client behind the proxy gets selection with no client-side change at all. Set NEEDLEPATH_API_KEY in the proxy’s environment rather than api_key: in the config, which would put a secret in a file you commit.

pip install llama-index-postprocessor-needlepath

from llama_index.postprocessor.needlepath import NeedlepathPostprocessor

query_engine = index.as_query_engine(
    node_postprocessors=[NeedlepathPostprocessor(operating_point="np-2026-08-r4")],
)

This is the weakest of the use cases, and we would rather say so. A retrieval postprocessor never sees tool outputs, and retrieved chunks are already short and already ranked. It exists because LlamaIndex is where many developers already have a postprocessor slot. If you have an agent with tool calls, start there instead.

Writing it yourself

If you are not on Python or TypeScript, the integration surface is the HTTP contract and it is smaller than it looks. It is three things: map your messages to records, call the endpoint, and fail open.

KIND_BY_ROLE = {
    "user": "user_input",
    "assistant": "llm_response",
    "tool": "tool_result",
    "system": "external_data",
}


def to_records(messages):
    return [
        {
            "id": m.get("id") or f"msg-{i}",
            "kind": KIND_BY_ROLE.get(m["role"], "external_data"),
            "text": m["content"],
            "step_id": m.get("step_id"),
        }
        for i, m in enumerate(messages)
    ]


def select(messages, prompt, *, budget=8000, keep=()):
    """Returns the message subset to send, or the original list on any failure.

    `keep` is the set of messages that must survive: the system prompt, the
    current user turn. They are held back from selection entirely rather than
    sent with a pin, because nothing in the request pins a record today.
    """
    keep_set = set(keep)
    candidates = [m for m in messages if id(m) not in {id(k) for k in keep_set}]
    if not candidates:
        return messages

    try:
        response = requests.post(
            f"https://{HOST}/v1/context/select",
            headers={"Authorization": f"Bearer {API_KEY}",
                     "content-type": "application/json"},
            json={
                "request_id": new_request_id(),
                "records": to_records(candidates),
                "task": {"prompt": prompt},
                "budget": {"max_context_tokens": budget,
                           "operating_point": "np-2026-08-r4"},
                "return_per_record": True,
            },
            timeout=10,
        )
        response.raise_for_status()
        result = response.json()
    except Exception:
        return messages                       # fail open

    kept = {s["record_id"] for s in result.get("selected", [])}
    if not kept:
        return messages                       # empty selection is pass-through
    survivors = [m for i, m in enumerate(candidates)
                 if (m.get("id") or f"msg-{i}") in kept]
    # Original order, with the held-back messages back in place.
    return [m for m in messages if m in keep_set or m in survivors]

Three details in there are the whole art of it:

Hold back what must survive. required_record_ids is the field designed to pin a record and it does not pin today. Keeping a message out of records[] is the only guarantee, and it is the right shape anyway: a system prompt does not benefit from being selected.
Supply an id on every record. Without one you get a server-generated id back that joins to nothing on your side, and two identical calls return different ids.
Two pass-through paths: an exception, and an empty selection. Both return the original list. An empty selection returned as a success is a failure mode, not a valid answer.

Keep the message order. The example filters the original list rather than rebuilding from selected[], so ordering is preserved for free. selected[] is in selection order, not conversation order, and reconstructing from it directly will scramble a conversation.

The LangGraph seam

For a LangGraph graph, the seam that composes with a non-destructive selection service is a pre-model hook that changes what the model sees without mutating graph state, the llm_input_messages pattern. Selection is advisory per call, so a later node still has the full state to work from. Deleting messages from state with RemoveMessage also works and is the right tool if you genuinely want them gone, but it is destructive: a stand-down cannot undo it, and a subsequent turn cannot recover a record the engine would have selected next time.

Rules every adapter follows

These are binding on our packages and are the right rules for yours.

Fail open on every error path

Timeout, non-2xx, empty selection: pass the original messages through unmodified and emit a metadata-only warning. At a framework boundary this matters more than anywhere else, because the caller has no way to inspect what happened.

Pin the operating point in the constructor

Not per call, and never left to the server default. Behaviour must not shift under an application that has not changed.

Guard the 6 MB body limit client-side

It is a platform cap enforced before the service is reached, so the error it produces will not be a Needlepath error shape. Check before sending.

Depend only on public, documented framework symbols

And cap the framework at a major version. Reaching into a framework’s internals buys a feature now and an outage on its next minor release.

Choosing between us and what your framework already ships

Several frameworks now include some form of context trimming in-tree and free: LangChain, for example, ships middleware that clears tool results once a token threshold is crossed. A developer evaluating Needlepath usually already has that installed, so the honest comparison is not “can something prune tool results”. It is three narrower questions:

Question	In-tree trimming	Needlepath
What happens to the content?	Typically cleared or replaced with a placeholder	Selected, not rewritten: a kept record’s excerpt is built from its own content, never paraphrased into new prose (with a stated exception)
What triggers it?	A token threshold	A judgement about whether trimming would pay on this request
What happens when trimming would not help?	It trims anyway; the threshold is the only input	It stands down and returns your context intact
What do you learn?	That something was removed	Which records, with a score and a reason, plus the token arithmetic

If your problem is “the context window overflows and I need it to stop”, a threshold-based trimmer in your framework is a genuinely reasonable answer and it costs nothing. Reach for Needlepath when which records survive is the part that matters.

Try it on your own traffic first

Run selection alongside your existing prompts, record what would have been dropped, and change nothing until you have looked.

Get started

Release notes

How selection works

Running it in production

Billing

Integrations

The core client

Framework adapters

Writing it yourself

The LangGraph seam

Rules every adapter follows

Choosing between us and what your framework already ships

Try it on your own traffic first

​The core client

​Framework adapters

​Writing it yourself

​The LangGraph seam

​Rules every adapter follows

​Choosing between us and what your framework already ships

Try it on your own traffic first

The core client

Framework adapters

Writing it yourself

The LangGraph seam

Rules every adapter follows

Choosing between us and what your framework already ships