yvgude--lean-ctx/docs/context-os/cookbook-non-coding.md

Non-Coding Cookbook

Concrete recipes for building non-coding agents on lean-ctx. Each uses real, shipped features — personas, extractors, SDKs, and adapters — no mocks.

Prerequisites: a running server (lean-ctx serve or the HTTP server) and one SDK installed. Examples use the Python SDK; the TypeScript SDK is equivalent.

from leanctx import LeanCtxClient
client = LeanCtxClient("http://127.0.0.1:8080")

---

Recipe 1 — Lead-generation agent

Goal: prospect and enrich sales leads from web pages and notes.

1. Select the persona. lead-gen exposes web/search/knowledge tools, uses the prose compressor, paragraph chunking, and a confidential sensitivity floor — set it for the process:

   export LEAN_CTX_PERSONA=lead-gen
   

2. Ingest a prospect page. HTML is extracted to clean Markdown and chunked by paragraph automatically when indexed; or read a URL via the tool:

   text = client.call_tool_text("ctx_url_read", {"url": "https://acme.example/about"})
   

3. Persist enrichment facts so later turns recall them cheaply:

   client.call_tool("ctx_knowledge", {
       "action": "remember", "category": "decision",
       "content": "ACME: 200 employees, Series B, CTO is the buyer."})
   

4. Wire into your harness. Expose lean-ctx tools to your LLM loop:

   from leanctx.adapters import to_openai_tools, run_openai_tool_call
   tools = to_openai_tools(client)        # pass to your OpenAI call
   # when the model returns a tool_call:
   result_text = run_openai_tool_call(client, tool_call)
   

Why it works: the prose compressor strips scraped-page boilerplate; the confidential floor keeps lead data from leaking into shareable artifacts.

---

Recipe 2 — Research assistant with cited synthesis

Goal: read documents/web and synthesize findings with citations.

1. Persona: research — map read-mode, the markdown compressor (strips HTML comments, badges, and link-URL noise while keeping text), and a public sensitivity floor.

   export LEAN_CTX_PERSONA=research
   

2. Index a corpus of mixed formats. The ingestion front-door admits .md, .html, .pdf, .json, .csv (not just code), and the extractor picks the right reader per format:

   client.call_tool_text("ctx_index", {"action": "build", "project_root": "./reports"})
   

3. Search semantically across the indexed corpus:

   hits = client.call_tool_text("ctx_semantic_search", {"query": "Q3 churn drivers"})
   

4. Synthesize in your agent, citing the chunk sources the tools return.

Why it works: format extractors normalize PDFs/HTML into paragraphs; the markdown compressor removes link/badge noise so more of the budget is signal.

---

Recipe 3 — Customer-support triage

Goal: triage inbound emails and resolve from a knowledge base.

1. Persona: support — auto read-mode, prose compressor, internal floor, intents triage/diagnose/resolve/escalate/document.

2. Extract the email. .eml files become a salient-header summary (From/To/ Subject/Date) plus the text/plain body — MIME boilerplate stripped:

   # When indexing a mailbox dir, .eml is handled by the eml extractor.
   client.call_tool_text("ctx_index", {"action": "build", "project_root": "./tickets"})
   

3. Find the resolution in your KB and draft a reply with your LLM, using ctx_semantic_search + ctx_knowledge recall.

4. Stream live updates to a dashboard via SSE:

   for event in client.subscribe_events():
       dashboard.push(event["kind"], event["payload"])
   

---

Recipe 4 — Data-analysis pipeline

Goal: ingest structured data and report.

1. Persona: data-analysis — map read-mode, identity compressor (preserves tabular structure), lines chunker.

2. Ingest CSV/JSON. The CSV extractor parses RFC-4180 (quoted fields, embedded delimiters) into labeled records; JSON is chunked per element/entry:

   client.call_tool_text("ctx_index", {"action": "build", "project_root": "./data"})
   

3. Query with ctx_search / ctx_semantic_search, then compute and report in your harness.

Why it works: identity + lines keep rows intact so the model reasons over real records, not reflowed prose.

---

Building a custom vertical

Not one of the four? Ship a persona file at <personas_dir>/<name>.toml:

name = "compliance"
tool_profile = "custom"
tools = ["ctx_read", "ctx_search", "ctx_semantic_search", "ctx_knowledge"]
default_read_mode = "map"
compressor = "prose"
chunker = "paragraph"
intent_taxonomy = ["scan", "flag", "cite", "report"]
sensitivity_floor = "confidential"

Then export LEAN_CTX_PERSONA=compliance. See persona-spec-v1. Add a domain tool with a plugin manifest, or a domain compressor/chunker via the extension registry — both surface in /v1/capabilities and are conformance-checked.

---

Verifying your integration

from leanctx import run_conformance
card = run_conformance(client)
assert card.all_passed, [c for c in card.checks if not c.passed]

And prove the savings to stakeholders:

lean-ctx savings roi --json