LangChain Upgrade — Current State and Next Steps

Last Updated: 2026-02-17
Builds on: README.md (all phases 1.1–3.2 complete)
Purpose: Snapshot of where things stand and an actionable plan so building from here is easier.

1. Where We Stand Now

All items in the LangChain Upgrade roadmap are done:

Phase	What’s in place
1.1	LangSmith env and tracing
1.2	RAG: MemoryChunksRetrieverAdapter in context + langchainToolTurn
1.3	Prompts in LangChain (asoSystemPrompt + langchainToolTurn)
2.1	Multi-step agent (createReactAgent) behind `USE_LANGCHAIN_ORCHESTRATOR`
2.1.1	Unified LangChain path + multimodal (images)
2.1.2	File support on LangChain path
2.1.3	Dual transport (One API vs direct provider)
2.2	LangChain memory (AsoDbChatMessageHistory)
3.1	LCEL chain: prompt → model → parser; optional context + toolCallPrompt builder; `buildToolCallPrompt` in aso/promptBuilder.service.ts
3.2	LangGraph: asoResponseGraph (router + respond nodes)

In practice today: The runtime is LangChain-only. aso.service builds toolCallPrompt and calls asoResponseGraph.invoke({ payload: lcArgs }) and uses payload.content and payload.trace.

The LangGraph includes a router:
- cognitiveDepth=single_pass and no attachments → single-pass model call (no agent/tools)
- otherwise → agent/tool loop via asoResponseChain (prompt → agent/tools → parser)
If the LangChain graph/chain fails for any reason, the turn fails (no native/legacy fallback path).

1.1 What’s Live in Production (detail)

Area	Status	Notes
LangChain orchestrator	✅ Fixed and running	On when `USE_LANGCHAIN_ORCHESTRATOR` and `USE_PROVIDER_NATIVE_TOOLS` are true; path does not depend on attachments or cognitive depth (Phase 2.1.1). Was failing due to wrong `BaseChatMessageHistory` import; fixed to use `@langchain/core/chat_history` so the path runs and tools (e.g. web search) are invoked.
ASO response path	✅ LangGraph router	`aso.service` calls `asoResponseGraph.invoke({ payload: lcArgs })` and uses `payload.content` + `payload.trace`. Router can fast-path `single_pass` (no agent/tools).
Agent + tools	✅ Working	createReactAgent loop; tools (including web search) invoked; `AsoDbChatMessageHistory` loads history from DB.

Entry point: backend/src/services/aso.service.ts — condition for LangChain vs native vs self-monitoring (see README “When the LangChain Orchestrator Runs”).

1.2 Implemented but Not Wired

Piece	Location	How to use
Full chain (context + prompt build)	`asoResponseChainWithContext` in `chains/`	Invoke with `AsoChainInputWithContextStep` (no pre-built `toolCallPrompt`); context and toolCallPrompt built inside the chain.
Prompt builder service	`backend/src/services/aso/promptBuilder.service.ts`	`buildToolCallPrompt()` already used by `aso.service`; also usable by `asoToolCallPromptBuilderRunnable` or other callers.

aso.service does not call asoResponseChainWithContext yet; context + toolCallPrompt building still happens outside the chain.

1.3 Quick Reference

Chains: backend/src/services/langchain/chains/ — asoResponseChain, asoResponseChainWithContext, runnables (context, toolCallPromptBuilder, prompt, model, parser).
Graph: backend/src/services/langchain/graph/ — asoResponseGraph (router + respond nodes; includes single-pass fast lane).
Memory: backend/src/services/langchain/memory/asoDbChatMessageHistory.ts — LangChain chat history backed by ASO Memory; BaseChatMessageHistory from @langchain/core/chat_history.
File/code map: See README “File and Code Reference”.

2. Suggested Next Steps (Prioritised)

Use this as a plan; tick items as you go.

2.1 Stabilise and Observe

[ ] Run under load and confirm behaviour and latency.
[ ] Use LangSmith (set LANGCHAIN_TRACING_V2, LANGCHAIN_API_KEY) to inspect traces and tool usage.
[ ] Add or run tests that hit the LangChain path (e.g. asoResponseChain.invoke(...) with minimal lcArgs, and optionally the graph).
[ ] Run regression smoke test (schema + multimodal + routing):\n+ - node -r ts-node/register backend/tests/langchain-regressions.smoketest.ts

2.2 Optional: Use Full Chain in Production

[ ] Option A — Full chain: In aso.service, call asoResponseChainWithContext.invoke(extendedState) with AsoChainInputWithContextStep (include context params; omit toolCallPrompt) so context and prompt building run inside the chain.

2.3 Extend the Graph (When Needed)

[x] Conditional edges: single_pass vs agent/tool loop (already implemented).
[ ] More routing (e.g. “attachments present”, “web-search allowed”, “deep” vs “multi_stage”).
[ ] Extra nodes (e.g. context, post-process, human-in-the-loop) in backend/src/services/langchain/graph/asoResponseGraph.ts.

2.4 Deprecate Native Path

[x] Removed the native/legacy tool-call paths in aso.service and updated flags/docs for the core LangChain upgrade docs.

2.5 Keep Docs in Sync

[ ] Update README “Current Status” and “LangChain Capabilities” tables so they match reality (chains, agents, memory, LangGraph in use where applicable).
[ ] Update this doc when you complete or add next steps.

2.6 Future Roadmap

[ ] Streaming from the chain or graph if the UI needs it.
[ ] Evals / datasets in LangSmith for quality and regressions.
[ ] New subgraphs or chains (e.g. specialised flows); document in README or a “Post–Phase 3” section.

3. One-Page Checklist (Copy and Use)

LANGCHAIN — CURRENT STATE & NEXT STEPS (from CURRENT-STATE-AND-NEXT-STEPS.md)

WHERE WE ARE
  [x] All phases 1.1–3.2 done (see README).
  [x] LangChain path runs when USE_LANGCHAIN_ORCHESTRATOR and USE_PROVIDER_NATIVE_TOOLS are true (path not gated by attachments or depth).
  [x] asoResponseChain used in aso.service; tools (e.g. web search) working.
  [x] BaseChatMessageHistory import fixed (chat_history).
  [x] README “Current Status” and “LangChain Capabilities” updated to match code.

NEXT (pick what you need)
  [ ] Stabilise: load test, LangSmith, tests for chain/graph.
  [ ] Optional: wire asoResponseChainWithContext in aso.service.
  [ ] Extend graph: conditional edges, more nodes.
  [ ] Deprecate native path when ready.
  [ ] Update README + this doc.
  [ ] Future: streaming, evals, new chains/subgraphs.

README.md — Full phase-by-phase guide, env vars, file reference.
Memory System, Prompt System, Tool System.
06-ARCHITECTURE/Data-Flow.

Explanation

How To

Reference

Tutorials

Explanation

How To

Previous Docs

Reference

Explanation

How To

Reference

Tutorials

LangChain Upgrade — Current State and Next Steps

1. Where We Stand Now

1.1 What’s Live in Production (detail)

1.2 Implemented but Not Wired

1.3 Quick Reference

2. Suggested Next Steps (Prioritised)

2.1 Stabilise and Observe

2.2 Optional: Use Full Chain in Production

2.3 Extend the Graph (When Needed)

2.4 Deprecate Native Path

2.5 Keep Docs in Sync

2.6 Future Roadmap

3. One-Page Checklist (Copy and Use)

LangChain Upgrade — Current State and Next Steps ​

1. Where We Stand Now ​

1.1 What’s Live in Production (detail) ​

1.2 Implemented but Not Wired ​

1.3 Quick Reference ​

2. Suggested Next Steps (Prioritised) ​

2.1 Stabilise and Observe ​

2.2 Optional: Use Full Chain in Production ​

2.3 Extend the Graph (When Needed) ​

2.4 Deprecate Native Path ​

2.5 Keep Docs in Sync ​

2.6 Future Roadmap ​

3. One-Page Checklist (Copy and Use) ​

4. Related Docs ​

LangChain Upgrade — Current State and Next Steps

1. Where We Stand Now

1.1 What’s Live in Production (detail)

1.2 Implemented but Not Wired

1.3 Quick Reference

2. Suggested Next Steps (Prioritised)

2.1 Stabilise and Observe

2.2 Optional: Use Full Chain in Production

2.3 Extend the Graph (When Needed)

2.4 Deprecate Native Path

2.5 Keep Docs in Sync

2.6 Future Roadmap

3. One-Page Checklist (Copy and Use)

4. Related Docs