Node.js everyday

AI FluentGraph — Semantic Intelligence Layer for ServiceNow Fluent & LLM Systems

February 15, 2026 · YES PRASAD

Open Source · MIT License · ServiceNow Fluent SDK 4.x.x

Map every table, script, and relationship across your Fluent application. Know the full blast radius of any change — before it reaches production.

FluentGraph is an semantic layer that enables LLMs to safely understand, reason about, and interact with ServiceNow Fluent systems using structured context instead of raw code.

Get Started Free View on GitHub

▶ MCP compatible ⏱ One-command analysis ⚙ Zero configuration ▶ CI/CD compatible

fluent-graph analyze — ITSM Application

$ fluent-graph analyze ── Scanning project artifacts... 📦 DATA SCHEMA ───────────────────────────────────── Table Source File Status x_1566_seventh_account tables/account.ts ✓ active x_1566_seventh_customer tables/customer.ts ✓ active x_1566_seventh_risk_score tables/risk_score.ts ✓ active x_1566_seventh_fraud_alert tables/fraud.ts ✓ active 🔗 SCHEMA RELATIONSHIPS ──────────────────────────── Source Field → Target Table Type account.owner → x_1566_seventh_customer reference fraud_alert.account → x_1566_seventh_account reference critical_account.team → sys_user_group reference ⚙️ LOGIC ATTACHMENTS ────────────────────────────── Artifact Table Trigger State bank_incident_onload incident [onLoad] active cs_incident_onload incident [onLoad] active cs_incident_onchange_caller incident [onChange] active cs_account_onchange_type x_1566_account [onChange] active Auto-close empty Changes change_request [action] review ✓ Analysis complete — 9 tables · 8 relationships · 9 scripts Output written to fluent-graph.json

fluent-graph — dependency graph · ITSM Application

Filter:

Custom table

Platform table

Client script

Business rule

Schema ref

Logic attachment

Click a node to inspect · Blast radius mode reveals change impact

The Problem

Production breaks are preventable

ServiceNow Fluent applications grow quickly. What begins as a handful of clean tables becomes a dense network of scripts, business rules, and cross-references. Without visibility into those connections, every refactor is a gamble.

Scenario A

You delete a field.
Production breaks.

Fourteen client scripts fail. Three business rules throw errors. Two dashboards go blank. You discover the full scope — at runtime, in production.

Error: Field 'caller_id' not found at ClientScript: cs_incident_onload at ClientScript: bank_incident_onload + 12 more...

Scenario B

A new developer joins.
No one knows the app.

Understanding how tables interconnect, which scripts are active, and why certain business rules exist takes days of exploration — time that should be spent shipping features.

Root Cause

ServiceNow Fluent needs a dependency graph

The most critical question before any change: what else does this touch? FluentGraph is that answer — a free, one-command tool that draws a complete map of your project.

Capabilities

Everything your team needs
to ship with confidence

FluentGraph surfaces the architectural intelligence already embedded in your project — structured, queryable, and ready for automated pipelines.

Artifact Lineage

A complete inventory of every table, field, client script, business rule, UI action, and ACL — each mapped to its source file and active state.

Schema Relationships

Every foreign-key reference and table extension within your app, including links to platform tables like sys_user and incident.

Blast Radius Analysis

Run a single command to enumerate every artifact affected if you modify or remove a target table. Know the full impact before the first line changes.

CI/CD Integration

Outputs a machine-readable fluent-graph.json artifact purpose-built for automated pipeline checks. Intercept conflicts before the merge queue.

Logic Attachment Mapping

Associates every onLoad, onChange, and onSubmit script with its owning table, trigger type, and active state — making dormant code visible at a glance.

Rapid Onboarding

New engineers understand the full application architecture in minutes rather than days. The entire dependency graph is a single command away.

Output

Three sections.
Complete visibility.

Run fluent-graph analyze and get a clean, readable report divided into three sections — plus a machine-readable JSON file for your pipelines.

01 — DATA SCHEMA

Your table inventory

A clean list of every custom table alongside its source file and active status.

Table name and scope
Source file location
Active / deleted status
Visibility attributes

02 — SCHEMA RELATIONSHIPS

How your tables talk

Every reference field connection — including links out to platform tables outside your scope.

Source table and field name
Target table (local or platform)
Reference type and direction
Cross-scope dependencies

03 — LOGIC ATTACHMENTS

Every script mapped

Each client script, business rule, and UI action listed with the table it attaches to and its trigger type.

onLoad / onChange / onSubmit
Business rules and script includes
UI actions and ACLs
Active vs inactive state

Blast Radius

Know what breaks
before you deploy

Before renaming, modifying, or removing any table, run one additional command. FluentGraph traverses your entire dependency graph and returns a ranked list of every artifact affected — along with a calculated risk level.

$ fluent-graph blast incident

🔥 Blast Radius — incident LOW RISK

Artifact	Type	Trigger
bank_incident_onload	client_script	onLoad
cs_incident_onload	client_script	onLoad
cs_incident_onchange_caller	client_script	onChange

Total impacted: 3 artifacts · client_script ×3

🔥 Blast Radius — x_1566039_seventh_account MEDIUM RISK

Artifact	Type	Reason
cs_account_onchange_type	client_script	onChange
x_1566_seventh_fraud_alert	field	FK via account
x_1566_seventh_risk_score	field	FK via account
x_1566_seventh_account_ext	field	FK via linked_account

Total impacted: 5 artifacts · client_script ×1 · field ×3

"Running blast radius before a major refactor revealed that deleting a custom field would have broken four client scripts, two business rules, and a UI action — all before a single line was deployed to production." — Eshwar Prasad Yaddanapudi, Creator of FluentGraph

Get Started

Up and running
in under a minute

FluentGraph requires Node.js 18 or later and an initialized ServiceNow Fluent SDK project. No account, no configuration file, no API keys.

Install globally via npm

Install the package once and use it across all your Fluent projects. Or invoke on-demand with npx without a global install.

$npm install -g @yesprasad/fluent-graph

Analyze your Fluent project

Navigate to the root of any Fluent project and run the analysis command. FluentGraph scans your artifact directory and produces a full dependency report in seconds.

$fluent-graph analyze

Run blast radius before any breaking change

Before modifying any table, supply its name as a target. FluentGraph returns the complete list of affected artifacts and a risk-level assessment.

$fluent-graph blast <table_name>

Wire into your CI/CD pipeline

The generated fluent-graph.json integrates with any pipeline. Add the step to your GitHub Actions workflow to block merges that introduce identity conflicts.

CI/CD Integration

Catch conflicts
before the merge

FluentGraph outputs structured JSON designed for automated pipeline consumption. Gate your deployments on dependency integrity without writing a single custom script.

.github/workflows/fluent-check.yml

name: Fluent Dependency Check on: [push, pull_request] jobs: analyze: runs-on: ubuntu-latest steps: # Extract full artifact lineage - name: Run FluentGraph run: npx @yesprasad/fluent-graph analyze # Block merge on identity conflicts - name: Validate dependency graph run: | if grep -q '"action": "CONFLICT"' fluent-graph.json; then echo "Identity conflicts detected" exit 1 fi

✓ Runs in GitHub Actions, GitLab CI, or Jenkins
✓ No authentication or external network calls required
✓ Structured JSON output for custom pipeline logic
✓ Automatically blocks deploys with unresolved identity conflicts
✓ Integrates with existing Fluent SDK toolchain workflows

Open Source · Free Forever

Map your application.
Ship with certainty.

Drop FluentGraph into any ServiceNow Fluent project and get your complete dependency graph in under sixty seconds.

View on npm Star on GitHub

AI From ChromaDB to S3 Vectors — What I Learned About How Embeddings Actually Work

January 01, 2026 · YES PRASAD

Embeddings

· YES PRASAD · 0 comments

ChromaDB · S3 Vectors · RAG · AWS Bedrock

I have been building RAG systems for a while now. ChromaDB locally, then AWS with Bedrock and S3 Vectors. As I was building, I asked myself: "so where exactly does the embedding sit?"

So I went deep. I traced one sentence — one actual benefits document chunk — from raw text all the way through embedding, storage, and retrieval. In two completely different systems. What came out the other side changed how I think about vector databases in general.

The Sentence That Started It

A simple question

My RAG system answers health insurance benefits questions. The documents contain sentences like this:

"Preventive care: Annual physical, immunizations, and screenings
covered at 100% in-network, no copay."

When a user asks "Is my annual checkup free?" — they never wrote those exact words. The RAG system has to find that sentence anyway. That is the whole point of vector search: finding semantic similarity, not keyword matches.

To get there, that sentence has to become a number. Actually, it has to become a list of numbers. Let me show you exactly what happens — in both worlds.

Two Worlds, Same Problem

Same pipeline, very different internals

I built the same pipeline twice. First with sentence-transformers + ChromaDB running locally. Then with Amazon Titan V2 + S3 Vectors on AWS via CDK. Same input. Same goal.

World 1 — Local / ChromaDB

self.model = SentenceTransformer('all-MiniLM-L6-v2')
self.client = chromadb.PersistentClient(path='./chroma_store')
self.collection = self.client.get_or_create_collection('policies')

World 2 — AWS / S3 Vectors

bedrock_runtime = boto3.client("bedrock-runtime", region_name="us-east-1")
s3vectors = boto3.client("s3vectors", region_name="us-east-1")

One runs inference on my laptop. The other makes API calls to AWS. But the shape of what they produce — and what they store — is structurally the same.

Step 1

Turning text into numbers

embedding — encode()

"Preventive care: Annual physical, immunizations..."
        ↓  encode()  or  invoke_model()
[0.0231, -0.1847, 0.0093, 0.2341, ..., -0.0876]

With all-MiniLM-L6-v2: The model weights (~80 MB) live on your machine. model.encode(text) runs inference locally and returns a numpy array of 384 floats. No network call. No cost. Fast.

With Titan V2: A POST request goes to Bedrock. AWS runs the model on their infrastructure and returns a list of 1024 floats. Network latency. Billed per token.

"The embedding is not a summary. It is a coordinate. A point in high-dimensional space where meaning lives as geometry."

Step 2

What gets stored and where

This is where the two systems diverge most visibly.

ChromaDB — add

def process_chunk(self, chunk_text, chunk_id):
    embeddings = self.model.encode(chunk_text)
    self.collection.add(
        documents=[chunk_text],
        embeddings=[embeddings.tolist()],
        ids=[chunk_id]
    )

AWS — put_vectors()

vectors_payload.append({
    "key": f"{policy}_chunk_{idx:04d}",
    "data": {"float32": embedding},         # the 1024 floats
    "metadata": {
        "policy":      "PPO_PLUS",
        "chunk":       chunk_text,          # original text stored here
        "chunk_index": idx,
        "source":      "docs/ppo_plus_2024.txt"
    }
})
s3vectors.put_vectors(
    vectorBucketName=BUCKET, indexName=INDEX, vectors=vectors_payload
)

The structure is the same: a unique key, the float vector, and the original text traveling alongside. The difference is that my ChromaDB version stores no policy metadata — which matters enormously at query time.

Architecture

The full pipeline visualised

YOUR SENTENCE (raw text)
         │
         ▼
┌─────────────────────────┐
│   EMBEDDING MODEL       │
│                         │
│  MiniLM  →  384 floats  │
│  Titan   →  1024 floats │
└─────────┬───────────────┘
          │
          ▼
┌─────────────────────────────────────────────────┐
│              VECTOR STORE                        │
│                                                  │
│  KEY          │ VECTOR          │ TEXT/METADATA  │
│  chunk_0042   │ [0.02, -0.18…] │ "Preventive…"  │
│  chunk_0043   │ [0.11,  0.03…] │ "Deductible…"  │
│  chunk_0044   │ [-0.07, 0.22…] │ "Out-of-pocket"│
│                                                  │
│  ◄── similarity search runs here ──►             │
│        (on the float columns only)               │
└─────────────────────────────────────────────────┘
          │
          ▼
    QUERY: "Is my annual checkup free?"
         │  embed this too
         ▼
    [0.019, -0.176, ...]   ← 384 or 1024 floats
         │  cosine similarity against stored vectors
         ▼
    chunk_0042  score 0.91  ✓  return its text
    chunk_0019  score 0.74
    chunk_0031  score 0.71

Step 3 — The Part I Did Not Expect

ChromaDB uses two storage systems

I thought ChromaDB was Magic! It is not. It uses two completely separate storage systems — and understanding why is the most interesting technical detail in this entire article.

./chroma_store — on disk

./chroma_store/
├── chroma.sqlite3          ← ids, documents, metadata
└── <collection-uuid>/
    ├── data_level0.bin     ← the actual float vectors (HNSW)
    ├── header.bin
    └── length.bin

SQLite — chroma.sqlite3

Human-readable data

IDs, original document text, and metadata — everything you can read, filter, and query with standard SQL.

HNSW — data_level0.bin

The float vectors

Raw float arrays stored in a Hierarchical Navigable Small World graph, purpose-built for nearest-neighbour search.

Root Cause

Why two systems?

SQLite is not designed for "find me the 3 rows whose float arrays are geometrically closest to this other float array." HNSW builds a multi-layered graph and navigates it hierarchically — O(log n) instead of brute-force O(n). The two systems work together: HNSW returns IDs 42, 17, 8 → SQLite returns their text.

HNSW GRAPH — simplified

HNSW GRAPH (simplified)

Layer 2 (coarse):    A ──────────────── E
                          \          /
Layer 1 (medium):    A ─── C ─────── E ─── G
                     │     │         │
Layer 0 (fine):    A─B─C─D─E─F─G─H─I─J  (all vectors here)

✓ Query enters at Layer 2, navigates toward target region,
  then drills to Layer 0 for exact nearest neighbors.

"ChromaDB looks like one thing from the outside. Inside, it's a SQLite database and an HNSW graph file working as a team — one for the math, one for the meaning."

Step 4

Why metadata filtering actually matters

At query time, the user asks: "What is my deductible?" That question gets embedded into the same vector space as all stored chunks. Here is where the two implementations diverge in a way that directly affects answer quality.

Scenario A — ChromaDB, no metadata

Imprecise retrieval.

A question about PPO deductibles might return HMO chunks. The similarity search does not know which plan the user is asking about.

Mixed results — PPO question
returned HMO_SELECT chunks

Scenario B — S3 Vectors, filtered

Precise retrieval.

Policy is stored as metadata at ingest and used to filter before similarity search runs. Only the correct plan's chunks are ranked.

The right way — ChromaDB supports this too

results = self.collection.query(
    query_embeddings=[question_embedding.tolist()],
    n_results=3,
    where={"policy": "PPO_PLUS"}   # filter equivalent
)

The lesson: metadata is not decoration. It is the mechanism that makes multi-document RAG precise. Build it in from day one.

Comparison

ChromaDB vs S3 Vectors — side by side

Dimension	ChromaDB (local)	S3 Vectors (AWS)
Embedding model	`all-MiniLM-L6-v2` local	Titan Embed V2 via Bedrock
Vector dimensions	384	1024
Where model runs	Your machine (CPU)	AWS infrastructure
Embedding cost	Free (compute only)	Billed per token
Vector storage	HNSW `.bin` files on disk	Managed ANN index
Text/metadata	SQLite (chroma.sqlite3)	Metadata fields in S3 Vectors
Query filtering	`where={"policy": ...}`	`returnMetadata=True` + filter
Scales beyond one machine	No (file-based)	Yes (managed service)
Setup complexity	`pip install chromadb`	CDK stack + IAM + bootstrap
Best for	Local dev, prototyping	Production, multi-user, scale

Takeaways

What I would tell myself before starting

ChromaDB is not Magic!. It is SQLite plus HNSW. The SQLite handles text and metadata retrieval. The HNSW handles the actual vector math. They are different tools solving different problems, bundled into one library.
The embedding dimension is a contract. If you ingest with all-MiniLM-L6-v2 (384 dims) and query with Titan V2 (1024 dims), you get an error or nonsense results. Whatever model you use at ingest time, you must use at query time. Always.
Metadata is not optional. The moment you have more than one document type or user context in your vector store, metadata filtering is how you keep retrievals precise. Build it in from day one.
Local to cloud is architectural, not technical. The concepts — embed, store, search, retrieve — are identical. The execution model changes: local CPU vs API call, disk files vs managed service, free vs billed. The hardest part was IAM and CDK, not the vector logic.

Closing

Not by reading, but by geometry

The RAG pipeline I built for wellness benefits uses S3 Vectors in production now — with Titan V2 for embeddings, Nova Micro for generation, and Bedrock Guardrails on both input and output. The vector search itself is one step in a larger chain.

But understanding that one step precisely — what a vector is, where it lives, what retrieves it, and why ChromaDB needs both SQLite and HNSW to do the job — changed how I reason about everything above it.

That sentence about preventive care? It is a point in 1024-dimensional space now. When someone asks if their checkup is free, the system finds that point — not by reading, but by geometry.

ChromaDB· S3Vectors· Embeddings· RAG· AWSBedrock· VectorSearch· HNSW

RAG

Building RAG systems and agentic pipelines on AWS. Part of the RAG → Agentic RAG series — previous posts cover chunking strategy, hallucination handling, and the ReAct agent loop.

GitHub LinkedIn

TypeScript Complier API: Reading Object's Key and value pair using "ts-morph"

October 15, 2025 · YES PRASAD

Recently, I am trying to build a Domain Specific Language (DSL) which sits inside a TypeScript file (*.ts).

My aim is to read and convert this file into a JSON and then convert it into to JavaScript and then to XML.

To do this, we need to traverse the code inside this .ts file which has the DSL. This can be done either directly by TypeScript Compiler API which is more verbose and laborious or through a package called ts-morph which wraps the APIs into a more convenient interface.

I chose ts-morph for my use case.

Here is a sample code from my DSL. It assigns a constant with a function call that takes a plain JavaScript object.


export const server_script = ServerScript({
  name: 'script',
  metadata: {
    origin: 'external_api',
    module: 'customer',
    createdBy: 'Admin'
  }
});

To parse this, when we send the file to ts-morph, it creates an AST (Abstract Syntax Tree) which needs to be recursively parsed to extract the required information.

If we use the ASTExplorer tool, we will see a tree as below:


SourceFile
  └─ VariableStatement
       └─ VariableDeclarationList
            └─ VariableDeclaration (name: "server_script")
                 └─ Initializer → CallExpression
                      ├─ Expression → Identifier ("ServerScript")
                      └─ Arguments
                           └─ ObjectLiteralExpression
                                ├─ PropertyAssignment (key: "name")
                                │   └─ Initializer → StringLiteral ("script")
                                └─ PropertyAssignment (key: "metadata")
                                     └─ Initializer → ObjectLiteralExpression
                                          ├─ PropertyAssignment (key: "origin", value: "external_api")
                                          ├─ PropertyAssignment (key: "module", value: "customer")
                                          └─ PropertyAssignment (key: "createdBy", value: "Admin")

As we can notice, the object’s key–value pairs such as Key: name and Value: script can be extracted differently. Let’s see how.

We have to let the TypeScript compiler know that the node we are parsing is of type Node.ObjectLiteralExpression.

Here’s the step-by-step extraction process. First, we find all nodes which are of ServerScript type:


const scriptExpressions = sourceFile
  .getDescendantsOfKind(SyntaxKind.CallExpression)
  .filter(call => call.getExpression().getText() === 'ServerScript');

The result we get is of type CallExpression<ts.CallExpression>[], which is essentially nothing but an array.

we need to now iterate through the above CallExpression array. for now let us take we loop through the first element in the array. the code looks like below


const ObjectLit = callExpr.getArguments()[0].asKindOrThrow(SyntaxKind.ObjectLiteralExpression);
const currentProps = ObjectLit.getProperties();


currentProps.forEach((attribute: ObjectLiteralElementLike) => {
  const currAttribute = attribute.asKindOrThrow(SyntaxKind.PropertyAssignment);
  const key = currAttribute.getName();
  
});

as we can see above, the Key is easy to read - it is a simple .getName but to read the value we need to do .getInitializer() first to read the complete value and then check its type and then read the value, for example in our case it is a simple StringLiteral as seen above, it is currAttribute.getInitializer()?.getText()

but then why does ts-morph wants us to do this extra job to read the value and not a simple .getValue()??

This is because, the value here can be another ObjectLiteral or a CallExpression or anything. Thus the compiler wants us to explicitly understand what it is and hence gives us the option .getInitializer() to first get it and check its type and then extract the content.

ts-morph is an npm package that wraps the TypeScript compiler API to make syntax tree manipulations much simpler to perform using TypeScript itself.

LLM From RAG to Agentic RAG — Why I Built It, Whether It's Real, and What Comes Next

September 19, 2025 · YES PRASAD

AI AgentAgentic RAGReActInsuranceWellnessArchitecture

I have a confession: I forgot why I built this.

I finished my RAG series — three posts on chunking, hallucination, and token speed — and then kept coding. The repo grew a new folder called agent/. Files appeared: perceive.py, reason.py, act.py. I shipped it, wrote a README, and moved on. A few weeks later someone asked me why I added the agent layer at all, and I genuinely did not have a crisp answer.

So I went back and reconstructed it. This article is what I found — and more usefully, when a RAG system actually needs to become an agent, with real evidence from companies that have already made that call.

The Honest Reconstruction

Why I actually built this

It started with an ER visit. The bill was itemized in ways I did not understand, which sent me down a rabbit hole about how medical charges are actually structured. I built a RAG system to query policy documents — wellness plans, benefits handbooks, coverage tables — and get plain-language answers with citations.

That worked. But then a different question formed: what if an employee did not just want to read their benefits — what if they wanted to act on them? Check eligibility before a procedure. Compare two plan options side by side. Ask a follow-up that depended on the previous answer. These are not retrieval problems. They are reasoning problems that happen to need retrieval inside them.

"A RAG system answers. An agent pursues a goal. The moment your user's question requires more than one retrieval step to answer honestly, you are already in agent territory."

That is the line I crossed — probably without fully realising it. The wellness agent I built is designed for employees and HR teams at companies whose wellness benefits are administered through a provider. Simple queries like "what is the maximum gym claim?" are retrieval. But "compare my nutrition and mental health coverage and tell me which one I am underusing" — that requires intent classification, two separate retrievals, a synthesis step, and a structured answer. That is an agent workflow.

RAG vs Agent

The actual difference — not the theoretical one

Traditional RAG

One question. One retrieval. One answer.

Query comes in. Embed it. Fetch top-K chunks. Pass to LLM. Done. The flow is linear, static, and non-iterative. It cannot decide to look again.

Agentic RAG

A goal. Multiple steps. Adaptive retrieval.

The LLM plans, retrieves, observes the result, and decides: enough context, or retrieve again? It can call tools, cross-reference sources, and change strategy mid-run.

The practical difference shows up in three scenarios. First, when a query has multiple parts and each part needs its own retrieval. Second, when the answer to the first question determines what to ask next. Third, when you need the system to check its own answer — to retrieve a second source and verify before responding. Standard RAG cannot do any of these. An agent can.

The Signal

When does RAG need to become an agent?

Not always. This is important. Most RAG problems do not need an agent — adding one adds latency, cost, and complexity. The question is whether your use case hits the signals that justify it.

Multi-step queries

The user's question cannot be answered from a single retrieval. It requires sub-questions with intermediate results feeding forward.

Multiple data sources

The answer lives across different documents, APIs, or structured databases — and the agent must decide which to query and in what order.

Verification required

High-stakes answers (benefits, healthcare, compliance) need the system to cross-check its own response before surfacing it to the user.

Conversational continuity

The user's follow-up question depends on the previous answer. Without memory, each turn starts cold and loses context.

The Wellness AI Agent hits three of these. Benefits queries often span multiple plan documents. Comparisons require synthesis across sources. And in healthcare adjacent domains, a wrong answer has real consequences — verification is not optional.

Real World

Companies already running this in production

This is not experimental. Agentic RAG is in production at scale across industries — and the use cases closest to mine are the most instructive.

Production deployments · Agentic RAG

Uber · Genie

Their on-call engineering copilot uses agents at multiple stages: a Query Optimizer reformulates ambiguous questions, a Source Identifier narrows the document set, and a Post-Processor deduplicates retrieved context. Result: 27% more acceptable answers, 60% reduction in incorrect advice vs traditional RAG.

eBay · Mercury

Their internal agent platform combines RAG with real-time inventory data for product recommendations. The agent decides when to retrieve and what source to use — product docs, live listings, or user history — depending on the query context.

Healthcare RAG

Agentic RAG systems pulling patient history, clinical literature, and drug interaction databases improved radiology QA accuracy from 68% to 73%. The agent retrieves from verified sources and decomposes complex clinical questions before answering.

Enterprise HR / Benefits

Employee policy copilots answering HR, travel, and benefits queries with citations and effective dates are explicitly named as a production RAG use case in 2025 enterprise guides — exactly the domain of the Wellness Agent.

The Architecture

What I built — and what the ReAct loop looks like

The project structure separates concerns into two layers. The core/ folder handles the machinery: chunking, embedding, retrieval, LLM calls. The agent/ folder handles the reasoning loop: perception, planning, action. Separating these was the most important architectural decision I made — it means the agent layer can evolve without rewriting the retrieval layer.

Wellness AI Agent — Project Structure

── agent/ (the reasoning loop)

perceive.py → clean input, classify intent

reason.py → plan steps, assemble retrieval queries

act.py → call core/, generate answer, observe result

── core/ (the retrieval machinery)

chunker.py → paragraph-based, 2-sentence overlap

embedder.py → all-MiniLM-L6-v2 embeddings

retriever.py → ChromaDB vector search, top-K cosine

llm_interface.py → Ollama / local model calls

── documents/

wellness_plan.md → the benefit document corpus

The pattern the agent follows is close to ReAct — Reasoning + Acting — where the model interleaves thought steps with retrieval actions. Perceive observes the input. Reason plans the retrieval steps. Act executes them and observes the result. The difference between this and full ReAct is the feedback loop: in true ReAct, the observation from Act feeds back into Reason so the model can decide whether to retrieve again or stop. That loop is the next thing I am adding.

Current state

Agentic RAG pipeline — linear

Perceive → Reason → Act runs once per query. The agent classifies intent, retrieves relevant chunks from the wellness plan documents, synthesizes an answer with citations. Single pass, no iteration.

Works well for: Single-intent queries — "what is covered for mental health?" — where one retrieval retrieves enough to answer fully.

Next state

Full ReAct loop — iterative

Act feeds its observation back into Reason. The LLM decides: "I have enough context" → deliver answer, or "I need to retrieve from the nutrition section too" → loop again. Maximum 3–4 iterations before forcing a final answer.

Needed for: Multi-part queries — "compare my gym and nutrition coverage and flag anything expiring this year" — where a single retrieval does not surface enough.

What This Means

The phrase I keep coming back to: reactive to predictive

When I first wrote about AI agents, I included a phrase without fully unpacking it: reactive to predictive. Traditional software — and traditional RAG — is reactive. Something happens, the system responds. An agent is predictive: it has a goal, it plans steps toward that goal, and it adjusts when reality does not match the plan.

For wellness benefits, that shift matters more than it might seem. A reactive system answers what you asked. A predictive one might notice you asked about gym coverage but have not claimed it yet this year, and surface that proactively. That is not a retrieval problem. That is an agent problem. And it is exactly the kind of thing that makes the difference between a tool employees open once and a tool they actually rely on.

"The market for agentic RAG is projected to reach $40 billion by 2035. The underlying use case — grounded, auditable, multi-step reasoning over private documents — is the same one I am building for wellness benefits."

What's Next

Where this project goes from here

✓ Paragraph chunking with 2-sentence overlap in core/
✓ Intent classification in perceive.py
✓ Retrieval + generation with citations in reason/act
✓ Separated agent layer from retrieval layer
○ ReAct feedback loop: act observation → reason re-plan
○ Session memory in core/ — remember prior Q&A per user
○ Multi-document routing — which plan document to query first
○ Claims processing actions — not just answers, but submissions

Part 4 of the RAG → Agent series. Parts 1–3 cover building RAG from scratch without LangChain, chunking strategy, and local model benchmarking. The full code for the Wellness AI Agent — including the agent loop and core RAG machinery — is on GitHub.

Wellness AI Agent on GitHub · Built from scratch · No LangChain · Full agent loop coming.

View on GitHub RAG Repo LinkedIn

I build backend systems, AI tools, and developer infrastructure.

Research

Engineering Lab

Field Notes

Production breaks are preventable

Everything your team needs
to ship with confidence

Three sections.
Complete visibility.

Know what breaks
before you deploy

Up and running
in under a minute

Catch conflicts
before the merge

A simple question

Same pipeline, very different internals

Turning text into numbers

What gets stored and where

The full pipeline visualised

ChromaDB uses two storage systems

Human-readable data

The float vectors

Why two systems?

Why metadata filtering actually matters

Imprecise retrieval.

Precise retrieval.

ChromaDB vs S3 Vectors — side by side

What I would tell myself before starting

Not by reading, but by geometry

Why I actually built this

The actual difference — not the theoretical one

One question. One retrieval. One answer.

A goal. Multiple steps. Adaptive retrieval.

When does RAG need to become an agent?

Companies already running this in production

What I built — and what the ReAct loop looks like

Agentic RAG pipeline — linear

Full ReAct loop — iterative

The phrase I keep coming back to: reactive to predictive

Where this project goes from here

I build backend systems, AI tools, and developer infrastructure.

Research

Engineering Lab

Field Notes

Production breaks are preventable

Everything your team needsto ship with confidence

Three sections.Complete visibility.

Know what breaksbefore you deploy

Up and runningin under a minute

Catch conflictsbefore the merge

A simple question

Same pipeline, very different internals

Turning text into numbers

What gets stored and where

The full pipeline visualised

ChromaDB uses two storage systems

Human-readable data

The float vectors

Why two systems?

Why metadata filtering actually matters

Imprecise retrieval.

Precise retrieval.

ChromaDB vs S3 Vectors — side by side

What I would tell myself before starting

Not by reading, but by geometry

Why I actually built this

The actual difference — not the theoretical one

One question. One retrieval. One answer.

A goal. Multiple steps. Adaptive retrieval.

When does RAG need to become an agent?

Companies already running this in production

What I built — and what the ReAct loop looks like

Agentic RAG pipeline — linear

Full ReAct loop — iterative

The phrase I keep coming back to: reactive to predictive

Where this project goes from here

Everything your team needs
to ship with confidence

Three sections.
Complete visibility.

Know what breaks
before you deploy

Up and running
in under a minute

Catch conflicts
before the merge