Random thoughts on coding and technology

Building a Local Voice Cloning Studio That Actually Runs on My Machine

noreply@blogger.com (Jordi Corbilla) — Sun, 19 Apr 2026 06:33:00 +0000

I wanted a local voice cloning workflow that felt like a real product, not a notebook demo.

The goal was simple: record or upload a short reference clip, create a reusable voice profile, type arbitrary text, synthesize speech locally, and keep every file on my own machine. No accounts, no cloud voice API, no remote inference.

The result is local-voice-studio: a React and FastAPI application with local profile management, reference audio handling, generation history, diagnostics, and pluggable local TTS engines.

The Product Shape

The app is built around a few core workflows.

You can create multiple voice profiles, each with notes, language preference, tags, saved reference clips, a primary clip, and synthesis defaults. Reference clips can come from browser microphone recording or from uploaded audio files. The backend normalizes every clip to a model-friendly WAV file, stores metadata in SQLite, and keeps the original upload on disk.

The generation page is a focused workspace: choose a profile, enter text, optionally provide delivery instructions, tweak advanced settings, generate audio, and then preview or download the WAV result. Every generation is stored in history with status, parameters, input text, output path, and errors if something fails.

The settings page shows the local runtime state: active engine, model name, GPU detection, FFmpeg availability, directories in use, and whether local transcription is available.

Everything lives under the local data/ directory.

Architecture

The backend is FastAPI with a deliberately boring service/repository split.

Routes handle HTTP only. Services coordinate profile management, audio processing, generation jobs, runtime diagnostics, and TTS orchestration. Repositories isolate SQLite persistence. Audio utilities handle normalization and metadata probing through FFmpeg and FFprobe.

The TTS runtime sits behind a TtsEngine interface. The generation service does not care whether the active engine is XTTS or Qwen3. It prepares a profile, builds a synthesis payload, writes the output to data/generated, and records status updates in SQLite.

Synthesis runs as an in-process background job. That is enough for a local desktop-style app and avoids adding Redis, Celery, or other distributed infrastructure too early.

The frontend is React, TypeScript, Vite, React Router, and TanStack Query. The UI is desktop-first, dark, and intentionally simple: left navigation, profile cards, reference clip panels, a generation workspace, history, and diagnostics.

The XTTS Lesson

The first implementation used Coqui XTTS v2.

XTTS was a useful baseline because it can do zero-shot voice cloning from reference audio and it is relatively well-known in local TTS experiments. The app normalized clips, cached conditioning artifacts when possible, and used the selected primary clip as the conditioning source.

But in practice, the output did not sound close enough. The voice often drifted into a generic speaker. In one test, the result sounded like a random English man rather than the target voice.

That was an important product lesson: a working local model integration is not the same thing as a good cloning experience.

The app was technically generating speech, but the speaker identity was not good enough.

Why Transcript-Aware Cloning Helped

The breakthrough was moving from audio-only cloning to transcript-aware cloning.

Qwen3-TTS expects the reference audio and the exact text spoken in that reference audio. That small workflow change matters. Instead of asking the model to infer everything from the waveform alone, the app gives it aligned acoustic and linguistic context.

So the profile workflow changed:

Record or upload a clean reference clip.
Mark the best clip as primary.
Save the exact transcript of that clip.
Generate using Qwen3-TTS.

The app now stores reference_text on each clip. The primary clip transcript becomes part of the conditioning fingerprint, so changing the transcript invalidates old cached prompts. There is also an optional local transcription path using a Whisper-style local ASR dependency, but manual transcript entry is always available and often better if the user knows exactly what they said.

This made the system feel much closer to the Voicebox-style workflow that worked well in practice.

UX Details That Matter

Local AI workflows often have long, silent waits. That is bad UX.

The app now shows loading feedback where it matters:

The Transcribe locally button shows a spinner while transcription is running.
The transcription button is disabled while the action is in progress, preventing accidental duplicate requests.
The Generate audio button shows a spinner while the job is starting or running.
The generate page warns if the selected primary clip is missing its transcript.

These are small details, but they make the app feel more trustworthy. When local models take time to load, users need visible progress.

Running It Locally

The recommended path is Qwen3-TTS.

From the repository root:

powershell -ExecutionPolicy Bypass -File .\scripts\setup.ps1
& .\.venv\Scripts\python.exe -m pip install -e ".\backend[qwen,transcription]"

Start the backend:

$env:LVS_TTS_ENGINE = "qwen3"
powershell -ExecutionPolicy Bypass -File .\scripts\dev-backend.ps1

Start the frontend:

powershell -ExecutionPolicy Bypass -File .\scripts\dev-frontend.ps1

Then open:

http://localhost:5173

If another local app is already using port 8000, run the backend on 8010 and point the frontend proxy at it:

$env:LVS_TTS_ENGINE = "qwen3"
$env:LVS_BACKEND_PORT = "8010"
powershell -ExecutionPolicy Bypass -File .\scripts\dev-backend.ps1

$env:VITE_API_TARGET = "http://127.0.0.1:8010"
powershell -ExecutionPolicy Bypass -File .\scripts\dev-frontend.ps1

What I Would Improve Next

The next improvements are mostly product polish and runtime hardening.

The app should make the active engine more visible in the main UI. Profiles should get a clear "Qwen-ready" badge when their primary clip has a transcript. The transcription workflow could show progress beyond a spinner, especially on first model load. The settings page could provide stronger guidance when the environment is missing Qwen, Whisper, CUDA, FFmpeg, or model weights.

Long-form generation also needs more work. The app currently supports normal generation jobs, but paragraph-aware chunking, concatenation, and better history grouping would make it more useful for narration.

Finally, Qwen and XTTS have different Python/runtime expectations. A future version could support separate engine environments or a small process boundary so users do not have to fit every model into one Python virtual environment.

Takeaway

The biggest lesson was that local-first voice cloning is not just about wiring up a model.

The workflow matters.

For this project, XTTS proved the architecture and local storage model. Qwen3-TTS made the voice identity closer by adding the missing reference transcript. The resulting app is still early, but it now has the shape of a real local voice studio: profiles, clips, transcripts, generation history, runtime diagnostics, and no cloud dependency.

Beyond Prompts: Building a Codex Playbook for Real Application Developmentnoreply@blogger.com (Jordi Corbilla) — Mon, 13 Apr 2026 20:13:00 +0000
One-off prompting is weak engineering infrastructure.
It can be useful for getting unstuck, drafting code, or exploring ideas, but it does not produce repeatable engineering behavior on its own. The same prompt that works acceptably on one backend feature often degrades into generic advice or inconsistent implementation on the next one. That happens because a prompt is usually trying to do too many jobs at once: repository policy, architectural philosophy, feature workflow, review heuristics, and implementation detail.
This repository was built to separate those concerns and make them durable. 
JordiCorbilla/codex-engineering-playbook
The Core ProblemMost teams experimenting with coding agents start with giant instruction blobs. They pour style preferences, architecture opinions, code review heuristics, framework conventions, and edge-case warnings into a single file or prompt. That usually fails in predictable ways:
durable guidance gets buried under temporary workflow detail
the instructions become too large to scan and too vague to route reliably
project structure becomes secondary to the agent's last prompt
implementation becomes inconsistent across languages and application layers
The problem is not that the model needs more words. The problem is that the repository needs a better operating model.
What This Repository Builds InsteadThis playbook uses four layers:
AGENTS.md for durable repository-wide rules
.agents/skills for reusable workflows
templates and scripts for deterministic implementation support
examples for concrete, inspectable reference projects
That split is the point of the repository.
The top-level AGENTS.md stays small. It says what the repository is for, when to prefer skills, what "done" means, and what kinds of validation are expected. It does not try to teach every implementation pattern directly. That restraint is important. Durable instructions should be hard to invalidate.
The detailed workflow logic moves into focused skills such as:
csharp-backend-feature
python-backend-review
react-typescript-feature
api-contract-review
layered-architecture-recon
This is better than a giant style blob because routing matters. Reviewing a Python backend diff is not the same task as implementing a React feature or mapping an unfamiliar layered architecture. Putting those workflows into separate skills makes the instructions sharper and more reusable.
Why Durable Repo Instructions MatterAgent behavior improves when the repository teaches stable defaults instead of relying on the operator to restate them every time.
In this repository, the durable defaults are simple:
inspect existing structure first
keep boundaries clear
put logic in the right layer
validate the touched area before calling the work done
explain trade-offs when architecture changes
Those rules are broad enough to matter across C#, Python, and React, but narrow enough to remain useful. They establish an operating model without pretending the languages are interchangeable.
Why Skills Beat Giant Prompt FilesA single giant prompt tends to flatten all engineering work into "follow best practices." That is almost always too soft. Real engineering work has modes, and the quality bar changes with the mode.
Feature work needs placement discipline. Review work needs risk detection. Contract review needs attention to caller-visible behavior. Architecture reconnaissance needs an accurate map, not rewrite advice.
That is why the skills in this repository are intentionally separate:
csharp-backend-feature cares about thin controllers, service-led behavior, async correctness, DTO boundaries, and targeted tests.
csharp-backend-review cares about fat controllers, sync-over-async mistakes, leaky entity boundaries, and weak exception flows.
python-backend-feature emphasizes typed boundaries, thin request handling, explicit services, and restrained abstraction.
frontend-ux-polish is about hierarchy, spacing, labels, state clarity, and affordances, not broad frontend architecture.
Separating those workflows does two things. It makes routing more reliable, and it avoids making every task carry the weight of every other task's instructions.
The C# GuidanceThe C# portion of the playbook favors a layered ASP.NET Core style, but it is not blindly enterprise. The guidance in conventions/csharp.md pushes toward controllers, services, and repositories when those boundaries provide real value. It also says something many style guides avoid saying clearly: repository abstractions can become ceremony.
That trade-off matters. In the C# example app, the repository boundary exists because it helps keep persistence concerns separate and makes the service easy to test. But it stays intentionally small and in-memory. The goal is to demonstrate responsibility boundaries and async flow, not to perform ORM theater.
The example includes:
OrdersController.cs for HTTP concerns
OrderService.cs for validation, orchestration, and business flow
InMemoryOrderRepository.cs for isolated storage behavior
ExceptionMappingMiddleware.cs for centralized error translation
That is a good example of the repository's overall stance: use structure to clarify responsibilities, not to multiply files for their own sake.
The Python GuidancePython code often swings between two bad extremes when teams talk about architecture. One extreme is route handlers full of business logic and IO. The other is an imported enterprise pattern that creates classes, abstract base types, and indirection that the codebase has not earned.
The Python guidance in conventions/python.md tries to avoid both.
It emphasizes:
thin request handling
typed boundaries
explicit validation
clear service or module ownership
simplicity over cleverness
In the Python example app, the route module translates HTTP concerns, the service owns the business path, and the data-access layer stores records in memory. The example is intentionally small, but the boundaries are inspectable:
orders.py keeps request handling thin
orders.py owns the business behavior
orders.py isolates storage concerns
orders.py defines typed request and response models
That structure is useful because it makes future changes cheaper. A new validation rule or storage implementation has an obvious home.
The React + TypeScript GuidanceFrontend guidance is often too aesthetic or too abstract. This playbook is trying to be engineering guidance, so the React conventions focus on code structure, state handling, and contract discipline.
The priorities in conventions/react-typescript.md are:
keep components focused
separate API access from rendering
make loading, error, and empty states explicit
type props and async data honestly
keep hooks disciplined
avoid business logic hidden in JSX
The React example app is not a design system demo. It is a small application slice showing the separation between transport, state, and presentation:
orders.ts owns data access behavior
useOrders.ts models async state transitions
OrderSummaryList.tsx renders typed data
App.tsx composes the UI and makes loading, empty, and error states visible
That is deliberate. Many generated React examples hide the interesting part of the problem inside a single file. This one does not.
Why The Examples MatterExample apps are not filler in a repository like this. They are operational anchors.
Without examples, convention documents drift toward abstract advice. Skills become more likely to overfit to generic framework knowledge. Templates become harder to evaluate because there is no concrete reference point for what "good" looks like in the repository.
The examples in this playbook make the guidance testable. They show the relationship between the documents and actual code. They also give Codex stable insertion points when exploring an unfamiliar but similarly structured codebase.
The practical run instructions live in the repository README. That split is intentional: the blog explains the design, while the README acts as the operational starting point.
Scripts And Templates As Engineering ToolsAnother failure mode in agent-oriented repositories is over-explaining deterministic work in prose. If a C# controller shape is predictable, a template is better than another paragraph. If you need to discover likely insertion points or summarize changed files, a small script is usually better than asking the model to infer everything from scratch every time.
That is why this repository includes:
templates/csharp
templates/python
templates/react
scripts/scan_repo.py
scripts/find_feature_insertion_points.py
scripts/discover_tests.py
scripts/summarize_changed_files.py
scripts/validate_playbook.py
These are small on purpose. They exist to support repeatability, not to introduce another platform inside the repository.
StrengthsThe repository is structured for reuse, not just demonstration.
The top-level instructions are durable enough to survive ordinary growth.
The skills are narrow enough to route reliably.
The examples make the guidance concrete instead of rhetorical.
The validation bar is lightweight but real.
LimitationsThe playbook is intentionally opinionated, which means it will not fit every team culture.
The examples are small; they demonstrate boundaries, not the full complexity of production systems.
The repository does not solve framework-specific edge cases beyond the patterns it chooses to illustrate.
Skills can become stale if a team's real architecture evolves and the playbook does not.
There is also a rigidity trade-off. If a team treats the playbook as law rather than guidance, it can become a local maximum. Not every codebase needs controller/service/repository layering. Not every React feature needs another hook. Not every Python service needs another module boundary. Good playbooks create defaults, not dogma.
Where This Helps MostThis approach helps most when:
a team wants more repeatable coding-agent behavior
the codebase already values clear boundaries
multiple languages need a shared architectural vocabulary
implementation and review workflows should be routable and explicit
It helps less when:
the codebase is intentionally experimental
architecture changes weekly
framework-specific constraints dominate general engineering structure
the team wants maximal freedom and minimal convention
Pros And ConsPros:
better repeatability than one-off prompts
clearer separation between policy, workflow, and implementation detail
easier extension through focused skills
stronger grounding through examples and validation
Cons:
more repository structure to maintain
more upfront design work than dropping a prompt file into a repo
some duplication between conventions, skills, and examples is intentional and needs upkeep
can become too rigid if teams stop exercising judgment
Final ViewThe point of this repository is not to prove that Codex can follow instructions. The point is to make those instructions worth following.
That requires durable repository guidance, focused workflow skills, deterministic helpers, and concrete examples. It also requires saying no to the usual temptation to dump everything into a single mega-prompt and hope the agent will sort it out.
That temptation is understandable. It is also a weak substitute for engineering structure.

Skills for Codex: The missing layer between prompts and reliable workflows

noreply@blogger.com (Jordi Corbilla) — Sun, 12 Apr 2026 18:27:00 +0000

The real unlock for coding agents is packaging workflows into AGENTS.md, skills, and scripts

Most teams experimenting with coding agents are still operating at the wrong layer.

They keep trying to get reliability by writing better prompts. That helps a little. It does not solve the real problem.

The hard part is not telling the model to "be careful" or "think step by step." The hard part is turning repeated engineering workflows into artifacts the agent can reuse: repo instructions, narrowly scoped skills, and deterministic helper scripts.

That is what I built in this demo repository.

The repo is small on purpose. It contains a tiny legacy-style Python service, four concrete Codex skills, a short AGENTS.md, several Python scripts, and lightweight tests. The point is not to show off a toy prompt library. The point is to show what a serious workflow layer looks like when you want an agent to behave more like an engineer and less like an improv partner.

One-line takeaway: prompting is too ephemeral for repeated engineering work.

Another one: if a workflow matters more than once, it should probably exist as a repo artifact.

Why prompting alone breaks down

One-off prompting degrades for boring reasons:

The same task gets described slightly differently every time.
The agent re-derives the workflow from scratch.
Deterministic steps get handled as prose instead of code.
The model mixes operational guidance with local reasoning and drops part of it under pressure.

Senior engineers already know this pattern from human systems. If a workflow matters, we do not rely on memory alone. We add runbooks, scripts, templates, checks, and conventions.

Coding agents need the same thing.

"Please inspect the code carefully before changing anything" is not a reliable mechanism. It is a wish. A skill with explicit triggers, steps, outputs, and boundaries is a mechanism.

The missing layer: `AGENTS.md` + skills + scripts

The repo uses three layers, each doing a different job.

AGENTS.md is the repo-level contract. It tells Codex how work should be done here:

prefer skills for recurring workflows
use scripts for deterministic tasks
validate changes before calling them done
plan first when risk or ambiguity is non-trivial

That file is intentionally short. Repo instructions are more useful when they set constraints and decision rules, not when they try to micromanage every possible action.

The skills are the workflow layer. Each one has a sharp name, obvious routing description, trigger conditions, workflow steps, expected outputs, and boundaries. That matters because routing quality is part of the problem. If skill names are vague, the agent will miss them or apply them at the wrong time.

The scripts are there for the parts that should not depend on language generation at all. Parsing test failures, scanning a repo for hotspots, and extracting risk signals from a diff are all better handled with code than with a paragraph of instructions.

One-line takeaway: natural language is a poor substitute for a parser.

The example repo

The demo repo has a compact but realistic structure:

skills/ contains four engineering workflows
scripts/ contains Python helpers for deterministic scanning and summarization
demo/legacy_service/ contains a deliberately awkward Python service
demo/artifacts/ contains failing test output and a risky sample diff
tests/ validates the scripts

The service is small, but it has the right kind of mess:

module-level in-memory storage
a module-level cache
configuration read from environment at import time
time-sensitive pricing logic
hidden coupling between service, storage, and cache code

That is enough to make the skills meaningful. The repo is not pretending that agents only work on greenfield, well-factored code.

How to get the repo and run it

The repository is here:

https://github.com/JordiCorbilla/engineering-skills-for-codex

If you want the full example locally, clone it and run the lightweight validation:

git clone https://github.com/JordiCorbilla/engineering-skills-for-codex.git
cd engineering-skills-for-codex
python -m unittest discover -s tests -p "test_*.py" -v
python -m unittest discover -s demo/tests -p "test_*.py" -v

If make is available in your environment, the equivalent entry points are simpler:

make test
make validate

The skills themselves live under skills/. In practice, you use them by opening the repo in Codex and invoking the workflow by name when the task matches. For example:

ask Codex to use investigate-before-patching before editing demo/legacy_service/services/order_service.py
ask Codex to use summarize-test-failures against demo/artifacts/pytest_failure_output.txt
ask Codex to use legacy-codebase-recon on demo/legacy_service
ask Codex to use review-change-safely on demo/artifacts/sample_change.diff

The deterministic parts can also be run directly without the skill wrapper:

python scripts/inspect_patch_context.py --root demo --target demo/legacy_service/services/order_service.py
python scripts/summarize_test_failures.py --input demo/artifacts/pytest_failure_output.txt
python scripts/legacy_recon.py --root demo/legacy_service
python scripts/diff_review_summary.py --input demo/artifacts/sample_change.diff

If you want to reuse the skills in another repository, the practical starting point is to copy the relevant folder from skills/, bring over any supporting script from scripts/, and adapt AGENTS.md so the repo-level instructions match the codebase you actually have. Treat these skills as templates for repeatable workflows, not drop-in magic.

The skills

`investigate-before-patching`

This skill exists to stop speculative editing.

Before changing code, the workflow inspects the target module, local dependencies, related tests, and obvious coverage gaps. The helper script, scripts/inspect_patch_context.py, gives a deterministic first pass over imports, sibling modules, and nearby tests.

That sounds basic. It is also exactly the sort of discipline agents tend to skip when left alone. They jump to the patch because producing a patch is easier than earning one.

The important design choice here is scope. The skill does not promise a full call graph. It explicitly says the scan is a starting point and that critical modules still need to be read.

`summarize-test-failures`

This skill handles a very common failure mode in agent-driven work: drowning in raw test output.

The script ingests a test log, extracts parseable failures, clusters them by likely cause, and produces a debugging brief. In the demo, the sample pytest log gets reduced to three concrete buckets:

stale state or cache invalidation
pricing rule regression
configuration drift

That is already more useful than dumping forty lines of traceback back at the user.

The limit is important though: this is a triage tool, not a diagnosis engine. If the log is messy or incomplete, the summary should stay humble.

`legacy-codebase-recon`

This is the first-pass orientation skill for inherited systems.

The script looks for entry points and scores modules for hotspots using simple heuristics: mutable globals, environment coupling, cache usage, time-sensitive behavior, and general structural weight. On the demo service, it correctly flags the order service and repository layer as the riskiest modules.

This is exactly where skills can help: not by pretending to understand a legacy system instantly, but by providing a disciplined first pass that makes the next manual inspection smarter.

The failure mode is also obvious. Heuristics are directional. A hotspot score is not architecture truth.

`review-change-safely`

This skill is designed for reviewing diffs with an emphasis on unintended side effects.

The demo diff changes a function signature, alters the returned payload shape, and replaces a guarded key lookup with a required-key lookup. The script surfaces all three and also notes that no tests moved with the behavior change.

That is a useful baseline because many agent reviews default to a glorified summary. Serious review work needs findings, not narration.

The skill therefore forces a review shape:

findings first
severity and confidence
file references
residual risk

That structure matters. It is much easier to trust and act on than a free-form paragraph about what changed.

Why scripts matter

The scripts are not there because Python is exciting. They are there because some tasks are simply better when the machine is forced to be literal.

Three examples:

First, parsing failure lines. Asking a model to "read this pytest output and summarize it" works until the output is long, repetitive, or messy. A parser is cheap and stable.

Second, scanning code for risk signals. Telling the model to "look for tight coupling and hidden state" is too vague on its own. A script can make that scan explicit and repeatable, even if the results are only heuristic.

Third, diff review. Function signature changes, payload key changes, and test coverage gaps are not subtle concepts. They should be machine-detectable.

The right split is simple:

use scripts for deterministic extraction
use skills for workflow logic
use the model for judgment, prioritization, and synthesis

What worked well

The most useful part of the repo is the layering.

AGENTS.md gives the repo a stable operating model. The skills give recurring tasks structure and routing clarity. The scripts prevent a class of drift where every run invents a slightly different method. The tests keep the helpers from silently rotting.

The second useful part is restraint. The skills are short. They are not trying to encode every engineering principle. They are only trying to make a few repeated workflows reliable enough to be worth using.

One-line takeaway: a narrow skill you can trust is worth more than a broad skill you cannot.

What still does not work well

Skills do not remove the need for real engineering judgment.

They do not understand runtime behavior. They do not replace reading the code. They do not magically fix weak tests, misleading names, or missing context from the user. They also do not help much when the task is genuinely novel and there is no repeated workflow to package.

There is also a maintenance cost. Once you create a skill, you own it. If the repo changes and the skill instructions or script behavior drift, you have created a false sense of reliability.

This is why I would be cautious about building fifty skills too early. Most teams should start with a handful of painful, recurring workflows and make those solid.

When I would use this in production

I would use this pattern in production when:

the team is repeatedly using agents on the same codebase
the work includes bug triage, reviews, legacy recon, or change planning
there is enough repetition to justify a workflow artifact
the team cares more about consistency than about model theatrics

I would not bother in a repo where agent use is rare, the workflows are highly bespoke, or the codebase is changing so quickly that skill maintenance would dominate the value.

The threshold is not "do we use AI?" The threshold is "do we keep repeating the same engineering moves?"

Closing thoughts

The claim here is modest.

Coding agents do not become reliable because we found the perfect prompt. They become more useful when we stop forcing the model to reinvent stable workflows on every task.

That means packaging the workflow.

Write the repo contract in AGENTS.md. Turn repeated tasks into skills with real boundaries. Move deterministic steps into scripts. Test those scripts. Then let the model operate inside that frame.

That is less glamorous than prompt alchemy. It is also much closer to how engineering systems usually become dependable.

Building Fund Overlap Lab: From Surface Labels to Real Exposure

noreply@blogger.com (Jordi Corbilla) — Wed, 08 Apr 2026 15:34:00 +0000

If you have ever compared two multi-asset funds and thought, "These look different, but are they actually different?" this project is for that exact problem.

Fund Overlap Lab is a Python tool for Vanguard UK funds that retrieves holdings, normalizes names, and calculates overlap. It includes a CLI for fast checks and a Streamlit app for interactive analysis.

JordiCorbilla/fund-overlap-lab: fund-overlap-lab

Why It Exists

Wrapper funds such as LifeStrategy and Target Retirement can look distinct at the top level while sharing large portions of the same underlying exposures.

The project aims to make that visible by combining:

look-through holdings
transparent overlap math
risk and cost context
practical UI workflows for real portfolio conversations

Core Overlap Model

For two funds, overlap is calculated as:

sum(min(weight_a_i, weight_b_i))

where each i is a normalized underlying holding.

The app then reports:

overlap percentage
shared and distinct holdings
only-in-A and only-in-B tables
bucket-level aggregation

Data Pipeline: What Changed and Why

Early versions parsed portfolio HTML tables. That broke when pages shifted to JS-driven rendering. The current pipeline is built to survive those changes.

Current strategy:

primary source: GraphQL endpoint for detailed holdings
fallback source: HTML table/text extraction where possible
resilience fallback: API asset-allocation level extraction
dynamic product lookup from Vanguard product catalog

This layered approach keeps the tool operational when upstream page structures move.

How Data Access Works

Under the hood, the provider follows a staged resolution and retrieval flow:

Product resolution

the app accepts multiple identifiers (fund code, SEDOL, slug)
it queries Vanguard UK product metadata and resolves those inputs to canonical product fields (including portId)

Primary holdings retrieval (GraphQL)

with the resolved product, it calls Vanguard UK GraphQL endpoints to fetch holdings details
this path returns richer data than static page scraping, including constituent-level rows where available

Recursive expansion (optional)

in Ultimate Look-Through mode, holdings that are themselves funds or ETFs can be expanded recursively
each child weight is multiplied through the parent path weight
recursion is bounded by max depth and protected against cycles

Fallback retrieval

if detailed holdings cannot be retrieved, the provider falls back to HTML extraction and then allocation-level API data
this keeps the app functional even when one upstream path changes

Normalization and comparison preparation

holding names are normalized for robust joins
duplicate rows are consolidated
percentage fields are standardized before overlap calculations

This design keeps the user workflow simple while handling real-world upstream variability in a resilient way.

Ultimate Look-Through Mode (Recursive)

A major upgrade is recursive decomposition of fund-of-funds structures.

You can now choose between:

Direct Holdings mode: one layer of holdings
Ultimate Look-Through mode: recursively expands eligible underlying funds and ETFs

Both Two-Fund Compare and Portfolio Analysis now include:

an Ultimate Look-Through toggle
a max depth control to limit recursion
cycle protection so recursive expansion does not loop

This matters for mixed wrappers where one level of holdings is still another basket.

Example Questions It Answers Quickly

How much overlap exists between a LifeStrategy fund and a Target Retirement fund right now?
Is a portfolio diversified across managers and wrappers, or concentrated in repeated underlyings?
Do risk and OCF differences align with actual exposure differences?
Does recursive look-through materially change the diversification story?

Project Structure

fund_overlap_lab/providers.py: data access, product resolution, holdings retrieval
fund_overlap_lab/compare.py: overlap and portfolio analytics
fund_overlap_lab/models.py: data models
fund_overlap_lab/buckets.py: coarse asset bucketing
fund_overlap_lab/cli.py: command-line workflows
app.py: Streamlit experience

Run It

Install:

python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt

CLI compare:

python -m fund_overlap_lab.cli compare VGL100A VAR45GA

Streamlit app:

streamlit run app.py

Final Thought

Fund Overlap Lab is intentionally practical. It is built to help answer a real question before making allocation changes:

"Am I truly diversifying, or buying the same exposure through different wrappers?"

Building a Quant Developer Reference Librarynoreply@blogger.com (Jordi Corbilla) — Tue, 07 Apr 2026 09:43:00 +0000
For a long time, I wanted a single place that explained quantitative finance the way quant developers actually need it explained.
Not as a pure math textbook. Not as a collection of interview flashcards. Not as a random pile of disconnected notes.
I wanted something practical. Something that connects pricing theory to implementation. Something that helps you move from "I know the formula" to "I can build this correctly, test it, and trust it in production."
So I started building the Quantitative Developer Reference Library. JordiCorbilla/Quantitative-Developer-Reference-Library: Quantitative-Developer-Reference-Library
Why This ExistsA lot of great quantitative finance material already exists. The problem is not the lack of information. The problem is fragmentation.
If you are a quant developer, the knowledge you need is usually scattered across:
textbooks that go deep on theory but say little about implementation,
code samples that skip market conventions and edge cases,
desk knowledge that lives in someone's head,
internal wikis that are useful but never portable,
and years of trial and error that are expensive to repeat.
That leaves a gap between understanding the model and building the system.
In practice, that gap is where most of the pain lives:
curves built with the wrong conventions,
volatility surfaces that look smooth but produce nonsense risk,
pricing engines that work for the happy path but fail on real trades,
PnL explain that does not reconcile,
market data that is technically available but not analytically usable,
and analytics platforms that become hard to trust as they grow.
This repository is meant to close that gap.
What The Library Tries To DoThe goal is simple:
Build a practitioner-focused reference for quant developers that connects products, pricing, risk, market data, numerical methods, and production architecture.
This is not meant to be read cover to cover like a course.
It is designed to work as:
a reference you can return to when building something real,
a bridge between theory and implementation,
a map of how the major pieces fit together,
and a foundation that can keep growing over time.
What Is In The RepoThe library is organized to cover both the instrument side and the engineering side.
Core product chaptersoptions,
futures and forwards,
equities,
FX,
fixed income,
interest rates,
credit,
commodities,
and cross-asset topics.
Quant engineering chaptersmarket data,
pricing architecture,
risk and PnL,
testing and validation,
performance and production.
There is also a numerical methods chapter because, in practice, almost every serious pricing problem ends up there eventually.
The idea is that a quant developer should not need to mentally separate:
"the finance part,"
"the code part,"
and "the production part."
Those are usually the same problem, just seen from different angles.
The Point Of ViewThis repo is opinionated.
It assumes that quantitative correctness is not just about deriving the right formula. It is also about:
using the right conventions,
consuming the right market data,
choosing the right numerical method,
exposing the right risk,
and building the system so the result is reproducible and explainable.
That is why the library focuses on questions like:
What does the desk actually quote?
What data do you really need?
What assumptions are hidden in this model?
What tends to break in production?
How should this be tested?
How do you know the output is sane?
Those questions matter just as much as the equation itself.
Who It Is ForI built this primarily for:
quant developers,
engineering-minded quants,
developers moving into front-office or analytics roles,
and practitioners who want a more implementation-grounded way to study the field.
If you are preparing for interviews, building pricing libraries, working on market data or risk systems, or trying to connect multiple years of learning into one coherent framework, this should be useful.
It should also be useful to people already in the field who want a clean reference instead of searching across old notes and half-remembered documents.
What Makes It DifferentThere are plenty of resources that explain option pricing. There are plenty of resources that explain fixed income. There are plenty of resources that explain numerical methods.
What is rarer is a resource that keeps all of the following in the same frame:
product intuition,
pricing formulas,
market conventions,
implementation shape,
validation logic,
and production pitfalls.
That is the standard I want this repository to meet.
For example, an options chapter should not stop at Black-Scholes. It should also talk about:
implied volatility surfaces,
no-arbitrage checks,
surface risk conventions,
American exercise intuition,
implementation pitfalls,
and the difference between a formula that works on paper and an analytics workflow that works on a desk.
The same standard applies across rates, fixed income, credit, market data, risk, and architecture.
Why I Am Sharing It EarlyI do not want this to become a private note system that only becomes visible once it is "finished."
A library like this gets better in the open.
It improves when people use it, challenge it, extend it, and point out where the real complexity lives. Quant development is too broad, too practical, and too experience-driven for one person to pretend they can write the final word on it alone.
So I am sharing it as a growing public reference.
The current version already has the foundation:
a consistent structure,
broad chapter coverage,
deeper treatment in options, fixed income, rates, and numerical methods,
and dedicated chapters for the engineering side of quant work.
From here, the plan is to keep making it more useful.
Where I Want To Take ItOver time, I want this repository to become a serious long-term resource for the quant developer community.
That means:
deeper product coverage,
better worked examples,
more implementation patterns,
more sanity-check frameworks,
stronger cross-links between topics,
and eventually a body of material that is genuinely useful both for study and for real-world system design.
Some of the areas I especially want to deepen:
volatility modelling,
multi-curve rates,
fixed-income relative value and spread analytics,
calibration workflows,
pricing architecture patterns,
risk explain,
and the operational side of production quant systems.
If You Work In This SpaceIf you are a quant developer, quant, trader, or engineer working near pricing and risk systems, I would love for you to take a look.
Use it. Challenge it. Steal from it. Improve it.
If a section is missing something important, I want to know. If a convention should be clarified, I want to know. If there is a subtle implementation trap that every real system hits, that is exactly the kind of knowledge worth capturing here.
The best technical references are not just correct. They are useful.
That is the bar.
RepositoryIf this sounds useful, you can explore the repo here:
Quantitative Developer Reference Library
Start with:
README.md
00-overview.md
01-options.md
05-fixed-income.md
06-interest-rates.md
10-numerical-methods.md
Closing ThoughtQuant finance has no shortage of complexity. What it often lacks is structure.
The point of this library is to create more structure:
structure around the products,
structure around the implementation,
structure around the failure modes,
and structure around the knowledge itself.
If it saves someone time, helps someone build something better, or gives the community a shared reference that is more practical than what already exists, then it is worth doing.
That is the project.
Short Version For Social PostsI built a Quantitative Developer Reference Library: a practical, growing repo for quant developers that connects products, pricing, risk, market data, numerical methods, and production architecture.
It is designed to bridge the gap between "I know the formula" and "I can build this properly."
Current coverage includes options, futures, equities, FX, fixed income, rates, credit, commodities, cross-asset topics, plus market data, pricing architecture, risk/PnL, testing, and production engineering.
If you work in quant dev, pricing, risk, or analytics engineering, I would love feedback.

Building a CLI Firework Simulation in Python, Just for Fun

noreply@blogger.com (Jordi Corbilla) — Tue, 07 Apr 2026 07:36:00 +0000

Every now and then it is worth building something with no real business value at all.

JordiCorbilla/firework-simulation: firework-simulation

This terminal firework simulation was one of those projects.

It was not meant to be a serious graphics engine, a physics experiment, or a polished game. It was just a fun idea: could a terminal window, a handful of ASCII characters, and some ANSI colors feel enough like fireworks to make me smile? The answer turned out to be yes.

The basic idea is simple. A rocket launches from the bottom of the terminal, rises with velocity and gravity, bursts near its apex, and then scatters particles across the screen. Those particles fade out over time, slow down slightly, and disappear. Render that fast enough in a loop and you get something that feels lively, colourful, and surprisingly expressive for such a low-tech medium.

What makes a project like this enjoyable is that the constraints are part of the charm. A terminal is a terrible place for realistic animation. Resolution is coarse, circles are approximate, motion is chunky, and different terminals behave differently. But that is exactly why the project works best as a stylized effect rather than a realistic one. Bright colours, simple trails, exaggerated bursts, and particles fading from @ to o to * to . do more for the effect than realism ever could.

The implementation uses plain Python and ANSI escape codes, which keeps it lightweight and easy to run. There is a render loop, a small particle system, a few burst patterns, and some keyboard controls for launching rockets, triggering bursts, toggling finale mode, pausing, and quitting. Nothing too deep. Just enough structure to make the show feel varied.

I also leaned into the playful side of it. There are different shell patterns like chrysanthemum, ring, willow, palm, and crackle. Rockets leave trails. The background has stars. There is an automatic finale mode that ramps up the pace. None of this was necessary. That was the point.

Projects like this are a good reminder that programming does not always need to be optimized around utility. Sometimes it is enough to build something because it is amusing, visually satisfying, or slightly ridiculous. A CLI firework show definitely qualifies.

In the end, this was just for fun, and that is exactly why it was worth making.

If you want to try it yourself, run:

python -m fireworks

And if you want to interact with it:

space launches a rocket
r triggers a random burst
f toggles finale mode
p pauses
q quits

It is a small project, but it captures something I like about programming: sometimes a silly idea is reason enough.

Running Gemma 4 Locally on Android: Surprisingly Good

noreply@blogger.com (Jordi Corbilla) — Tue, 07 Apr 2026 07:25:00 +0000

I’ve been experimenting with on-device LLMs for a while—mostly via Ollama, OpenClaw, and various local inference stacks—but this is the first time I’ve seen something that feels actually usable on a phone without compromise.

I just tested Gemma 4 (E2B-it variant) directly on Android, and the experience is… unexpectedly solid.

TL;DR

Area	Verdict
Setup	Extremely simple (native integration)
Performance	Fast enough to feel interactive
Quality	Strong for a ~2.5GB model
UX	Clean, minimal, no friction
Practicality	Finally viable for real usage

What This Is

This is Google’s Gemma 4 model running fully on-device, exposed through an Android-native interface using LiteRT-LM.

Key characteristics:

~2.5GB footprint (E2B-it variant)
Runs entirely locally
Supports multimodal input
~32K context window
No cloud dependency
No latency spikes from network

This matters more than it sounds—because most “local LLM” setups are either:

Too heavy (desktop GPU required), or
Too slow (toy-level mobile inference)

This sits right in the middle: practical local intelligence.

First Impressions

1. Setup Experience

This is where it stands out immediately.

No:

Docker
Python envs
CUDA nonsense
CLI gymnastics

Just:

Open app
Tap download
Done

Compared to typical local setups (Ollama, llama.cpp, etc.), this is orders of magnitude simpler.

2. Performance

This is the surprising part.

Responses are fast enough to feel conversational
No obvious stalling or token starvation
Latency feels closer to edge inference than “local hack”

This suggests:

Aggressive quantization
Optimized runtime (LiteRT-LM is doing heavy lifting here)
Likely hardware acceleration (NNAPI / GPU paths)

It’s not desktop-level—but it’s good enough to actually use.

3. Model Quality

For a 2.5GB model, the quality is impressive:

Coherent reasoning
Good instruction following
Decent structure in responses
No obvious collapse under moderate prompts

Where it likely struggles (as expected):

Deep multi-step reasoning
Heavy coding tasks
Long-chain logical consistency

But for:

Notes
Quick analysis
Idea generation
Lightweight coding help

…it’s absolutely viable.

Why This Matters (Strategically)

This is bigger than just “cool mobile AI”.

1. True Edge AI Is Finally Here

We’re crossing a threshold:

Before	Now
Cloud-only intelligence	Local-first viable
Privacy tradeoffs	Fully private inference
Latency issues	Instant response
API costs	Zero marginal cost

This changes:

Enterprise workflows
Personal productivity
Privacy models

2. Cost Model Disruption

If you can run:

A good-enough model locally
With zero infra cost

Then:

Not every task needs GPT-5 / Claude Opus
You offload 70–80% of interactions locally
Cloud becomes premium tier, not default

This is exactly the direction your current stack (OpenClaw + Ollama) is already heading—this just compresses it into mobile.

3. UX Is the Real Breakthrough

The real innovation here is not the model—it’s the delivery.

Compare:

Stack	Friction
Ollama + CLI	Medium
OpenClaw + agents	High (powerful but complex)
Android Gemma app	Near zero

Who wins?
The one users can install in 30 seconds.

Where It Fits in a Serious Stack

Given your current setup (agentic + local infra), this opens interesting architecture options:

Hybrid Model Strategy

Mobile (Gemma 4)
→ Quick queries, notes, offline usage
Local Desktop (Ollama / OpenClaw)
→ Agent workflows, automation, coding
Cloud (Claude / GPT)
→ Heavy reasoning, critical tasks

This becomes a tiered inference system:

Cheap → Fast → Local
Expensive → Smart → Cloud

Limitations (Be Realistic)

This is not magic.

Constraints:

Memory-bound → limited reasoning depth
Smaller parameter count → weaker abstraction
Likely struggles with:
- complex code generation
- financial modelling
- deep system design

Hidden Tradeoffs:

Quantization artifacts
Potential hallucination under pressure
Performance tied to device hardware

Still—none of these are deal-breakers for its target use.

Opinionated Take

This is the first time I’d say:

Local LLMs on mobile are no longer a gimmick.

We’re not at parity with cloud models—but we don’t need to be.

We just need:

70% of capability
0% latency
0% cost
100% privacy

And this hits that balance.

What I’d Do Next (If You Want to Push This Further)

Given your background, this is where it gets interesting:

1. Build a Mobile → Agent Bridge

Phone handles prompts locally
Escalates complex tasks to your OpenClaw backend

2. Local RAG on Mobile

Index notes / PDFs on-device
Use Gemma as query layer

3. Trading / Quant Use Case (Lightweight)

Quick portfolio queries
Market summaries (cached locally)
Decision journaling

4. Telegram Bot + Mobile LLM Hybrid

Local inference first
Cloud fallback only when needed

Final Verdict

Dimension	Score
Innovation	8/10
Practicality	9/10
Performance	7.5/10
UX	9.5/10
Strategic impact	9/10

This is the direction everything is going.

Not bigger models.
Not more GPUs.

Smarter distribution of intelligence across edge + cloud.

Closing Thought

If this trajectory continues:

Your phone becomes your primary AI interface
Your laptop becomes your agent orchestration layer
The cloud becomes optional, not required

That’s a very different world than where we were even 12 months ago.

Build a Simple MCP Agent with OpenAI: Describe and OCR Local Images

noreply@blogger.com (Jordi Corbilla) — Sun, 05 Apr 2026 13:31:00 +0000

If you want a practical MCP example that is easy to run and easy to explain, image analysis is a great fit.

Source code: JordiCorbilla/mcp-image-analysis-agent: mcp-image-analysis-agent

In this walkthrough, we will build a minimal Model Context Protocol (MCP) setup:

An MCP server that exposes tools to list images, download files, and analyse local images
An MCP client that uses OpenAI tool-calling to decide when to call that tool
A CLI flow that returns both:
- image description
- extracted text (OCR)

This example is intentionally small so you can publish it, teach it, and extend it quickly.

What You Will Build

You will run two Python programs:

server.py: MCP server with practical tools for image workflows
client.py: OpenAI-powered agentic client that connects to the server and can invoke MCP tools

The interesting part is the split of responsibilities:

The client handles conversation, model calls, and tool orchestration.
The server handles local file access safely and image analysis logic.

Why This Is a Good MCP Example

MCP is most useful when a model needs controlled access to local capabilities. In this project:

The model cannot directly read files.
The model must call a tool exposed by your MCP server.
The server validates paths and performs the action.

That makes this architecture both practical and safer than giving direct unrestricted local access.

Prerequisites

Python 3.10+
OpenAI API key
A local image file in the lab folder (for example sample.png)

Project Files

client.py
server.py
requirements.txt

Install Dependencies

From the lab folder:

python -m pip install -r requirements.txt

Set Environment Variables

Use a .env file in the same folder:

OPENAI_API_KEY=sk-your-key-here
OPENAI_MODEL=gpt-4.1-mini
# Optional override for server-side vision model
OPENAI_VISION_MODEL=gpt-4.1-mini

Run the Demo

Start the client and point it to the server:

python .\client.py .\server.py

From the menu:

Choose Analyse Local Image (Description + OCR)
Enter an image path relative to the project folder
Optionally add a focus instruction (for example: extract receipt totals)

How the Agentic Loop Works

The client does this repeatedly:

Sends user query + available MCP tools to OpenAI.
If model requests tool calls, client executes them through MCP.
Tool results are appended back into the conversation.
Model returns final answer.

That means the model decides when to use tools, while your server decides how tools operate.

Core MCP Tools

The server exposes these core tools:

list_images_in_current_folder()
download_file_from_url(url, output_path="")
analyze_local_image(file_path, focus="")

1) List Images in the Current Folder

Use this when you want the agent to discover available images before analysis.

Example request:

List images available in this folder.

Returned data includes:

count
images[] with name, relative path, size, and modified timestamp

2) Download a File from a URL

Use this to bring an image into your project folder before analysis.

Example request:

Download https://example.com/photo.jpg to downloads/photo.jpg.

The tool restricts downloads to http/https and saves only inside your project directory.

3) Analyse a Local Image

This performs description + OCR in one pass.

Behaviour:

Validates the path stays inside the project directory.
Checks that the file exists and is a supported image format.
Converts image bytes to a data URL.
Sends image + instruction to OpenAI Vision.
Returns structured output:
- description
- extracted_text
- notable_details

Example Prompt

User asks:

Analyze image sample.png. Use MCP tools. Return a short description, extracted text, and two useful follow-up actions.

You can also run a
two-step flow:

Ask the agent to list images with list_images_in_current_folder.
Pick one and ask the agent to analyse it with analyze_local_image.

Possible response:

Description: A photographed whiteboard with sprint tasks and dates.
Extracted text: "Sprint 12, Demo Friday, Fix auth timeout"
Follow-up actions:
- Convert items into a task checklist.
- Create calendar reminders for deadline lines.

Error Handling Included

This sample handles common failures cleanly:

Missing OPENAI_API_KEY
Invalid image path
Path traversal attempts outside project folder
Unsupported image extension
Non-JSON model output fallback

Security Notes

Even in a demo, do not skip path validation.

The server uses a safe resolver that enforces all tool file access under the project root. This prevents prompts from tricking your tool into reading arbitrary files outside the workspace.

Cost and Model Tips

Start with gpt-4.1-mini for lower cost.
For higher OCR fidelity, test a stronger model in OPENAI_VISION_MODEL.
Keep outputs concise to reduce tokens.

Troubleshooting

`OPENAI_API_KEY is not set`

Add the key to .env or set it in your shell, then restart.

`Image file not found`

Use a path relative to the project folder where you run the client.

`Unsupported image extension`

Use one of: .png, .jpg, .jpeg, .webp, .gif, .bmp, .tif, .tiff.

No OCR text returned

Some images contain no readable text or low-quality text. Try a clearer image or add focus guidance.

Extension Ideas

Once this baseline works, you can add:

Batch image processing folder mode.
Structured OCR outputs (fields for receipts/invoices/forms).
A second tool to summarize OCR into action items.
Markdown report generation from analysis results.

Final Thoughts

This project is a compact, publishable MCP example that demonstrates real agent behaviour:

OpenAI handles reasoning and tool decisions.
MCP exposes local capabilities safely.
You get immediately useful output from local images.

If you are teaching MCP, this is a strong first demo before moving on to multi-tool, multi-agent workflows.

Rowlens: finding one exact CSV row in a 17 GB file without blowing up memory

noreply@blogger.com (Jordi Corbilla) — Sun, 29 Mar 2026 15:48:00 +0000

Most CSV tooling assumes the file is still small enough to load, sort, or inspect interactively. That breaks down fast once the file is measured in gigabytes. rowlens was built for the opposite case: a CLI you can point at a very large CSV when you already know the clues you are looking for and you want the exact matching rows back in a readable format.

The design constraint was simple: never read the full file into memory. rowlens opens the CSV as a stream, reads the header once, and then processes each record one at a time with Python's standard csv reader. That keeps memory usage effectively flat even when the input file is 17 GB or more. The tool does not build an index, cache rows, or attempt an in-memory dataframe workflow. It just walks the file once and stops early if you set --max-results.

The matching model is intentionally narrow for version 1.0. Repeated --keyword arguments are treated as exact cell-value matches. Repeated --filter arguments are treated as substring checks. A row is returned only when it satisfies every supplied condition. That gives a useful two-stage search pattern in practice: use --keyword for the hard identifier, then --filter to narrow the surrounding context.

Example:

rowlens --file "huge.csv" --keyword "1213131" --filter "AAA" --output "results.txt"

If a row matches, the output is not dumped as raw CSV. Instead, rowlens renders a bordered CLI report with summary metadata at the top and then a per-match table that lists each column name beside its value. That matters more than it sounds. When you are debugging a production extract or validating a record in an enormous export, the important part is not just finding the row. The important part is understanding the row immediately.

That output style was inspired by terminal-first tooling such as csv-stream-diff: strong borders, obvious sections, and tabular structure that still works in plain text when redirected to a file. The same rendered report can be written with --output, which makes it easy to attach to a ticket, share in chat, or keep as a trace artifact from an investigation.

Under the hood, Python was a good fit here because the problem is mostly streaming IO plus deterministic row checks. The package is structured with Poetry from the start so it can be shipped cleanly to PyPI. The CLI entry point lives behind the rowlens console script, dependencies are minimal, and the test suite covers the main behaviors: combined keyword and filter matching, case-insensitive search, support for extra cells beyond the header, and output-file generation.

Version 1.0 is deliberately focused. It solves one job well: find the exact row you care about in a file too large for the usual tools, then present it cleanly. Future iterations could add column-scoped matching, JSON output, compressed input support, or richer summary stats. But the first release already hits the core operational need: streaming search for massive CSVs with output that humans can read immediately.

Building sqlcsv-exporter: a Python CLI to Stream SQL Server Data into CSV

noreply@blogger.com (Jordi Corbilla) — Sat, 28 Mar 2026 22:00:00 +0000

I recently built a small Python package called sqlcsv-exporter to solve a very practical problem: export the results of a SQL Server query into a CSV file, from the command line, without dragging an entire dataset into memory.

The tool is packaged as a Poetry project, designed to be publishable to PyPI, and focused on a workflow that is common in reporting and data operations teams:

store the SQL in a .sql file
pass connection details at runtime
stream rows in chunks
write the CSV incrementally
show visible progress while the job runs

This post walks through why I built it, how it works, and what I learned while testing it against a local SQL Server instance.

The Problem

The starting point was familiar: a one-off Python script that connected to SQL Server, ran a query, and wrote a CSV. That works for quick experiments, but it gets messy fast.

Typical issues show up immediately:

query text is embedded inside Python instead of living in a .sql file
authentication logic is mixed into export logic
the script is hard to reuse across environments
large result sets become memory-heavy
the UX is poor when a query runs for several seconds or several minutes

The goal was to replace that with a proper CLI package that feels like a real tool rather than a disposable script.

The Goal

I wanted a command like this:

sqlcsv-exporter `
  --sql .\queries\report.sql `
  --output .\exports\report.csv `
  --server "DESKTOP-TTUSQLJ\SQLEXPRESS" `
  --database QuantDevTest

The requirements were straightforward:

read SQL from file
connect to SQL Server with trusted auth or SQL auth
stream the result set with fetchmany()
write CSV rows incrementally
avoid pandas for the write path
provide useful progress output
keep the package testable and publishable

The Package Structure

I split the project into small modules so each concern is isolated:

cli.py: argument parsing and process exit behavior
config.py: config model and validation
connection.py: ODBC connection string and connection creation
sql_rewriter.py: SQL file loading and optional variable rewriting
exporter.py: query execution, chunked fetch, CSV writing, and progress rendering

That separation matters because it makes the code easier to test. The CSV writer can be tested without a database. The SQL rewriting logic can be tested with simple strings. The export workflow can be tested with mocked connections and cursors.

Why Streaming Matters

The core design choice was to stream results instead of loading everything into memory.

The exporter:

opens the SQL file
optionally rewrites a declared date variable such as @InAsOfDate
executes the query with pyodbc
fetches rows in chunks
writes each chunk directly to a CSV file

That keeps the memory profile stable even when the result set gets large.

Instead of doing something like this:

rows = cursor.fetchall()
writer.writerows(rows)

the tool does this conceptually:

while True:
    rows = cursor.fetchmany(chunk_size)
    if not rows:
        break
    writer.writerows(rows)

That small change is the difference between a toy exporter and something you can trust on real datasets.

A Better CLI Experience

Command-line tools that do database work have one recurring UX problem: silence. If a query takes ten seconds, users start wondering whether the command is stuck, blocked, or dead.

So the exporter prints:

a short run summary before execution
detected column count after the query starts returning metadata
a live progress display while rows are written
a final completion summary with rows, columns, file size, and elapsed time

I used rich for the terminal output instead of hand-rolled print() calls. It gives the tool a more deliberate interface without turning it into a full TUI.

Handling SQL as a File

One design decision I liked immediately was keeping SQL in a separate file. That brings a few benefits:

the query is easier to inspect and review
analysts or DBAs can edit SQL without touching Python code
the same CLI can be reused for many exports
long or multi-step SQL scripts remain readable

For example, this simple test query lives in its own file:

SELECT TOP (1000)
    [Id],
    [Stock],
    [LowPrice],
    [MaxPrice],
    [AvgPrice]
FROM [QuantDevTest].[dbo].[StockMetrics];

That file can be passed directly to the CLI without changing the Python package at all.

Optional SQL Rewriting

Some teams keep parameter values in SQL scripts using a declared variable like:

DECLARE @InAsOfDate DATE = '2026-03-01';

To support that style, the tool includes a lightweight SQL rewriting step. If the variable exists, the CLI can replace its value based on --date. If the variable does not exist, the SQL runs unchanged.

This keeps the interface flexible:

SQL files can remain mostly static
operators can adjust date-driven exports without manually editing the file

It is intentionally narrow in scope. It is not trying to become a generic SQL templating engine.

A Real-World Bug Caught by Live Testing

The first end-to-end run against my local SQL Server instance did not succeed.

The CLI connected successfully, but then failed with:

AttributeError: 'pyodbc.Cursor' object has no attribute 'timeout'

That was useful. The mocked tests passed, but the live run exposed a compatibility assumption in the code. Some pyodbc environments expose timeout behavior differently.

The fix was simple:

try setting the timeout on the cursor if that attribute exists
otherwise fall back to the connection object

That is exactly why live testing matters. A tool can look clean in unit tests and still fail in a real environment for reasons that only surface with the actual driver and actual database connection.

Stress Testing with a Slower Query

A fast export is not a great demo for progress reporting, so I added a dedicated slow test query.

It:

copies base rows into a temp table
creates two multiplier temp tables
cross joins them to expand the result set
adds a short WAITFOR DELAY

That makes it easy to simulate a longer-running export without needing a large production-sized table.

Conceptually, the query looks like this:

SELECT TOP (1000) ... INTO #BaseStockMetrics ...
SELECT TOP (200) ... INTO #MultiplierA ...
SELECT TOP (200) ... INTO #MultiplierB ...

WAITFOR DELAY '00:00:03';

SELECT ...
FROM #BaseStockMetrics AS b
CROSS JOIN #MultiplierA AS a
CROSS JOIN #MultiplierB AS c;

With a small base table, this is enough to create a large CSV and make the progress output visible. With a large base table, it can scale very aggressively, so it is the kind of test query you use carefully.

Testing Strategy

The package includes pytest coverage around the parts that are most likely to break:

config validation
date resolution
SQL file loading
SQL variable rewriting
connection string generation
CSV writing
mocked end-to-end export behavior

That balance is important. Not every code path needs a deep integration test, but the components that define correctness should have coverage.

The live SQL Server run complements those tests by exercising:

the actual ODBC driver
the actual SQL Server instance
actual filesystem writes
real CLI behavior

Packaging for PyPI

The project is set up as a Poetry package and versioned as 1.0.1.

Build artifacts are created with:

poetry build

That produces:

a source distribution
a wheel

Those are the exact artifacts needed for publishing to PyPI.

Example Usage

Trusted connection:

poetry run sqlcsv-exporter `
  --sql .\queries\stock_metrics_top_1000.sql `
  --output .\exports\stock_metrics_top_1000.csv `
  --server "DESKTOP-TTUSQLJ\SQLEXPRESS" `
  --database QuantDevTest

SQL authentication:

poetry run sqlcsv-exporter `
  --sql .\queries\stock_metrics_top_1000.sql `
  --output .\exports\stock_metrics_top_1000.csv `
  --server "my-server" `
  --database "Reporting" `
  --sql-auth `
  --username "report_user" `
  --password "secret"

Final Thoughts

This is not a huge project, but it is a useful example of turning a script into a tool.

The interesting part was not the CSV writing itself. It was the engineering around it:

separating concerns into modules
choosing streaming over eager loading
designing a usable CLI
writing tests around the core behavior
validating the tool against a real SQL Server environment

That is usually the difference between “something that works on my machine” and “something I would actually hand to another team.”

If I extend it further, the next areas I would look at are:

environment-variable support for connection defaults
optional gzip output
row count estimates before execution when possible
better handling for very wide result sets
structured logging for scheduled runs

For now, sqlcsv-exporter does the job it was meant to do: run a SQL Server query from a file and stream the results into CSV in a way that is practical, testable, and ready to package.

Building csv-stream-diff: A Fast, Streaming CSV Comparison Tool for Very Large Files

noreply@blogger.com (Jordi Corbilla) — Sun, 22 Mar 2026 20:30:25 +0000

Comparing two CSV files sounds simple until the files are no longer small.

Once the datasets move into the millions of rows, the usual approaches start to fall apart. Loading both files into memory is expensive. Spreadsheet tools stop being useful. Even many ad hoc scripts become slow, fragile, or impossible to run reliably in production-like environments.

That is the problem I wanted to solve with csv-stream-diff.

The Problem

In real systems, CSV comparison is rarely just "diff these two files."

Usually the job looks more like this:

The files are large enough that a full in-memory load is risky or impossible
The key columns on the left and right files do not use the same names
The comparison should only consider a selected subset of columns
Duplicate keys may exist and need to be reported clearly
Sometimes a full comparison is required, but sometimes a statistically useful sample is enough
The output needs to be machine-readable so it can feed downstream validation or remediation workflows

I wanted a tool that could handle that cleanly, with minimal dependencies, and still be easy to package and run anywhere.

What `csv-stream-diff` Does

csv-stream-diff is a Python CLI tool for comparing very large CSV files using:

streaming reads
hash-based partitioning
multiprocessing
YAML-driven configuration

It produces structured output files for:

rows only on the left
rows only on the right
rows with cell-level differences
duplicate keys
summary metadata

It is designed to be practical rather than clever.

The Core Design

The main design constraint was memory.

If a tool tries to build a single giant in-memory index for both files, it will eventually hit a limit. So instead of comparing the full files at once, csv-stream-diff uses a two-phase approach.

1. Partition both files into hashed buckets

Each row key is normalized and hashed into a bucket. The left and right files are streamed row by row and written into matching bucket files on disk.

That matters because rows with the same normalized key always land in the same bucket. Once that is true, each bucket can be compared independently.

2. Compare buckets in parallel

After partitioning, the tool compares bucket pairs using multiple worker processes. Each worker only needs to index one bucket of the left file at a time, not the entire dataset.

This keeps memory bounded while still taking advantage of all available CPU cores.

The result is a design that scales much better for heavy loads than a naïve single-process implementation.

Why YAML Configuration

I did not want the CLI to become a wall of flags.

The comparison usually needs several pieces of information:

the left and right file paths
the left and right key columns
the left and right comparison columns
CSV dialect options
output paths
sampling settings
performance settings

That is much easier to manage in a YAML file than on the command line.

The CLI still supports overrides, but the YAML file is the primary contract. That makes runs reproducible and easier to version alongside data validation jobs.

Exact Sampling for Large Validation Runs

Sometimes you do not want to compare every row.

For example, if the source files contain tens of millions of records, you may want to run a fast validation pass against an exact random sample of keys before committing to a full comparison.

csv-stream-diff supports that:

sampling.size: 0 means compare everything
sampling.size > 0 means compare an exact random sample of left-side unique keys
sampling.seed makes the sample reproducible

This gives you a useful middle ground between tiny spot checks and full heavy-load comparisons.

Handling Duplicate Keys

Duplicate keys are one of the most annoying edge cases in file comparison work.

If a key appears multiple times, the comparison becomes ambiguous. Instead of failing silently or hiding the problem, the tool reports duplicate keys explicitly and continues using the first occurrence for the main comparison.

That behaviour is deliberate:

you get a warning
you get a separate duplicate-key artifact
you still get a usable comparison result

This makes the tool better suited for messy real-world data.

Keeping Dependencies Small

I wanted the runtime dependency footprint to stay minimal.

The tool is built mostly with the Python standard library. The only runtime dependency is PyYAML, which is used for configuration loading.

That keeps installation simple and reduces operational friction when the tool needs to run in different environments.

Outputs That Are Actually Useful

One important goal was to avoid producing a human-only report.

The tool writes separate output files for each class of result, which makes it easier to automate downstream processing:

only_in_left.csv
only_in_right.csv
differences.csv
duplicate_keys.csv
summary.json

The differences.csv file is especially useful because it reports cell-level differences with both the left and right column names and values.

That means you can do more than say "this row changed." You can say exactly how it changed.

Testing the Tool Properly

I also wanted the project to be easy to validate.

So the repository includes:

unit tests with pytest
BDD-style acceptance tests with behave
a fixture generator that creates two baseline-identical CSV files and then introduces controlled differences

The generator makes it easy to create realistic comparison scenarios involving:

changed values
left-only rows
right-only rows
duplicate keys

That is useful both for development and for demonstrating the tool to others.

A Few Practical Lessons

Building this reinforced a few engineering lessons:

For large-file tooling, streaming and partitioning beat clever in-memory shortcuts
Exact sampling is worth implementing properly because it gives a fast validation mode without becoming a toy feature
Duplicate handling should be explicit, not implicit
Machine-readable outputs matter as much as console output
Minimal dependencies make utility tools easier to adopt

Example Usage

With a config file in place, the tool is intentionally simple to run:

python -m csvstreamdiff.cli --config config.yaml

You can also override selected settings from the CLI:

python -m csvstreamdiff.cli --config config.yaml --sample-size 100000 --workers 8

Why I Built It

This project came from a practical need: compare large CSV datasets reliably, with clear outputs, and without depending on heavy frameworks or fragile one-off scripts.

The result is a tool that is meant to be packaged, published, and reused anywhere.

That was the bar from the start.

Closing

If you work with large exports, migration validation, reconciliation jobs, or data quality checks, CSV comparison becomes infrastructure very quickly.

csv-stream-diff is my attempt to make that infrastructure solid:

reproducible
scalable
explicit
easy to automate

If you want to explore the project, the repository includes the CLI, example configuration, test generator, and packaging setup needed to build and publish it.

Coding from Telegram: my OpenClaw + Ollama setup

noreply@blogger.com (Jordi Corbilla) — Sun, 15 Mar 2026 12:44:00 +0000

I finally got a setup working that feels a bit like the future.

I launched OpenClaw with:


ollama launch openclaw --model kimi-k2.5:cloud

and connected it to Telegram, which means I can now talk to my coding assistant directly from my phone.

What makes this especially satisfying is that the whole thing is running on a very inexpensive mini PC at home:

Mini PC, 12GB RAM + 128GB ROM, Intel Celeron J4125 (up to 2.7 GHz), Windows 10 Pro, dual Wi-Fi 2.4/5G, Bluetooth 4.2, 4K HD, 2 HDMI + 1 VGA.

Nothing exotic. Nothing expensive. Just a small, affordable box quietly sitting there, acting as the bridge between my workspace and my phone.

That is part of the appeal. This setup feels surprisingly capable for something that costs very little and, beyond the hardware I already own, is effectively free to run.

The interesting part is not just that it chats back. It has access to my workspace, can help create projects, work with files, and act more like a real development companion than a simple question-answer bot. That changes the experience completely. It stops being something I occasionally open in a browser and starts feeling more like an always-available engineering copilot.

What I like most is the shift in how and where coding can happen.

I can be away from my desk, out doing groceries, commuting, or just walking around, and still make progress. I can send a quick message to scaffold an idea, create a project structure, inspect something in the workspace, or prepare the next task before I am back in front of the machine. It turns dead time into useful time.

That is the part that feels powerful: development becomes more ambient.

Instead of waiting for the perfect focused block at a desk, I can stay connected to the flow of a project throughout the day. A thought appears, I message it. A small task comes to mind, I delegate it. A project idea starts forming, I capture it immediately. By the time I sit down again, some of the groundwork is already done.

There is also something elegant about the stack itself. Ollama provides a clean way to launch the model workflow, OpenClaw gives the agent a useful operating surface, and Telegram becomes the lightweight interface that makes it all feel natural. No heavy setup on the phone, no friction, no need to open a laptop just to move a task forward.

The other thing I genuinely like is how accessible it is. You do not need a powerful workstation, a costly hosted service, or a complex mobile setup. A cheap mini PC, a Telegram account, and the right tooling are enough to build something that feels surprisingly close to a personal remote engineering assistant.

It is still early, of course, and this kind of workflow needs trust, guardrails, and careful handling when it comes to file access and automation. But even in its current form, it already feels genuinely useful.

A coding assistant in Telegram sounds like a gimmick until it starts helping you build real things while you are standing in a supermarket queue.

That is when it stops sounding like a demo and starts feeling like a new way of working.

Tina the Destroyer: Turning Family Photos Into a Playable Arcade Game

noreply@blogger.com (Jordi Corbilla) — Sun, 08 Mar 2026 15:39:00 +0000

I built a small local arcade game called Tina the Destroyer with Python and Pygame.

The idea was simple and personal: I took pictures of my daughter, converted them into game-ready pixel sprites, and built a one-screen game around that character. The result is a fast arcade loop where Tina smashes falling rats before they hit the ground.

The Core Idea

I wanted a game that was:

Fast to play
Easy to understand
Personal and fun

So I designed a tight gameplay loop:

Move left and right
Press Space to perform a ground smash
Squash rats for points
Lose a life when a rat reaches the bottom
Game over after 3 missed rats

From Photos to Sprites

The visual pipeline started with real photos. I cleaned and adapted the character images to work as sprite sheets and exported key poses:

player_idle.png
player_smash.png

I also prepared enemy and effect assets:

rat.png
rat_squashed.png
impact.png
title.png

For audio, I added smash, miss, and looped music effects, with fallback loading so the game still runs if a file is missing.

Building the Game

The game is organized into small modules:

main.py entrypoint
game.py state machine and game loop
entities.py player, rats, and impact effects
settings.py tuning values
utils.py asset loading and fallbacks

Key features I focused on:

Clean state flow (TITLE, PLAYING, GAME_OVER, QUITTING)
Responsive movement and smash timing
Difficulty scaling over time
Score/lives HUD
Best-score persistence to JSON
Graceful fallback behavior for missing assets

Vibe Coding the Project

I vibe coded this with gpt-5-3.codex, iterating quickly on gameplay feel, tuning values, and production details (asset fallbacks, restart flow, audio handling, and UI polish).

Source code: JordiCorbilla/tina-the-destroyer: tina-the-destroyer

That pairing made it easy to keep momentum: prototype fast, test, adjust, repeat.

Why I Loved This Build

This project sits at the intersection of family creativity and engineering. It started as a fun idea with photos and ended up as a fully playable local arcade game I can run anytime with:

pip install pygame
python main.py

Small scope, real personality, and a complete game loop. Exactly the kind of build I enjoy.

Building a Portfolio CLI in 2026 (and Why CLIs Feel Cool Again)

noreply@blogger.com (Jordi Corbilla) — Sun, 15 Feb 2026 21:09:00 +0000

Over a single weekend, I decided to build a portfolio tracker that lives entirely in the terminal. Not a web app. Not a spreadsheet. A real, interactive CLI with panels, charts, and daily tracking.

I also wanted it to fit how I actually work: Excel as the source of truth, but with a console experience that makes daily updates fast and visual.

This was vibe-coded with Chat GPT-5-2-Codex over a weekend, which made it surprisingly fun to iterate on UI tweaks, edge cases, and the overall feel.

Why a CLI?

CLIs are back. Not because they're nostalgic, but because they're fast, distraction-free, and feel like tools instead of products. A good CLI lets you focus on the data and decisions rather than the UI chrome.

What I Built

The result is my-portfolio-cli, an interactive portfolio dashboard that:

Reads data from an Excel workbook.
Renders a rich TUI with Spectre.Console.
Shows daily PnL, MTD performance, and FY summaries.
Displays a simple PnL bar chart right in the terminal.
Lets you add a new daily snapshot instantly.
Creates new monthly sheets when you need them.

The Flow

Start it and it opens directly in interactive mode. Use arrow keys to move across days and months. Press A to add a new entry. If the month doesn't exist yet, it creates it automatically.

If you're starting from scratch (no workbook or no month sheets), the CLI prompts you to create the first month, add accounts, and enter initial values.

Design Notes

The key was making it feel like a real console app:

Clean layout with strong visual hierarchy.
Color-coded gains and losses.
A compact FY summary that's readable at a glance.
A minimal bar chart for quick trend cues.

It isn't about being fancy. It's about being useful and enjoyable to use every day.

What's Next

This project is going online soon, which means:

A demo workbook and screenshots.
A short walkthrough.
Possibly a minimal installer or single-file publish.

For now, it's a tight little tool that does exactly what I need.

If you want to build your own CLI tool, I highly recommend it. The feedback loop is short, and it's easy to keep refining the experience until it feels right.

Running Claude Code Fully Locally with Ollama (Yes, It’s Possible — With Caveats)

noreply@blogger.com (Jordi Corbilla) — Sun, 25 Jan 2026 17:37:00 +0000

Claude Code is designed as a cloud-first, tool-centric coding agent tightly coupled to Anthropic’s infrastructure. Out of the box, it does not support local models.

However, with a combination of:

endpoint redirection,
model aliasing inside Ollama,
and a tool-capable local model,

you can run Claude Code entirely locally against Ollama — including file edits, refactors, and shell tools.

This article documents the exact path that works, the failure modes you will hit, and the engineering trade-offs.

Why Claude Code Is Hard to Run Locally

Claude Code makes three strong assumptions:

Anthropic authentication is always available
Model names are fixed (claude-sonnet-*)
Tool calling is mandatory

Most “local Claude” guides fail because they only solve one of these.

To succeed, you must solve all three.

Architecture That Actually Works


VS Code
 └─ Claude Code extension
     ├─ hardcoded model name (claude-sonnet-*)
     ├─ mandatory tools
     └─ Anthropic-style requests
           ↓
      Ollama (localhost)
           ↓
   Tool-capable local model (Qwen)

Key insight:

You don’t change Claude Code — you adapt Ollama to look like Anthropic.

Step 1: Redirect Claude Code to Ollama

In VS Code Command palette -> Preferences: Open User Settings (JSON):


{
  "claudeCode.environmentVariables": [
    {
      "name": "ANTHROPIC_BASE_URL",
      "value": "http://127.0.0.1:11434"
    },
    {
      "name": "ANTHROPIC_AUTH_TOKEN",
      "value": "ollama"
    }
  ],
  "claudeCode.disableLoginPrompt": true
}

This bypasses cloud calls and sends all traffic to Ollama.

At this point:

UI works
Requests flow
But you will get 404 model not found

That is expected.

Step 2: Understand the Model Name Problem

Claude Code always sends model names like:


claude-sonnet-4-5-20250929

Ollama does not have such models.

You cannot configure Claude Code to use gemma, llama, or qwen directly.

Solution: Model aliasing

Ollama lets you create lightweight aliases that map one model name to another.

Step 3: Why Gemma Fails (Important)

Gemma models (including gemma3n) do not support tool calling.

Claude Code always sends a tools schema.

Resulting error:


does not support tools

This is a hard failure, not a timeout or config issue.

Conclusion

Gemma works for chat, not for Claude Code.

Step 4: Use a Tool-Capable Model

You need a model that supports:

structured tool calls
JSON responses
streaming + edits

Step 5: Create Claude-Compatible Aliases

Create a Modelfile:


FROM qwen2.5-coder:7b

Then create aliases Claude Code expects:


ollama create claude-sonnet -f Modelfile
ollama create claude-opus   -f Modelfile
ollama create claude-haiku  -f Modelfile

No weights are duplicated.
Only metadata is created.

Now Ollama can answer requests for claude-sonnet-*.

Result: Fully Local Claude Code

At this point, Claude Code can:

create files
edit files
run shell commands
refactor code
reason about repos

All without cloud access.

Building a Multi‑Agent Finance Chatbot with AG2

noreply@blogger.com (Jordi Corbilla) — Sun, 12 Oct 2025 19:23:00 +0000

Financial conversations often touch on complex markets, risk preferences and compliance constraints. A single large‑language model may struggle to handle every nuance, so AG2 (formerly AutoGen) offers a multi‑agent architecture where each agent specializes in part of the workflow. This article demonstrates how to create a finance chatbot using AG2 and Python. We will define specialised agents, orchestrate them via a group chat and show a sample interaction. The approach is inspired by multi‑agent healthcare chatbots but adapted to investment discussions.

Why multi‑agent chatbots?

Recent tutorials explain that multi‑agent chatbots divide complex interactions into specialised roles. Each agent focuses on one task—answering questions, providing recommendations or analysing data—so the overall system can handle nuanced conversations more accurately (analyticsvidhya.com). The AG2 documentation notes that multi‑agent architectures are easier to maintain and extend; they allow developers to add or remove functionality without redesigning the entire system (docs.ag2.ai). Multi‑agent designs also support different conversation patterns (sequential, group or nested chat) and enable tool use and code execution (docs.ag2.ai). In regulated industries such as healthcare or finance, this modularity improves accuracy and reduces risk (docs.ag2.ai).

Another advantage is practicality. Building a chatbot for stock‑market questions is complex, but packages like Chainlit and AG2 simplify the process by handling chat orchestration and tool calls (tinztwinshub.com). These frameworks allow you to run large‑language models locally or through an API and to register Python functions as tools (tinztwinshub.com). As open‑source models like Meta’s Llama 3.1 gain popularity, developers can deploy multi‑agent systems on local machines (tinztwinshub.com).

Pros and cons

Aspect	Pros	Cons & Considerations
Modularity	Each agent has a focused role, making the system easier to extend or modify (docs.ag2.ai).	More agents increase the number of interactions to manage and may introduce coordination overhead.
Specialisation	Domain‑specific agents can outperform a monolithic model on their task (analyticsvidhya.com).	Requires careful prompt design to keep agents within their remit and avoid conflicting advice.
Resource usage	Multi‑agent architectures can run cheaper models for some roles while leveraging larger models only where needed (docs.ag2.ai).	Running multiple models in parallel increases latency and can be costly for high‑volume workloads.
Transparency	By exposing distinct agent responses, users can understand how conclusions are derived (e.g., one agent summarises market data, another suggests allocations).	In some contexts users may prefer a single, unified answer; too much detail may confuse non‑experts.

Defining the finance chatbot agents

Our finance chatbot will engage the user to understand their goals, analyse market conditions and provide general asset‑allocation suggestions. It is not a licensed financial adviser; recommendations are for educational purposes. We adapt the roles from a mental‑health chatbot example into finance:

Client Agent – Captures the user’s financial situation, risk tolerance and investment goals.
Market Analysis Agent – Analyses the market based on user input. It summarises macro‑economic trends, asset‑class performance and volatility without giving personalised advice.
Portfolio Recommendation Agent – Suggests a high‑level asset allocation based on the analysis and user profile. It does not trade or recommend specific securities.

The roles can be summarized as follows:

Agent	Purpose	Key instructions
Client Agent	Collects information about the user’s financial goals, investment horizon and risk tolerance.	Ask the user about their objectives, constraints and any particular interests or concerns.
Market Analysis Agent	Summarises market conditions, including recent trends in equities, bonds, commodities and macro‑economic indicators.	Do not provide personal investment advice; instead, report high‑level insights such as whether markets are volatile or stable.
Portfolio Recommendation Agent	Provides general asset‑allocation suggestions based on the user’s profile and the market summary.	Recommend broad categories (e.g., 60 % equities, 30 % bonds, 10 % alternatives); include a disclaimer that this is not financial advice.

Setting up the environment

To follow along you need Python 3.11+ and the ag2 library. You can install AG2 via pip (pip install ag2[openai]). If you plan to run local models, install an API wrapper like ollama and download a model such as Llama 3.1 (tinztwinshub.com). You will also need API keys if using cloud models. In this example we configure the LLM via llm_config without specifying an API key; supply your own key as needed.

Implementing the agents

The following Python code illustrates how to create the finance chatbot. It borrows the group‑chat structure from the mental‑health example and uses AG2’s ConversableAgent, GroupChat and GroupChatManager classes:


from autogen import ConversableAgent, GroupChat, GroupChatManager

# Replace None with your OpenAI or local model API key if required
llm_config = {"config_list": [{"model": "gpt-4o", "api_key": None}]}

# 1. Client Agent: collects user goals and risk tolerance
client_agent = ConversableAgent(
    name="client",
    system_message=(
        "You are the client interface.\n"
        "Your job is to describe your financial goals, risk tolerance, investment horizon, "
        "and any budget constraints or ethical considerations."
    ),
    llm_config=llm_config
)

# 2. Market Analysis Agent: summarises current market conditions
market_analysis_agent = ConversableAgent(
    name="market_analysis",
    system_message=(
        "You analyse the current market based on the client's input."
        "Summarise macroeconomic factors (interest rates, inflation), sector trends and recent market volatility. "
        "Do not provide personalised investment advice; simply report high-level observations."
    ),
    llm_config=llm_config
)

# 3. Portfolio Recommendation Agent: proposes a high-level allocation
portfolio_recommendation_agent = ConversableAgent(
    name="portfolio_recommendation",
    system_message=(
        "You suggest a general asset allocation based on the analysis from the Market Analysis Agent."
        "Consider the client's risk tolerance and goals."
        "Recommend proportions across asset classes such as equities, bonds, and alternatives."
        "Include a disclaimer that the suggestions are educational and not financial advice."
    ),
    llm_config=llm_config
)

# Configure a group chat where the analysis and recommendation agents converse
# The manager orchestrates turn-taking in round‑robin fashion
finance_groupchat = GroupChat(
    agents=[market_analysis_agent, portfolio_recommendation_agent],
    messages=[],
    max_round=3,
    speaker_selection_method="round_robin"
)

manager = GroupChatManager(name="manager", groupchat=finance_groupchat)

# Function to start the finance chatbot

def start_finance_chat():
    print("\nWelcome to the AI Finance Chatbot!")
    user_input = input("Please describe your financial goals and risk tolerance: ")

    # The client agent initiates the conversation with the manager
    print("\nAnalysing your profile and market conditions...")
    response = client_agent.initiate_chat(
        manager,
        message=(
            f"My financial goals and risk tolerance are: {user_input}. "
            "Based on this, what insights and recommendations can you provide?"
        )
    )

    # Fallback in case the first response is empty
    if not response:
        response = portfolio_recommendation_agent.initiate_chat(
            manager,
            message="Based on the client's goals, please provide portfolio recommendations."
        )

# Run the chatbot
start_finance_chat()

How it works

User input – The client_agent collects the investor’s goals and risk tolerance. In a real deployment you might ask follow‑up questions to ensure clarity.
Market analysis – The market_analysis_agent reviews the input and provides a concise summary of current market conditions. It does not provide personalised advice, reflecting a common compliance requirement for general market commentary.
Portfolio suggestion – The portfolio_recommendation_agent uses the market summary and client profile to recommend an asset allocation. It emphasises diversification and includes a disclaimer.
Group chat management – The GroupChatManager coordinates the exchange. We use a round‑robin method to ensure both agents contribute (analyticsvidhya.com). The max_round parameter prevents infinite loops.

Sample interaction

Suppose a user says: “I’m saving for retirement in 20 years, have moderate risk tolerance and want to invest ethically.” The agents might respond as follows:

Market Analysis Agent: “Based on the current environment, central banks are signalling that interest rates may remain high to curb inflation, equities have been volatile with technology and renewable‑energy sectors outperforming, and bond yields offer moderate returns. Commodities like gold have appreciated due to geopolitical tension.”

Portfolio Recommendation Agent: “Given your 20‑year horizon and moderate risk tolerance, a diversified allocation could be 60 % equities (with a tilt towards ESG‑focused funds), 30 % bonds (combining government and investment‑grade corporate bonds), and 10 % alternatives such as real‑estate investment trusts or commodities. This is general information and not personalised financial advice.”

In a real‑world application you could register functions that fetch real‑time market data or compute portfolio statistics using AG2’s register_function API (tinztwinshub.com), but our simple example relies on the language model.

Pros and cons of this approach

Pros:
- Modularity and specialisation – Each agent has a clear purpose, which can improve the relevance and quality of responses (docs.ag2.ai). For example, one agent summarises macro data while another focuses on portfolio construction.
- Ease of extension – You can add agents to handle regulatory checks, tax considerations or portfolio rebalancing without rewriting existing components (docs.ag2.ai).
- Transparency – Users can see how the system arrives at recommendations because each agent’s contribution is visible (docs.ag2.ai).
Cons:
- Coordination overhead – More agents mean more messages and potential latency. Tuning max_round and speaker selection helps avoid long conversations.
- Prompt management – Agents must be carefully prompted to avoid stepping outside their roles. If the market‑analysis agent gives advice, it could cause compliance issues.
- Resource usage – Running multiple models or using powerful models for each agent can be costly. Techniques like mixing cheap and expensive models or limiting context length can help (docs.ag2.ai).

Future enhancements

Real‑time data integration: Register functions to call APIs (e.g., yfinance, Bloomberg, or custom data feeds) so the analysis agent can deliver up‑to‑the‑minute market summaries. The Tinz Twins example shows how to plot year‑to‑date gains using a registered function (tinztwinshub.com).
Regulatory compliance: Add an agent that checks whether recommendations adhere to regional regulations (e.g., MIFID II or SEC guidelines). It could flag issues before suggestions reach the user.
Advanced conversation patterns: Use nested or constrained group chats to handle multi‑step workflows, such as gathering risk questionnaires, performing Monte‑Carlo simulations and then generating a report. AG2 supports these patterns (docs.ag2.ai).
Multi‑modal output: Integrate charting tools to visualise asset allocations or risk/return trade‑offs. For instance, register a function that plots allocation pie charts and returns an image.

Conclusion

AG2’s multi‑agent architecture makes it straightforward to build tailored chatbots for complex domains such as finance. By dividing the conversation into specialised roles, developers can achieve greater accuracy, transparency and extensibility compared with monolithic chatbots (analyticsvidhya.com). The simple example above illustrates how you can adapt a mental‑health chatbot pattern to a personal‑finance advisor. Although multi‑agent systems introduce coordination challenges and resource overhead, careful design and modern frameworks like AG2 or Chainlit can mitigate these issues (docs.ag2.ai). As open‑source models and tooling evolve, we can expect multi‑agent finance chatbots to become more capable—potentially integrating real‑time data, compliance checks and sophisticated analytics.

Building a MiFID II Compliance Chatbot with CrewAI

noreply@blogger.com (Jordi Corbilla) — Sat, 11 Oct 2025 18:41:00 +0000

Financial regulation is notoriously complex. Investment firms must interpret and comply with lengthy documents such as the Markets in Financial Instruments Directive (MiFID II) and its companion regulation (MiFIR), while preparing for MiFID III. Compliance officers routinely pore over hundreds of pages of policy statements, ESMA Q&As and Regulatory Technical Standards (RTS). At the same time, regulators are tightening expectations: by September 2025 firms will need to implement the MiFID III amendments and be ready to demonstrate that surveillance and inducement controls work across every channel (luware.comluware.com). Manual search is inefficient and error‑prone.

This article shows how to build a MiFID II compliance chatbot using CrewAI, a multi‑agent framework. You will learn how to organise the workflow, assign tools at the agent or task level, avoid common validation errors, and anticipate upcoming regulatory changes. The techniques apply beyond finance; they illustrate a pattern for building reliable agentic systems that combine retrieval with language models.

Framework
CrewAI orchestrates multiple AI agents to search MiFID-related PDFs and draft compliance answers

Approach
Compare agent‑centric vs task‑centric tool assignment for reliability and predictability

Key Fix
Teach the language model to include the mandatory {"query": "<text>"} argument when calling the PDF search tool

Regulatory Horizon

MiFID III amendments enter force March 28 2024 with a main implementation deadline of September 29 2025 (luware.comluware.com)

New Features

CrewAI’s MCP standardises tool access and data sources (blog.crewai.com) while guardrails and event buses increase reliability (blog.crewai.comblog.crewai.com)

Agent‑centric vs Task‑centric Tool Assignment

CrewAI allows tools—such as a PDF searcher or a web search API—to be provided either to the agent as a global toolbox or to individual tasks. These two patterns affect reliability and maintainability.

Agent‑centric (Generalist)

In this common setup the agent receives a list of tools that it may call at any time. The agent decides which tool to use based on the prompt and its internal reasoning. This is flexible and quick to prototype, but it can lead to mis‑calls. For example, the PDF search tool expects a JSON argument with a query string. Without explicit instructions, the LLM may omit the argument, leading to the familiar Pydantic error:


Error: Arguments validation failed: `query` field required

When the agent owns the entire toolbox, every task must encode tool‑calling rules in its prompt to avoid such errors. In our experience this reduces predictability as the system grows; even seasoned engineers forget to repeat the tool signature in each description.

Task‑centric (Specialist)

The task‑centric approach grants tools only to the tasks that need them. When the agent begins a task it is temporarily given the required tools and cannot access others. This design leads to more predictable tool calls because the agent knows which tools are available for that job and the prompt can focus on how to use them.

In regulated domains this scoping is critical. It reduces the chance that a general‑purpose LLM will call a web search when only document evidence is allowed, and it makes unit testing straightforward: each task can be executed in isolation with its own tools and guardrails (blog.crewai.com).

Pros and Cons

Agent‑centric:
- Pros: Simple configuration; fewer moving parts; agent decides which tool to use.
- Cons: LLM may mis‑call tools without guidance; prompts must repeat tool signatures; difficult to test tasks in isolation.
Task‑centric:
- Pros: Predictable and secure; tools scoped to tasks; easier to unit‑test and update; better adherence to compliance restrictions.
- Cons: Slightly more verbose setup; requires careful mapping of tasks to tools.

Code Walkthrough

Let’s examine the core elements of the chatbot. The code below instantiates an LLM, sets up PDF search tools for each regulatory document, defines an agent with a system prompt and tool‑calling guide, and creates two tasks orchestrated sequentially by a crew. Code can be found here: (langgraph-cookbook/09 - Mifid CrewAI Chatbot at main · JordiCorbilla/langgraph-cookbook)


from crewai import Agent, Task, Crew, Process
from crewai import LLM
from crewai_tools import PDFSearchTool, SerperDevTool

llm = LLM(model="openai/gpt-4o-mini")

web_search_tool = SerperDevTool()

pdf_search_tool = PDFSearchTool(
    pdf="https://www.fca.org.uk/publication/policy/ps17-14.pdf",
    config={ 'embedder': { 'provider': 'huggingface', 'config': { 'model': 'sentence-transformers/all-MiniLM-L6-v2' } } }
)
pdf_search_tool2 = PDFSearchTool(
    pdf="https://www.fca.org.uk/publication/consultation/cp16-19.pdf",
    config={ ... }
)
pdf_search_tool3 = PDFSearchTool(
    pdf="https://www.esma.europa.eu/sites/default/files/library/2016-1452_guidelines_mifid_ii_transaction_reporting.pdf",
    config={ ... }
)

COMPLIANCE_SYSTEM_PROMPT = """
You are a MiFID II / MiFIR compliance analyst. Answer ONLY with information grounded in the provided PDFs.  Always include article‑level citations.  Prefer the latest ESMA RTS for conflicts.  No speculation.
"""

CITATION_FORMAT_PROMPT = """
Format citations as markdown footnotes: [MiFID II Art X(Y)](SOURCE_URL#page=?), [MiFIR Art X(Y)](SOURCE_URL#page=?).
"""

TOOL_CALLING_GUIDE = """
When using "Search a PDF's content", you MUST pass a JSON argument like {"query": "<short search string>"}.  Never omit 'query'.
"""

agent_centric_agent = Agent(
    role="MiFID Compliance Analyst",
    goal="Answer MiFID II / MiFIR questions with exact citations.",
    backstory="Seasoned regulatory analyst trained on MiFID II, MiFIR and FCA/ESMA RTS/Q&A.",
    tools=[pdf_search_tool, pdf_search_tool2, pdf_search_tool3, web_search_tool],
    llm=llm,
    system_prompt=COMPLIANCE_SYSTEM_PROMPT + CITATION_FORMAT_PROMPT + TOOL_CALLING_GUIDE
)

# Define tasks and crew
agent_centric_task = Task(
    description=(
        "Answer '{customer_query}'. First, search the PDFs using 'Search a PDF's content' with {\"query\": \"<your search string>\"}. Extract relevant passages and synthesise the answer."),
    tools=[pdf_search_tool, pdf_search_tool2, pdf_search_tool3],
    agent=agent_centric_agent
)

response_drafting_task = Task(
    description="Use the gathered information to draft a comprehensive response to '{customer_query}'.",
    agent=agent_centric_agent,
    context=[agent_centric_task]
)

task_centric_crew = Crew(
    agents=[agent_centric_agent],
    tasks=[agent_centric_task, response_drafting_task],
    process=Process.sequential
)

The system prompt instructs the agent to answer using only information from the PDFs, include citations, and avoid speculation. We append a tool‑calling guide that explicitly defines the JSON argument required by the PDFSearchTool. Without this guide the agent might call the tool incorrectly, causing the validation error described earlier.

The first task instructs the agent to search the PDFs for relevant text using a JSON query. The second task uses the extracted passages to draft the final answer. By assigning the PDF search tools only to the search task, we prevent accidental web queries during drafting.

Preparing for MiFID III

Our chatbot currently answers questions under MiFID II and MiFIR. However, regulatory evolution continues. MiFID III amendments were published in February 2024, entered into force in March 2024 and must be implemented by September 29 2025 (luware.com). The third iteration does not overhaul the framework but raises the bar on surveillance and inducements: compliance teams must prepare for heightened expectations around off‑channel communications and record‑keeping (luware.com). MiFID III builds on MiFID II by widening the focus to behavioural risks such as conflicts of interest and pricing opacity (luware.com), and regulators expect active monitoring rather than passive archiving (luware.com).

To stay ahead:

Integrate multi‑channel monitoring: capture voice, chat, video and messaging across platforms; apply AI to detect misconduct patterns (luware.com).
Extend the knowledge base: ingest ESMA Q&As, RTS documents and MiFID III draft texts; update embeddings regularly.
Use CrewAI’s guardrails: implement output‑length checks or hallucination detection to ensure answers remain grounded (blog.crewai.com).
Leverage event buses for audit logs and compliance evidence: CrewAI’s event bus emits events such as task started, tool use error, and LLM call completed (blog.crewai.com).
Adopt query rewriting and agentic RAG to improve retrieval. CrewAI now supports query rewriting to focus on relevant keywords and integrates with vector databases like Qdrant and Weaviate (blog.crewai.com).
Plan for MiFID III deadlines: ensure your system can adapt to new PFOF bans, stricter inducement rules, and expanded communication capture (luware.com).

Beyond Compliance – General Lessons

While this capstone project addresses a specific regulatory domain, the design patterns are broadly applicable:

Be explicit about tool signatures: LLMs cannot infer parameter names; include examples and constraints in prompts. For production systems, consider using structured tool calling (JSON Schema) or wrappers that handle input validation.
Scope tools to tasks: Minimises misuse and aids debugging. For high‑impact domains (finance, healthcare) this can be critical for legal and safety reasons.
Instrument your agents: Use CrewAI’s event bus to collect telemetry on tool use and LLM calls. This data helps debug issues and demonstrates compliance (blog.crewai.com).
Stay up to date: Regulations change. Regularly ingest new documents and search the web to supplement your knowledge base. MiFID III emphasises behaviour monitoring, so your system must adapt to detect tone and sentiment across channels (luware.com).
Embrace guardrails and RAG: Guardrails catch excessive or irrelevant outputs; agentic RAG (retrieval augmented generation) tailors the knowledge retrieval to each query, increasing precision and reducing hallucinations (blog.crewai.com).

Conclusion

By combining CrewAI’s multi‑agent orchestration with dedicated tools for PDF and web search, we built a robust MiFID II compliance chatbot. Assigning tools at the task level rather than the agent level yields more predictable and testable workflows. The critical missing‑query error was resolved by teaching the LLM to call tools correctly. Looking ahead, MiFID III will demand even greater surveillance and behavioural oversight; our modular architecture can adapt by adding new documents, query‑rewriting agents, guardrails and event logging.

Agentic AI is evolving rapidly. CrewAI’s adoption of the MCP, guardrails and event bus underscores this progress (blog.crewai.comblog.crewai.comblog.crewai.com). With careful design, developers can harness these advances to build trustworthy, compliance‑ready chatbots that empower experts rather than replace them. Start small, iterate quickly, and always validate your tools.

Automating MiFID Compliance with CrewAI

noreply@blogger.com (Jordi Corbilla) — Sat, 04 Oct 2025 19:04:00 +0000

	Regulatory context The MiFID II/III reviews introduce a single 7 % dark‑trading volume cap, ban payment for order flow (PFOF) and require Member States to ensure data‑quality standards for consolidated tape providers (legal.pwc.de). MiFID III mandates extended data fields and near‑real‑time reporting by September 2025 (asctechnologies.com). PFOF will be fully banned and a consolidated tape for equities, ETFs and derivatives will launch in June 2026 (asctechnologies.com). Key deadlines
	Member States must transpose the MiFID II/MiFIR review into national law by 28 September 2025 (legal.pwc.de). September 2025 is also the deadline for MiFID III reporting obligations (asctechnologies.com); the PFOF ban and consolidated tape come into force in June 2026 (asctechnologies.com). Challenges
	Firms face increased operational complexity: they must implement a single‑volume cap, monitor dark trading, ensure data quality for consolidated tapes and update policies and procedures (legal.pwc.de). Near‑real‑time reporting and expanded data fields demand modern IT infrastructure (asctechnologies.com). All customer conversations across channels must be recorded and analysed for misconduct, requiring AI‑powered risk detection (asctechnologies.com). Opportunities
	Greater transparency and harmonised data help investors and regulators. The EU‑wide consolidated tape offers real‑time market data (asctechnologies.com). AI and automation can transform compliance from a cost centre into a strategic differentiator: multi‑agent systems can handle large volumes of data, detect compliance risks and produce accessible reports. Automation approach
	CrewAI is a framework for building teams of autonomous agents that work together. A research agent gathers the latest MiFID updates using web‑search tools and summarises them; a writer agent turns this research into an engaging blog post. Tasks are executed sequentially, ensuring that the output of research feeds directly into writing.

Why MiFID Updates Matter

MiFID II was the EU’s flagship reform for securities markets. Seven years after its introduction, financial markets look very different: algorithmic trading, retail investing apps and AI‑assisted research have become mainstream. The European Commission therefore adopted a MiFID II/MiFIR review in February 2024. The review aims to boost transparency and investor protection by removing redundant provisions, creating a consolidated tape and banning PFOF (payment for order flow) (legal.pwc.de). Member States have until 28 September 2025 to transpose the amendments into national law (legal.pwc.de).

In parallel, the so‑called MiFID III package—an informal term for amendments to MiFID II and MiFIR—modernises the rulebook to reflect digitalisation. It requires firms to document transactions in greater detail and report them to supervisory authorities in near real time (asctechnologies.com), introduces a single 7 % dark‑trading cap (asctechnologies.com), bans PFOF (asctechnologies.com) and launches a consolidated tape for equities, ETFs and derivatives (asctechnologies.com).

These changes present both challenges and opportunities for financial institutions. On the one hand, compliance will demand investments in data governance, monitoring tools and process redesign (legal.pwc.de). On the other hand, harmonised data and advanced analytics can enhance risk management and investor confidence. Adopting multi‑agent AI systems such as CrewAI can help firms navigate this landscape efficiently.

Building a Multi‑Agent MiFID Compliance Workflow

The traditional approach to regulatory change management involves human analysts reading lengthy legislative texts, summarising them and drafting internal or external communications. This process is time‑consuming and error‑prone. CrewAI offers an alternative: you can orchestrate multiple AI agents to collaborate on complex workflows.

Below is a high‑level example of how to automate MiFID research and content creation:

Research agent – A specialist agent queries real‑time web search tools (such as Serper) for the latest MiFID II/III developments. It extracts key facts—deadlines, major amendments, compliance obligations—and generates a structured report. The report highlights the 28 September 2025 deadline for transposition (legal.pwc.de), the September 2025 start of near‑real‑time reporting (asctechnologies.com), and the June 2026 PFOF ban and consolidated tape (asctechnologies.com).
Content strategist – This agent receives the research report and crafts a reader‑friendly article. It explains why the single‑volume cap and consolidated tape matter, discusses the pros and cons of the new regime, and includes practical advice for compliance teams. It also emphasises how AI and automation can help firms handle increased data volumes and monitoring requirements (asctechnologies.com).
Workflow orchestration – A Crew object ties these agents and tasks together in a sequential process. The research task must finish before the writing task begins, ensuring that the output is coherent.

Sample Implementation

Below is a simplified Python script (see crewai_mifid_example.py) that demonstrates this workflow. It uses the CrewAI framework and assumes you have set a valid Serper API key and configured a supported large language model.


import os
from crewai import Agent, Task, Crew, Process, LLM
from crewai_tools import SerperDevTool

# Set your Serper API key
os.environ['SERPER_API_KEY'] = 'your_serper_api_key'

# Configure your LLM
llm = LLM(
    model="gtp-4",
    max_tokens=2000,
)

# Define the research agent
research_agent = Agent(
    role="MiFID Research Analyst",
    goal="Investigate and summarize recent MiFID II and III updates",
    backstory="Expert in EU financial regulation",
    verbose=True,
    allow_delegation=False,
    llm=llm,
    tools=[SerperDevTool()],
)

# Define the writer agent
writer_agent = Agent(
    role="RegTech Content Strategist",
    goal="Write an engaging article about MiFID updates and AI compliance",
    backstory="Skilled communicator for tech audiences",
    verbose=True,
    allow_delegation=True,
    llm=llm,
)

# Define tasks
research_task = Task(
    description="Gather and analyse MiFID II/III deadlines, reporting requirements and PFOF ban.",
    agent=research_agent,
    expected_output="A structured report on MiFID updates",
)
writer_task = Task(
    description="Draft a 4‑paragraph blog post based on the research.",
    agent=writer_agent,
    expected_output="A blog post summarising MiFID updates and the role of AI in compliance.",
)

crew = Crew(
    agents=[research_agent, writer_agent],
    tasks=[research_task, writer_task],
    process=Process.sequential,
    verbose=True,
)

if __name__ == '__main__':
    result = crew.kickoff(inputs={'topic': 'MiFID II and MiFID III updates 2025'})
    print(result)

Pros and Cons of Using CrewAI for Regulatory Compliance

Pros
- Efficiency and scale: AI agents can monitor regulatory updates 24/7, quickly summarising amendments like the MiFID reviews. This reduces manual labour and speeds up response times.
- Consistency: Automated pipelines deliver uniform analysis and writing quality, avoiding variability in human reporting.
- Adaptability: Changing the topic (e.g., from MiFID to ESG or AI regulation) simply requires passing a different input string; no need to redesign the workflow.
- Integrative power: Agents can be equipped with multiple tools—web search, document parsing, API connectors—allowing them to pull data from diverse sources.
Cons
- Context limitations: AI models may misinterpret nuanced legal language or miss implicit regulatory interactions. Human oversight remains essential.
- Data‑source constraints: Tools like Serper rely on publicly available information. Some proprietary regulatory databases may be inaccessible.
- Initial setup: Configuring secure LLM access and API keys requires careful attention to privacy and compliance policies.
- Regulatory liability: Over‑reliance on automated interpretations could pose risks if the system outputs incorrect advice. Always validate AI‑generated content with legal experts.

Conda Environment

To reproduce the workflow locally, create a conda environment named crew with the following specification (see environment.yml):


name: crew
channels:
  - defaults
  - conda-forge
dependencies:
  - python=3.10
  - pip
  - pip:
      - crewai==0.193.2
      - crewai-tools==0.38.0
      - langchain==0.3.20
      - langchain-community==0.3.19
      - databricks-sdk==0.57.0
      - jupyter
      - ipykernel
      - openai

Create the environment with:


conda env create -f environment.yml
conda activate crew

Install any additional models or API keys (e.g., for Serper or your chosen LLM) as environment variables.

Final Thoughts

The MiFID II/MiFIR review and the forthcoming MiFID III rules represent the biggest shake‑up of EU securities regulation since 2018. Firms must prepare for tighter reporting timelines, a 7 % dark‑trading cap and the end of PFOF. At the same time, greater transparency and harmonised data open new opportunities for data‑driven trading strategies and improved investor protection.

Leveraging frameworks like CrewAI allows compliance teams to automate the tedious parts of regulatory change management. By delegating research and writing tasks to specialised agents, practitioners can focus on high‑level analysis and strategic decision‑making. As always, technology is a tool—not a substitute for legal judgement—but used wisely it can turn regulation into a competitive advantage.

Reflection Pattern for Investment Advisory: A Fictional Take

noreply@blogger.com (Jordi Corbilla) — Sun, 28 Sep 2025 18:14:00 +0000

Reflection Pattern for Investment Advisory: A Fictional Take

This article explores how the reflection pattern, an agentic AI design pattern in which a model iteratively generates, critiques and refines its own work, can be applied to investment advisory. We’ll introduce fictional superstar advisors inspired by pop culture, explain how the reflection loop fits within an orchestrator–worker architecture, and provide a full Python implementation. Along the way, we highlight benefits, drawbacks and speculative future applications.

Summary at a Glance

Persona	Style	Typical Allocation (Equities / Alternatives / Fixed‑Income / Cash)
Bobby Axelrod	Aggressive hedge‑fund maverick willing to ride volatility	70% / 20% / 5% / 5%
Gordon Gekko	Opportunistic raider who loves leverage, options and arbitrage	75% / 15% / 5% / 5%
Richie Rich	Cautious wealth‑preserver who favours blue chips and bonds	30–60% / 10–20% / 15–45% / 5–15%

The Reflection Pattern Explained

The reflection pattern originates in cognitive science and has recently been adopted for large language models (LLMs). The idea is simple yet powerful: rather than trusting a single draft, the model runs a generate–critique–refine loop. According to Analytics Vidhya, the pattern “is a method where the model generates, critiques and refines its outputs through an iterative self‑assessment process” (analyticsvidhya.com). This loop mimics human editing, catching mistakes, clarifying ambiguities and improving quality across multiple passes (analyticsvidhya.com). A second LLM (or the same model with a different prompt) acts as a critic, evaluating the initial output against well‑defined criteria and feeding feedback back to the generator (philschmid.de).

Key steps in the reflection pattern include:

Generation: produce a first draft based on the user’s prompt. This can be done in a zero‑shot manner, generating a candidate without examples (analyticsvidhya.com).
Self‑reflection: the model reviews its own work, identifies errors, missing details or stylistic issues, and generates feedback (analyticsvidhya.com).
Iteration & refinement: the feedback is incorporated into a new draft, and the cycle repeats until the output meets quality thresholds or a maximum number of iterations is reached (tpiros.dev). Stopping conditions prevent infinite loops and include quality targets or iteration limits (analyticsvidhya.com).

Practical applications of the reflection pattern include code generation, content drafting, data analysis and decision‑making. Because the model critiques itself, it can catch inconsistencies and gradually improve the output. However, iterative generation consumes time and compute, and repeated prompts can induce drift or hallucination. A disciplined stopping criterion and robust evaluation criteria are essential.

The Orchestrator–Worker Pattern

The reflection loop fits naturally into an orchestrator–worker architecture, another agentic design pattern. In this setup, a central orchestrator decomposes a complex task into subtasks and dispatches them to specialized worker agents. The orchestrator maintains global oversight, monitors worker performance and synthesizes partial results into a final answer (dzone.com). Workers operate as domain‑specific experts, focusing solely on their assigned tasks (dzone.com).

This separation of concerns brings several benefits:

Modularity & extensibility: new worker agents can be added without rewriting the orchestrator, making the system scalable.
Parallelism: tasks can run concurrently, reducing latency and improving throughput.
Resilience: if one worker fails, the orchestrator can still produce a meaningful result from the remaining outputs (pytrick.medium.com).
Central control: centralized monitoring ensures that quality standards are enforced across workers and that fallback strategies are applied when errors occur (dzone.com).

The orchestrator–worker pattern is particularly useful for workflows that combine planning, data retrieval, analysis and synthesis. For example, in a technical stock analysis system, an orchestrator fetches data once, sends it to workers computing RSI, MACD and other indicators, then aggregates the signals into a report (pytrick.medium.com). Our fictional investment advisor will reuse this structure: the orchestrator iterates through different personas (workers), each generating an investment plan; an evaluator agent critiques the plan; and the orchestrator decides whether to accept or request another draft.

Fictional Investment Superstars

Real investment icons like Cathie Wood or Warren Buffett offer recognisable strategies, but they also introduce brand‑specific bias. To avoid conflating advice with real identities, and to show that agentic workflows can model a variety of styles, we propose three fictional personas:

Bobby Axelrod: loosely modelled on a hedge‑fund manager character. Bobby favours high‑growth sectors and alternative assets. In our template he allocates ~70 % to equities and 20 % to alternatives, leaving minimal fixed income and cash. This results in an aggressive risk grade.
Gordon Gekko: inspired by the 1980s corporate raider, Gordon prioritises concentrated bets, options and arbitrage. He rarely recommends conservative portfolios, pushing equities to 75 % and leaving a token 5 % to fixed income. Another aggressive profile.
Richie Rich: a wealthy heir who values security. Richie’s allocation varies by target grade: 60–30 % equities, 10–20 % alternatives, 15–45 % fixed income and the rest cash. He can satisfy conservative or moderate risk tolerances.

These personas serve as “workers” in our orchestrator. They each provide a distinct draft plan based on the investor’s profile and desired risk grade. A simple evaluator reads the plan, calculates the equity allocation and assigns a risk grade (conservative, moderate or aggressive). If the assigned grade doesn’t match the target, the orchestrator calls another persona to propose a new plan. After a preset number of iterations, the best plan is returned.

LLM Integration with LangChain

While deterministic templates offer repeatable outputs, they lack the spontaneity and nuance of natural language generation. To make the advisor more generative and human‑like, the latest version integrates an optional language model using LangChain’s ChatOpenAI interface. At the top of the code we attempt to import ChatOpenAI and ChatPromptTemplate. A helper function get_llm() tries to instantiate a gpt‑4o‑mini model with a moderate temperature (0.7). When this succeeds, each persona constructs a structured prompt containing the investor’s profile and target grade; the model then generates a bespoke Markdown plan with asset allocations, rationale and rebalancing advice.

The beauty of this design is its graceful fallback: if LangChain isn’t installed or the model fails to initialize (for instance, due to missing API keys), the code reverts to deterministic templates. The reflection loop and evaluator remain unchanged, so the orchestrator–worker architecture stays intact. Only the plan generation mechanism becomes dynamic when an LLM is available. This modularity demonstrates how real‑world systems can incrementally adopt generative AI without sacrificing robustness.

Code Implementation

To put these ideas into practice, we provide a fully working Python module that mirrors the reflection loop described in the Skills Network lab while swapping the real investors for our fictional superstars. The module defines a shared state dictionary, prompts for each persona, an evaluator inspired by Richie Rich’s prudence, and a simple Python loop that iteratively generates and critiques investment plans until the risk grade matches the target.

Key components include:

determine_target_grade – uses an LLM to pick a suitable risk grade for the investor based on their profile.
investment_plan_generator – produces an initial Bobby Axelrod–style plan and refines it using Gordon Gekko’s opportunistic rules when feedback exists.
evaluate_plan – calls a Richie Rich–style evaluator to classify the risk level and provide feedback on diversification, volatility and capital preservation.
route_investment – decides whether to accept the current plan or request another iteration, enforcing a maximum number of loops.
run_reflection_workflow – orchestrates the entire generate–evaluate–route cycle in plain Python without relying on LangGraph, returning the final plan along with feedback and iteration count.

Here is a high‑level sketch of the module’s structure (see langgraph-cookbook/06 - Investment Agent at main · JordiCorbilla/langgraph-cookbook for complete code):


from typing import TypedDict, Dict, Literal, Annotated
from langchain_openai import ChatOpenAI
from langchain_core.prompts import ChatPromptTemplate

grades = Literal["ultra-conservative", "conservative", "moderate", "aggressive", "high risk"]

class State(TypedDict):
    investment_plan: str
    investor_profile: str
    target_grade: grades
    feedback: str
    grade: grades
    n: int

# Initialise the LLM (gpt-4o-mini) and build prompt templates for each persona

# … Bobby Axelrod prompt and pipeline
# … Gordon Gekko prompt and pipeline with adaptation rules
# … Richie Rich evaluator prompt and structured output

def determine_target_grade(state: State) -> Dict[str, grades]:
    # Ask the LLM to choose the target risk grade based on the profile
    pass

def investment_plan_generator(state: State) -> Dict[str, str]:
    # Generate or refine the plan using Bobby or Gordon prompts
    pass

def evaluate_plan(state: State) -> Dict[str, object]:
    # Evaluate the plan with the Richie Rich evaluator
    pass

def route_investment(state: State, iteration_limit: int = 5) -> str:
    # Decide whether to accept the plan or loop again
    pass

def run_reflection_workflow(profile: str) -> State:
    # Orchestrate the reflection loop until the target grade is met or the iteration limit is reached
    pass

The complete implementation can be downloaded as custom_investment_reflection.py (file ID :agentCitation{citationIndex='0'}). This script uses LangChain’s ChatOpenAI to generate and evaluate plans, falls back gracefully if the LLM isn’t available, and demonstrates how to adapt the reflection pattern to custom personas.

Sample Execution

As an example, suppose you run run_reflection_workflow() from the custom_investment_reflection.py module with a 35‑year‑old investor earning $100 k, holding $100 k in assets, aiming to retire by 55 with a generous travel budget, and tolerating high risk. The workflow determines an aggressive target grade and iteratively refines the plan. One possible output (actual results vary slightly with the generative model) is summarised below:


🎯 Final Investment Plan Summary
========================================

📌 Investor Profile:
Age: 35
Salary: $100,000
Assets: $100,000
Goal: Retire comfortably by age 55 with ample travel budget
Risk tolerance: high

📈 Target Risk Grade: aggressive
📊 Final Assigned Grade: aggressive
🔁 Iterations Taken: 2

📝 Evaluator Feedback:
----------------------------------
This portfolio is classified as aggressive due to its heavy allocation to equities (75%) and lower commitment to fixed income.  Ensure the investor is comfortable with higher volatility and periodic drawdowns.

📃 Final Investment Plan:
----------------------------------
Gordon Gekko advises the investor to pursue an assertive course:

### Asset Allocation
- **Equities (75%)**: Concentrated bets in blue chips and cyclical industries, supplemented by option strategies.
- **Alternatives (15%)**: Distressed debt, merger arbitrage and real‑estate investment trusts.
- **Fixed Income (5%)**: Opportunistic short‑dated corporate notes.
- **Cash (5%)**: Dry powder for takeover opportunities.

### Rationale
Prioritizing blue chip equities and sector ETFs with active options overlays, complemented by distressed debt and merger arbitrage funds.  Minimal fixed income ensures capital is working hard.

### Risk Management
Use stop‑loss orders and hedges; rebalance monthly to maintain leverage discipline.

The first iteration used the Bobby Axelrod persona, which produced a 70 % equity allocation (moderate grade). The evaluator recommended increasing risk exposure, and the orchestrator rotated to Gordon Gekko, whose 75 % equity allocation met the target. The system stopped after two iterations.

Pros and Cons of the Reflection Pattern in Finance

Advantages

Improved quality through self‑critique: By iteratively evaluating its own recommendations, the advisor reduces the likelihood of omissions or contradictory allocations. It mirrors the human practice of drafting and revising (philschmid.de).
Personalisation: Different personas allow the system to explore varied strategies. Investors can compare aggressive, moderate and conservative approaches without requiring multiple human advisors.
Generative creativity: When an LLM is available, each persona can craft bespoke investment narratives instead of fixed templates. This results in plans that read more naturally and incorporate subtle nuances while still adhering to the requested risk grade.
Reduced human bias: Using fictional characters avoids overreliance on real gurus. The system still captures different risk appetites but does not misappropriate any celebrity’s actual statements.
Extensibility: New personas or evaluators can be added without changing the core loop, demonstrating the modularity of the orchestrator–worker pattern (dzone.com).
Autonomy and scalability: The loop can be run asynchronously, and evaluation metrics can be refined over time to align with regulatory guidelines or individual preferences.

Limitations

Heuristic evaluator: Our evaluation function parses simple percentages and assigns grades. Real‑world risk analysis is far more complex, involving volatility, correlation and drawdown metrics. More sophisticated evaluators (e.g., risk‑parity or Monte Carlo simulators) could improve accuracy but also increase complexity.
Computational cost: Iterative generation and evaluation consume more compute cycles and may require multiple LLM calls. For high‑frequency use cases, latency and API cost could become prohibitive.
Unpredictability: Generative models may occasionally omit required allocation details or introduce inconsistent formatting. Although the evaluator catches gross mismatches, manual review is advisable when using LLM‑generated plans.
Potential oscillations: Without careful stopping rules, the system might ping‑pong between personas or produce contradictory adjustments. Clear termination criteria and penalizing repeated mistakes are essential (analyticsvidhya.com).
Lack of external context: Our fictional personas rely on templates rather than real market data. Integrating live data feeds and dynamic modelling would make the advice more actionable but also raises regulatory and liability considerations.

Conclusion

The reflection pattern offers a simple yet powerful mechanism for improving AI outputs by letting the model serve as its own critic. When combined with an orchestrator–worker architecture, it provides a modular and extensible framework for tasks like investment advice, where balancing risk and return requires careful iteration. By experimenting with fictional personas, we avoid real‑world bias while illustrating how different risk appetites can be encoded in code. Although our current implementation uses heuristic evaluators and templated advice, it lays the foundation for more sophisticated systems that combine generative AI, financial models and ethical constraints.

Benchmarking Dynamic Quantization for Larger Language Models

noreply@blogger.com (Jordi Corbilla) — Sat, 27 Sep 2025 11:44:00 +0000

Benchmarking Dynamic Quantization for Larger Language Models

Modern language models can answer complex queries and generate high‑quality text, but they are heavy: hundreds of megabytes of weights have to be loaded into memory and millions of multiply and accumulate operations run per query. To reduce latency and cost, practitioners use optimisation techniques such as model distillation, quantization, pruning, dynamic/continuous batching, and KV‑cache reuse. When these methods are combined, costs can be slashed by up to 80 % while maintaining acceptable qualitylatitude-blog.ghost.io. This post focuses on dynamic INT8 quantization for a medium‑sized GPT‑2 model, shows the performance difference between full‑precision and quantised models, and discusses trade‑offs.

Why Quantization?

Quantization reduces the precision of a model’s weights from 32‑bit floating‑point values to 8‑bit (or lower) integers. PyTorch’s quantization documentation notes that INT8 quantization can shrink the model size and memory bandwidth by roughly 4× and that INT8 operations are typically 2–4 × faster than FP32 (docs.pytorch.org). For example, a 500‑million‑parameter model occupying 2 GB in FP32 can be reduced to 0.5 GB when quantized to INT8 (latitude-blog.ghost.io). This smaller footprint allows large language models to run on memory‑constrained devices and reduces inference latency.

Weight‑only quantization (e.g. 4‑bit AWQ or GPTQ) can improve speed even more. In real deployments, quantized LLMs show dramatic throughput gains: DeepSeek‑7B’s throughput on an NVIDIA RTX 4090 increases from 52 tokens/s to 130 tokens/s using AWQ, while Mistral‑7B on an AWS G5.xlarge instance jumps from 28 tokens/s to 88 tokens/s (latitude-blog.ghost.io). A 4‑bit GPTQ version of Llama‑3.2 1B maintained its F1 score and gained 30 % speed (latitude-blog.ghost.io).

Despite these benefits, quantization can degrade output quality if not applied carefully. Lower‑precision representations introduce rounding errors and remove representational capacity. Advanced techniques like AWQ/GPTQ mitigate this by weighting channel scaling per layer and calibrating on sample data. Our example uses PyTorch’s simple dynamic quantization, which is less powerful than weight‑only methods but easy to apply.

The Example: Measuring FP32 vs. INT8 GPT‑2

We built a script (inference_example_large.py) that loads GPT‑2 (124M parameters), processes a handful of prompts, quantizes the model dynamically, and then processes the same prompts. The key steps are:

Load model and tokenizer. We use Hugging Face’s AutoModelForCausalLM with the GPT‑2 checkpoint and its tokenizer. Because GPT‑2 lacks a padding token, we assign the end‑of‑sequence token (eos_token) as the pad token and set padding_side='left' to avoid runtime warnings.
Run FP32 inference. The script encodes a list of prompts, generates up to 50 new tokens for each, and measures total time.
Apply dynamic quantization. torch.quantization.quantize_dynamic quantizes only linear layers in the model (attention projections and feed‑forward layers). Embedding and layer‑norm parameters remain in FP32, so the model size reduction is limited.
Run INT8 inference with the quantized model and measure time.

Here is a condensed version of the code’s core logic (full code here: JordiCorbilla/langgraph-cookbook: langgraph-cookbook):


from transformers import AutoModelForCausalLM, AutoTokenizer
import torch, time, psutil

model_name = "gpt2"
dev = torch.device("cpu")

# Load and patch tokenizer (GPT-2 has no pad token)
tokenizer = AutoTokenizer.from_pretrained(model_name)
if tokenizer.pad_token_id is None:
    tokenizer.pad_token = tokenizer.eos_token
    tokenizer.padding_side = "left"

# Load full-precision model
model = AutoModelForCausalLM.from_pretrained(model_name).to(dev)
model.eval()

prompts = ["Write a poem about quantization.",
           "Why is dynamic batching useful?",  # 4 prompts total...
          ]
max_new_tokens = 50

# FP32 inference
start = time.time()
for p in prompts:
    inp = tokenizer(p, return_tensors="pt").to(dev)
    out = model.generate(
        input_ids=inp["input_ids"],
        attention_mask=inp["attention_mask"],
        max_new_tokens=max_new_tokens,
        do_sample=False,
        pad_token_id=tokenizer.eos_token_id,
    )
end = time.time()
fp32_time = end - start

# Dynamically quantize linear layers
model_int8 = torch.quantization.quantize_dynamic(
    model, {torch.nn.Linear}, dtype=torch.qint8
)

# INT8 inference
start = time.time()
for p in prompts:
    inp = tokenizer(p, return_tensors="pt").to(dev)
    out = model_int8.generate(
        input_ids=inp["input_ids"],
        attention_mask=inp["attention_mask"],
        max_new_tokens=max_new_tokens,
        do_sample=False,
        pad_token_id=tokenizer.eos_token_id,
    )
end = time.time()
int8_time = end - start

Results

Our run on a Windows laptop (CPU) produced the following numbers:

Model	Precision	Weight size	Total time for 4 prompts	Speedup
GPT‑2	FP32	~474 MB	~6.57 s	1×
GPT‑2	INT8 dynamic	~474 MB*	~5.78 s	1.14×

*Dynamic quantization only converts nn.Linear layers. Embedding and layer‑norm weights remain in FP32, so the overall model footprint does not shrink. Weight‑only quantization or AWQ/GPTQ can compress all weights and yield 4×–8× reductions (docs.pytorch.orglatitude-blog.ghost.io).

Interpretation

Modest gains on small models. On a 124M‑parameter GPT‑2, dynamic quantization offered only a 14 % speedup and no memory savings. This is because the model’s largest tensors are the embeddings and LM head, which were not quantized. Dynamic quantization shines on CPU‑bound workloads with many linear operations but yields diminishing returns on small models or GPU‑accelerated inference.
Larger models benefit more. Weight‑only quantization of big models (e.g., Llama‑3 70B) can reduce memory from 2 GB to 0.5 GB and double token throughput (latitude-blog.ghost.iolatitude-blog.ghost.io). AWQ and GPTQ compress all weights, producing 2×–4× speedups while preserving or even improving some evaluation metrics (latitude-blog.ghost.io).
Accuracy trade‑offs. Lower‑bit quantization introduces rounding error. While our 8‑bit dynamic model produced sensible text, 4‑bit quantization must be applied with care (e.g., per‑channel scaling, calibration) to avoid harming output quality. The Latitude article emphasises that quantization maintains accuracy “good enough for most applications” (latitude-blog.ghost.io), but domain‑specific tasks may require careful evaluation.

Continuous and Dynamic Batching

Quantization isn’t the only lever for faster LLMs. Dynamic or continuous batching groups multiple inference requests arriving close in time into a single batch. Instead of running one forward pass per request, the server merges them into micro‑batches and runs a single forward pass. Systems like vLLM achieve up to 23× throughput gains by continuously adding new prompts mid‑generation and sharing key/value caches across requests.

In our earlier example (with a tiny MLP), we saw that the first request took ~23 ms, while subsequent requests processed within 0.5–2 ms because they piggy‑backed on the existing batch. Continuous batching is especially powerful when serving interactive chat applications where many users send short messages concurrently.

Conclusion

Dynamic quantization is an easy way to reduce the computational cost of LLM inference, but its benefits scale with model size. Our GPT‑2 experiment shows only modest gains because embeddings dominate memory usage and remain in FP32. For significant improvements, practitioners should adopt weight‑only quantization and pair it with continuous batching, KV‑cache optimisation, and model distillation. These methods, when applied thoughtfully, can make deploying large language models feasible even in cost‑constrained environments.

ReAct, For Real: Building Deterministic Tool-Using Agents with LangGraph

noreply@blogger.com (Jordi Corbilla) — Sat, 20 Sep 2025 13:07:00 +0000

ReAct, For Real: Building Deterministic Tool-Using Agents with LangGraph

(feat. a Safe AST Calculator)

A practical guide to wiring a reason + act loop that’s auditable, stable, and observable. We use LangGraph for orchestration and a hardened AST calculator for math, no evals, no vibes.

Why this pattern

Determinism over vibes. The calculator is pure Python AST (whitelisted ops), so results are exact and testable.
Controlled loop. First model step is forced to call the tool; the second cannot call tools and must answer. No infinite ping-pong.
Observability. Streamed console output shows precisely when the LLM runs vs. when the tool runs, with token usage.

Architecture at a glance


┌──────────────┐     (tools_condition)      ┌────────────┐
│   agent LLM  │ ─────────────────────────► │  ToolNode  │
│ (forced 1st) │                            │ calculator │
└──────┬───────┘                            └─────┬──────┘
       │                                          │ ToolMessage
       │ no tool calls → END                      ▼
       │                                    ┌──────────────┐
       └─────────────────────────────────── │  agent LLM   │
                                            │ (free finish)│
                                            └──────┬───────┘
                                                   │ AiMessage (final)
                                                   ▼ END

Key primitives:

MessagesState: appends messages, preserving the OpenAI tool-calling protocol.
ToolNode: executes declared tools.
tools_condition: routes to tools only when the assistant produced tool calls.
One-tool-call policy: first LLM is bound to the calculator; the finisher LLM is tool-free.

The safe calculator (snippet)

Goal: evaluate math deterministically, with a tiny NL preprocessor.


# Whitelisted ops only
_ALLOWED_OPS = {ast.Add: op.add, ast.Sub: op.sub, ast.Mult: op.mul,
                ast.Div: op.truediv, ast.Pow: op.pow, ast.Mod: op.mod,
                ast.UAdd: op.pos, ast.USub: op.neg}

def _preprocess(s: str) -> str:
    s = s.strip().lower()
    s = re.sub(r"\b(please|thanks|thank you|what\s*is|what's|calculate|compute|equals?)\b", "", s)
    s = re.sub(r"\bthe\b", "", s)
    s = re.sub(r"\bplus\b", "+", s); s = re.sub(r"\bminus\b", "-", s)
    s = re.sub(r"\btimes\b", "*", s); s = re.sub(r"\bdivided by\b", "/", s)
    s = re.sub(r"\b(?:the\s+)?square root of\b", "sqrt(", s)
    s = re.sub(r"√\s*", "sqrt(", s)
    s = re.sub(r"sqrt\(\s*([0-9\.]+)\s*\)?", r"sqrt(\1)", s)
    s = re.sub(r"(\d+(?:\.\d+)?)\s*%\s*of\s*([0-9\.]+)", r"(\1/100*\2)", s)
    s = re.sub(r"(\d+(?:\.\d+)?)\s*%", r"(\1/100)", s)
    return s.replace("^", "**").strip()

def _eval_ast(node: ast.AST) -> float:
    if isinstance(node, ast.Constant) and isinstance(node.value, (int, float)):
        return float(node.value)
    if isinstance(node, ast.UnaryOp) and type(node.op) in _ALLOWED_OPS:
        return _ALLOWED_OPS[type(node.op)](_eval_ast(node.operand))
    if isinstance(node, ast.BinOp) and type(node.op) in _ALLOWED_OPS:
        return _ALLOWED_OPS[type(node.op)](_eval_ast(node.left), _eval_ast(node.right))
    if isinstance(node, ast.Call) and isinstance(node.func, ast.Name) and node.func.id == "sqrt" and len(node.args) == 1:
        return math.sqrt(_eval_ast(node.args[0]))
    if isinstance(node, ast.Expr):
        return _eval_ast(node.value)
    raise ValueError("Unsupported syntax.")

Tool wrapper:


@tool("calculator_tool")
def calculator_tool(expression: str) -> str:
    try:
        pre = _preprocess(expression)
        value = _eval_ast(ast.parse(pre, mode="eval").body)
        return str(float(value))
    except Exception as e:
        return f"Error: {e}"

Why this is safe: Only numeric literals and whitelisted operators/functions are allowed; no names, attrs, or imports can ever execute.

LangGraph wiring (snippet)

Bind two LLM phases: forced first (must call calculator) and free finish (no tools bound).


llm_forced_first = ChatOpenAI(...).bind_tools(
    [calculator_tool],
    tool_choice={"type":"function","function":{"name":"calculator_tool"}}
)
llm_free = ChatOpenAI(...)

def _has_calc_tool_call(msgs) -> bool:
    return any(isinstance(m, ToolMessage) and getattr(m,"name","")=="calculator_tool" for m in msgs)

def agent_node(state: MessagesState):
    first_phase = not _has_calc_tool_call(state["messages"])
    llm = llm_forced_first if first_phase else llm_free
    ai = llm.invoke([SystemMessage(content=SYSTEM_RULE), *state["messages"]],
                    config={"tags": ["agent_llm", "forced_first" if first_phase else "free_finish"]})
    return {"messages": [ai]}

tool_node = ToolNode([calculator_tool])

g = StateGraph(MessagesState)
g.add_node("agent", agent_node)
g.add_node("tools", tool_node)
g.add_conditional_edges("agent", tools_condition, {"tools": "tools", "__end__": END})
g.add_edge("tools", "agent")
g.set_entry_point("agent")
graph = g.compile()

Why it ends cleanly: After tools run, the graph goes back to the agent once to produce the final answer; tools_condition routes to END if no tool calls are present.

Observability: know exactly when the LLM is used

Add a tiny callback to print LLM start/end and token usage; gate with DEBUG_AGENT=1.


class ConsoleLLMHandler(BaseCallbackHandler):
    def on_llm_start(self, serialized, prompts, **kw):
        if os.getenv("DEBUG_AGENT")=="1":
            print(f"[LLM START] {serialized.get('name','LLM')} | tags={kw.get('tags',[])}", file=sys.stderr)
    def on_llm_end(self, result, **kw):
        if os.getenv("DEBUG_AGENT")=="1":
            print(f"[LLM END] tags={kw.get('tags',[])} | usage={(result.llm_output or {}).get('token_usage',{})}", file=sys.stderr)

handler = ConsoleLLMHandler()
llm_forced_first = ChatOpenAI(..., callbacks=[handler]).bind_tools(...)
llm_free = ChatOpenAI(..., callbacks=[handler])

Optional: DEBUG_CALC=1 prints NL → normalized math expression for the tool.

Running it


export OPENAI_API_KEY=sk-...
# telemetry on:
export DEBUG_AGENT=1
export DEBUG_CALC=1

python calculator_agent.py "Calculate 12% of 255 plus the square root of 244"

Sample (trimmed) output:

================================ Human Message =================================

Calculate 12% of 255 plus the square root of 244

[LLM START] ChatOpenAI | tags=['seq:step:1', 'agent_llm', 'forced_first']
[LLM END] tags=['seq:step:1', 'agent_llm', 'forced_first'] | usage={'completion_tokens': 14, 'prompt_tokens': 161, 'total_tokens': 175, 'completion_tokens_details': {'accepted_prediction_tokens': 0, 'audio_tokens': 0, 'reasoning_tokens': 0, 'rejected_prediction_tokens': 0}, 'prompt_tokens_details': {'audio_tokens': 0, 'cached_tokens': 0}}
================================== Ai Message ==================================
Tool Calls:
  calculator_tool (call_134y7dqSU2udc2rr0OTNHKQs)
  Args:
    expression: 12% of 255 plus sqrt(244)

================================= Tool Message =================================
Name: calculator_tool

46.2204993518133

[LLM START] ChatOpenAI | tags=['seq:step:1', 'agent_llm', 'free_finish']
[LLM END] tags=['seq:step:1', 'agent_llm', 'free_finish'] | usage={'completion_tokens': 23, 'prompt_tokens': 121, 'total_tokens': 144, 'completion_tokens_details': {'accepted_prediction_tokens': 0, 'audio_tokens': 0, 'reasoning_tokens': 0, 'rejected_prediction_tokens': 0}, 'prompt_tokens_details': {'audio_tokens': 0, 'cached_tokens': 0}}
================================== Ai Message ==================================

The result of 12% of 255 plus the square root of 244 is approximately 46.22.

Design choices: pros & cons

Pros

Deterministic math; no LLM hallucinations for arithmetic.
Single tool call guarantees predictable latency and flow.
Great DX: streaming, token accounting, and NL conveniences (% of, √, word operators).

Cons

Narrow by design (sqrt, basic ops). Extend via whitelist if you need log/exp/pi/e.
Requires an LLM key for orchestration (the math itself is local).
NL preprocessor is conservative to keep parsing predictable.

Code & assets

Source: $https://github.com/JordiCorbilla/langgraph-cookbook$

Snippet appendix

System rule (keeps the agent honest)


SYSTEM_RULE = (
  "You are a math assistant. For ANY numeric computation, "
  "call `calculator_tool` exactly once, then return the final answer. "
  "Do not call tools again after you have the numeric result."
)

Smoke test idea


# Expect: ≥2 AI messages (forced+final), exactly 1 ToolMessage, final AI has no tool_calls

A Practical, Production-Ready Tool for Summarizing YouTube Videos with LLMs and Agents

noreply@blogger.com (Jordi Corbilla) — Sun, 14 Sep 2025 11:57:00 +0000

A Practical, Production-Ready Tool for Summarizing YouTube Videos with LLMs and Agents

This post is about a tool. It’s a CLI that uses LLM tool calling and a tiny agent loop to extract IDs, fetch transcripts/metadata, and produce high-quality summaries of long YouTube videos without tripping rate limits or context windows.

TL;DR

What it is	Why it’s useful	How it works	How to run
A CLI tool that summarizes YouTube videos using an LLM with tools/agents	Handles long videos and real-world edge cases (no transcript, quotas)	LangChain tool calling+ fixed/recursive chains + chunked map-reduce summarization + bare-LLM finalization	`python youtube_tool_agent.py summarize --url "<video-url>" --language en`

What this tool does

Extracts YouTube video IDs (robust to watch?v=, youtu.be/, embed/)
Fetches transcripts (and can be extended to fall back to captions/description via yt-dlp)
Pulls metadata & thumbnails via yt-dlp (title, views, likes, chapters, image sizes)
Searches YouTube by query (PyTube)
(Best-effort) Trending by region
Generates succinct, expert-oriented summaries of long videos using a chunked map-reduce flow that avoids TPM/context explosions
Includes a CLI and verbose tracing so you can see exactly what the agent is doing

Install & first run


# Python 3.11+ recommended
pip install -r requirements.txt

# Set your model key (OpenAI shown)
export OPENAI_API_KEY="sk-..."   # Windows PowerShell:  $env:OPENAI_API_KEY="sk-..."

# Summarize a video
python youtube_tool_agent.py --verbose summarize \
  --url "https://www.youtube.com/watch?v=8TJQhQ2GZ0Y" \
  --language en

You’ll see progress like:


[LLM] OpenAI provider model=gpt-4o provider=openai
[SUM] Chunk 1/2 (30000 chars)
[SUM] Chunk 2/2 (22007 chars)
<final polished summary printed here>

Why agents for this problem?

A “just call an API and prompt” script breaks on real-world YouTube:

Some videos have no official transcript (only auto-captions or nothing).
Transcripts can be huge, exceeding model context or your org’s TPM limits.
Tool-calling models often respond with empty content + a request to call another tool, unless you orchestrate correctly.

An agent (even a tiny one) solves this:

It decides which tool to call and in what order (ID → transcript → metadata → summarize).
It loops until it has what it needs (recursive chain), then finalizes the answer.
You get traceability: every tool call is logged with payload sizes so you can reason about cost and latency.

Core ideas (architectural choices that matter)

1) Tool calling (LangChain)

We expose capabilities as annotated tools the model can call by name:

extract_video_id, fetch_transcript, get_full_metadata, get_thumbnails, search_youtube, get_trending_videos.

These functions return plain JSON/strings, which keeps the glue simple and makes debugging obvious.

Source code can be found here:
JordiCorbilla/langgraph-cookbook: langgraph-cookbook

2) Two orchestration modes

Fixed chain for deterministic summarize:
1. Extract ID → 2) Fetch transcript → 3) Summarize (chunked) → 4) Polish (bare LLM)
Universal (recursive) chain for open “ask”:
- Keep calling tools while the model requests them. Stop when it returns text.

3) Chunked map-reduce summarization

Why: long transcripts blow up context and TPM.
How: split the transcript into overlapping chunks → summarize each chunk (map) → merge the bullet lists (reduce) → optional polish for clarity.

Key tunables:

Chunk size: 3k–4k chars (or larger if you have headroom)
Overlap: 200–300 chars
Short sleep between chunk calls to smooth TPM bursts

4) Bare-LLM finalization

Tool-calling models often return empty content when they want another tool. The final step uses a bare LLM (no tools bound). That forces a textual answer and prevents “one more tool?” loops.

Architecture at a glance


┌──────────────┐      ┌───────────────────────┐
│  CLI (args)  ├────▶ |  Orchestrator Chain   │
└─────┬────────┘      └──────────┬────────────┘
      │                           │  tool_calls
      │                           ▼
      │                 ┌─────────────────────┐
      │                 │  Tools (LangChain)  │
      │                 │  - extract_video_id │
      │                 │  - fetch_transcript │
      │                 │  - search_youtube   │
      │                 │  - get_full_metadata│
      │                 │  - get_thumbnails   │
      │                 └──────────┬──────────┘
      │                            │ results (text/JSON)
      │                            ▼
      │                   ┌─────────────────┐
      │                   │  Bare LLM Call  │  ← no-tools finalization
      │                   │ (map→reduce→polish)
      ▼                   └─────────────────┘
  stdout (summary)

Why “bare” LLM at the end? Tool-calling models often return empty content when they still want to call tools. Finalizing with a no-tools model guarantees text.

CLI you’ll actually use

Point tools (fast, no LLM):


python youtube_tool_agent.py metadata   --url "https://youtu.be/8TJQhQ2GZ0Y"
python youtube_tool_agent.py thumbnails --url "https://youtu.be/8TJQhQ2GZ0Y"
python youtube_tool_agent.py search     --query "Retrieval-Augmented Generation"
python youtube_tool_agent.py trending   --region GB

Deterministic, chunked summary:


python youtube_tool_agent.py --verbose summarize \
  --url "https://www.youtube.com/watch?v=8TJQhQ2GZ0Y" \
  --language en

Agentic “do what it takes”:


python youtube_tool_agent.py --verbose ask \
  --query "Summarize this YouTube video and explain the leveraging strategy (en): https://www.youtube.com/watch?v=8TJQhQ2GZ0Y"

Under the hood (high-level)


CLI → Orchestrator
  ├─ Fixed chain (summarize): ID → transcript → map→reduce→polish (bare LLM)
  └─ Universal chain (ask): recurse while the model returns tool_calls
Tools (LangChain @tool)
  ├─ extract_video_id
  ├─ fetch_transcript  (YouTubeTranscriptAPI; optional yt-dlp captions fallback)
  ├─ get_full_metadata, get_thumbnails
  ├─ search_youtube, get_trending_videos (best-effort)
Finalization
  └─ Bare LLM (no tools) → guaranteed text

Why the fallback? In production you’ll meet videos with no official transcript. Add a yt-dlp captions fallback and, as a last resort, summarize metadata/description so you always produce something useful.

Operational tips (so it stays fast and cheap)

TPM discipline: throttle chunk calls with short sleeps; prefer smaller models for map steps, then a slightly stronger model for merge/polish.
Chapters-aware chunking: if yt-dlp returns chapters, chunk on chapter boundaries first—better topical coherence and fewer duplicates.
Cache transcripts/metadata to disk (simple JSON files). You’ll save both time and money on reruns.
Observability: log tool names and payload sizes. When costs drift, you’ll know why.

Closing thoughts

This is a tool designed for the messiness of real YouTube content. The combination of tool calling, a minimal agent loop, chunked summarization, and bare-LLM finalization makes it predictable, debuggable, and resilient. You can drop it into a pipeline today and get reliable results on long videos.

Querying and Plotting Data with LangChain’s Pandas Agent + OpenAI

noreply@blogger.com (Jordi Corbilla) — Sun, 31 Aug 2025 20:17:00 +0000

Querying and Plotting Data with LangChain’s Pandas Agent + OpenAI

Natural language interfaces for data analysis are moving from research into everyday engineering practice.
With LangChain and OpenAI, you can now query a DataFrame directly in English, let the model write and execute the Pandas/Matplotlib code, and even plot results, all inside Python.

In this post, I’ll show you how I built a Pandas DataFrame Agent with LangChain + OpenAI that can:

Answer tabular questions about a dataset.
Generate Python plotting code automatically.
Execute that code safely to produce charts.

🔧 Setup

We need a few packages:


pip install langchain langchain-openai langchain-experimental pandas matplotlib

And of course, set your OpenAI key:


export OPENAI_API_KEY=...

📊 The Dataset

For demo purposes, let’s mock up some sales data:


import pandas as pd

data = {
    "month": ["2025-01","2025-02","2025-03","2025-04","2025-05","2025-06"],
    "region": ["EMEA","EMEA","EMEA","AMER","AMER","APAC"],
    "units":  [120, 150, 130, 200, 180, 160],
    "price":  [10.0, 10.0, 10.0, 12.0, 12.0,  9.0],
}
df = pd.DataFrame(data)
df["revenue"] = df["units"] * df["price"]

🤖 Creating the Agent

The magic comes from create_pandas_dataframe_agent.
This wraps the DataFrame in a tool the LLM can call with code execution:


from langchain_openai import ChatOpenAI
from langchain_experimental.agents.agent_toolkits import create_pandas_dataframe_agent

llm = ChatOpenAI(model="gpt-4o-mini", temperature=0)

agent = create_pandas_dataframe_agent(
    llm=llm,
    df=df,
    agent_type="openai-tools",
    verbose=False,  # cleaner logs
)

🔎 Asking Questions in English

Now you can query the data without touching Pandas:


resp = agent.invoke({
    "input": "Compute total revenue by region as a tidy table sorted descending."
})
print(resp["output"])

Output:


| region | revenue |
|--------|---------|
| AMER   | 4560.0  |
| EMEA   | 4000.0  |
| APAC   | 1440.0  |

The agent generated and executed the Pandas code under the hood.

📈 Asking for a Plot

We can go one step further — ask the model to plot monthly revenue:


plot_code = """
import pandas as pd
import matplotlib.pyplot as plt
from pathlib import Path

df['month'] = pd.to_datetime(df['month'])
monthly_revenue = df.groupby('month')['revenue'].sum()

plt.figure(figsize=(10, 5))
plt.plot(monthly_revenue.index, monthly_revenue.values, marker='o')
plt.title('Monthly Revenue Over Time')
plt.xlabel('Month')
plt.ylabel('Total Revenue')
plt.grid()
plt.xticks(rotation=45)
plt.tight_layout()

out = Path('monthly_revenue.png')
plt.savefig(out)
print(f'Chart saved to: {out.resolve()}')
"""
agent.invoke({"input": f"Execute this exact code:\n```python\n{plot_code}\n```"})

This produces:

🚀 Why This Matters

This pattern unlocks:

Rapid ad-hoc analytics: Ask questions in English, get code + charts.
Non-technical users can explore data without writing Pandas.
Bridges RAG + analytics: Instead of only text retrieval, you can augment LLMs with structured data queries.

Of course, for production you’d want guardrails (e.g., AST linting before execution, schema checks, sandboxing). But as a prototyping tool, this workflow is incredibly powerful.

Source code can be found here: JordiCorbilla/langgraph-cookbook: langgraph-cookbook

Building a Tiny LangGraph Agent with a Tool: A Weather-Aware Trip Planner

noreply@blogger.com (Jordi Corbilla) — Sun, 31 Aug 2025 19:57:00 +0000

Building a Tiny LangGraph Agent with a Tool: A Weather-Aware Trip Planner

Most agent demos are either too simple (toy calculators) or too complex (enterprise-scale pipelines).
Here’s a middle ground: a 5-node LangGraph agent that builds a half-day itinerary for a city, adapts to weather, respects user preferences, and calls a real tool along the way.

Why this example?

Small, visualizable graph: plan → weather → search → pick → draft → finalize
Conditional routing: rainy → indoor picks, sunny → outdoor picks
Real tool usage: random_weather is a LangChain tool, called explicitly from the graph
Typed state with Pydantic v2
Optional LLM for nicer itinerary text (but not required), this example used OpenAI
Two runnable scenarios: London (rainy) and Barcelona (sunny)

Architecture

Nodes
- plan: log initial context
- weather: calls random_weather tool → Weather state
- search: load city places
- pick: filter by weather & prefs (budget, dislikes)
- draft: generate itinerary text
- fallback: relax prefs if nothing chosen
- finalize: wrap up
Edges
- Normal path: plan → weather → search → pick → draft → finalize
- Fallback path: pick → fallback → draft → finalize

The Weather Tool


from langchain_core.tools import tool
import random

@tool
def random_weather(city: str) -> dict:
    """
    Return randomized weather for the city.
    """
    conditions = ["sunny", "cloudy", "rain", "storm"]
    cond = random.choice(conditions)
    low, high = (12, 30)
    return {
        "city": city,
        "condition": cond,
        "high_c": float(random.randint(20, high)),
        "low_c": float(random.randint(low, 19))
    }

And in the weather_node:


def weather_node(s: GraphState) -> GraphState:
    w = random_weather.invoke({"city": s.city})  # tool call
    s.weather = Weather(**w)
    s.audit.append(
        f"weather: {s.weather.city} {s.weather.condition} "
        f"{s.weather.high_c}/{s.weather.low_c}°C"
    )
    return s

Full code can be found here -> JordiCorbilla/langgraph-cookbook: langgraph-cookbook

Example Run

Scenario A: London, dislikes museums, free-only budget


=== Scenario A: London + dislikes=['museum'], free_only ===
[Node] plan
[Node] weather
[Tool] random_weather(London) -> {'city': 'London', 'condition': 'sunny', 'high_c': 30.0, 'low_c': 28.0}
[Node] search
[Node] pick
[Node] draft
[Node] finalize
plan: city=London, half_day=morning, date=2025-08-31
weather: London sunny 30.0/28.0°C
search: 5 candidates
pick: Thames Riverside Walk, Hyde Park Loop, Sky Garden
draft: itinerary ready
finalize: done

Itinerary:
 - **Time:** 9:00 AM - 10:00 AM
 - **Tip:** Begin your day with a refreshing stroll along the river. Enjoy the views and the morning sun. Bring water and wear sunscreen!
 - **Transport:** Take the Tube from Embankment Station to Lancaster Gate (Circle or District Line).
 - **Tip:** This journey takes about 15 minutes. Consider grabbing a coffee from a nearby café before heading to the park.
 - **Time:** 10:15 AM - 11:30 AM
 - **Tip:** Enjoy the beautiful greenery and perhaps find a shaded spot to relax. Look out for the Serpentine Lake and the Diana Memorial Fountain.
 - **Transport:** Take the Tube from Lancaster Gate to Monument Station (Circle or District Line).
 - **Tip:** Allocate about 30 minutes for travel and check-in. Arrive by 11:45 AM to enjoy the stunning views of London.
 - **Time:** 12:00 PM - 12:45 PM
 - **Tip:** Enjoy a drink or snack at the café while taking in panoramic views of the city. Make sure to book your free entry in advance to avoid long waits!
Notes: Weather: sunny

Scenario B: Barcelona, no dislikes, mixed budget


=== Scenario B: Barcelona + no dislikes, mixed budget ===
[Node] plan
[Node] weather
[Tool] random_weather(Barcelona) -> {'city': 'Barcelona', 'condition': 'sunny', 'high_c': 29.0, 'low_c': 26.0}
[Node] search
[Node] pick
[Node] draft
[Node] finalize
plan: city=Barcelona, half_day=afternoon, date=2025-08-31
weather: Barcelona sunny 29.0/26.0°C
search: 5 candidates
pick: La Sagrada Família (Exterior), Gothic Quarter Stroll, Park Güell
draft: itinerary ready
finalize: done

Itinerary:
 - **Start at La Sagrada Família (3:00 PM - 3:45 PM)**
 - Arrive early to admire the stunning exterior of this iconic basilica. Take photos and enjoy the intricate details of Gaudí's masterpiece.
 - **Gothic Quarter Stroll (4:00 PM - 5:00 PM)**
 - Take a short taxi or tram ride (about 10-15 minutes) to the Gothic Quarter. Wander through the narrow streets, explore hidden squares, and admire the medieval architecture.
 - **Park Güell (5:15 PM - 6:45 PM)**
 - Head to Park Güell via taxi or public transport (approximately 15-20 minutes). Enjoy a leisurely walk through the park, taking in Gaudí's colorful mosaics and panoramic views of the city.
 - **Transport:** Use taxis or rideshare apps for quick transfers between locations, especially in the heat.
 - **Hydration:** Bring water to stay hydrated, as temperatures can be high.
 - **Footwear:** Wear comfortable shoes for walking on cobblestone streets and park paths.
Notes: Weather: sunny

Why this matters

Graph, not guesses: deterministic orchestration
Tools in action: explicit .invoke() calls with visible output
Policy in code: dislikes, budget filters, weather routing
Verbose logs: you can follow the agent step by step

Pros & Cons

Pros

Compact, easy-to-follow
Demonstrates both nodes and tools
Works with or without an LLM
Great for teaching graph concepts

Cons

Weather is mocked/randomized
Places are static, not from real APIs
No travel-time optimization

How to run


python trip_agent.py

Scenario A: London, free-only, dislikes museums → rainy picks
Scenario B: Barcelona, mixed budget → sunny picks

Build Your Own Local Copilot in VS Code with Continue + Ollama (CodeLlama‑7B)

noreply@blogger.com (Jordi Corbilla) — Tue, 22 Apr 2025 08:24:00 +0000

Build Your Own Local Copilot in VS Code with Continue + Ollama (CodeLlama‑7B)

TL;DR — In under 30 minutes you can have a fully‑offline, ChatGPT‑style coding assistant that reads your entire codebase and never leaks a byte to the cloud.

1 · Why bother?

Privacy first — No proprietary code leaves your laptop.
Low latency — Replies stream in milliseconds, not seconds.
Free — No API keys, no per‑token billing.
Hackable — Swap models, add custom prompts, or fine‑tune later.

2 · What we’ll build

A local stack where:

Ollama runs the codellama:7b model at http://localhost:11434.
Continue in VS Code chats with that model.
Continue indexes all your repositories so you can ask questions like:
“Where do we create the AWS SQS client?”

3 · Prerequisites

Item	Minimum
OS	Windows 11 22H2+
RAM	16 GB (32 GB recommended)
GPU (optional)	NVIDIA card with ≥ 8 GB VRAM & latest CUDA driver
WSL 2	Auto‑installed by Ollama if missing
VS Code	1.88 or newer

4 · Install Ollama

Download the Windows installer from https://ollama.ai/download/windows.
Run the MSI and accept defaults.
Verify the CLI:
```
ollama --version   # e.g. v0.1.32
```

**Heads‑up ** — The installer registers Ollama as a Windows service and listens on port 11434.

5 · Pull CodeLlama‑7B

ollama pull codellama:7b    # 4‑bit Q4_0 fits in 8 GB RAM

You’ll see a 100 % progress bar; the model lives in %USERPROFILE%\.ollama\models.

6 · Install Continue for VS Code

Open VS Code → Extensions.
Search “Continue” by Continue.dev and click Install.
Reload VS Code; a sunflower icon shows up in the Activity Bar.

7 · Point Continue at Ollama

Click the sunflower icon → gear ⚙ → Settings.
Choose Model Provider: Custom.
Fill the fields:
Field Value
Provider ollama
Base URL http://localhost:11434
Model codellama:7b
Press Save.

(This writes the same keys to your settings.json.)

8 · Index your repositories (no training required)

Add one line to User or Workspace settings:

"continue.directoryContext": [
  { "path": "D:/code", "depth": 4, "maxFiles": 25000 }
]

Continue walks the tree once, stores embeddings in %APPDATA%\continue\index, and keeps them fresh in the background.

9 · Smoke‑test the setup

Press Ctrl + Shift + L to open chat.

Type:

@Codebase Which file defines the KafkaConsumer settings?

The reply should include a Context block listing real file paths.
Optional: enable the Continue Console (Settings → Enable Console) to watch retrieved files live.

10 · Tame hallucinations (optional but recommended)

Add this to settings.json:

"continue.systemMessage": "You are a senior full‑stack engineer. Answer concisely and reference only provided context. If unsure, say 'IDK'.",
"continue.modelOptions": {
  "temperature": 0.2,
  "top_p": 0.9,
  "repeat_penalty": 1.1
}

11 · Daily cheat‑sheet

Task	How
Explain selected code	Select → right‑click → Continue: Explain
Generate tests	Same menu → Generate Tests
Inline autocomplete	Toggle Tab Autocomplete in Continue footer
Force retrieval	Prefix prompt with `@Codebase`, `@File`, or `@Folder`

12 · Troubleshooting

Symptom	Fix
`connect ECONNREFUSED 11434`	Tray → Start Ollama Service or `Start‑Service Ollama`
Model OOM on pull	Use quantised tag: `codellama:7b:Q4_0`
No Context block	Check `directoryContext` path / depth; rebuild index

13 · Next steps

Swap in StarCoder2‑15B or DeepSeek‑Coder‑33B for higher quality.
Drop temperature to 0 and let it draft unit tests you tweak.
Graduate to Tabby LoRA if you need inline completions that mimic your exact style.

Field	Value
Provider	`ollama`
Base URL	`http://localhost:11434`
Model	`codellama:7b`

Random thoughts on coding and technology

Building a Local Voice Cloning Studio That Actually Runs on My Machine

The Product Shape

Architecture

The XTTS Lesson

Why Transcript-Aware Cloning Helped

UX Details That Matter

Running It Locally

What I Would Improve Next

Takeaway

Beyond Prompts: Building a Codex Playbook for Real Application Development

The Core Problem

What This Repository Builds Instead

Why Durable Repo Instructions Matter

Why Skills Beat Giant Prompt Files

The C# Guidance

The Python Guidance

The React + TypeScript Guidance

Why The Examples Matter

Scripts And Templates As Engineering Tools

Strengths

Limitations

Where This Helps Most

Pros And Cons

Final View

Skills for Codex: The missing layer between prompts and reliable workflows

Why prompting alone breaks down

The missing layer: AGENTS.md + skills + scripts

The example repo

How to get the repo and run it

The skills

investigate-before-patching

summarize-test-failures

legacy-codebase-recon

review-change-safely

Why scripts matter

What worked well

What still does not work well

When I would use this in production

Closing thoughts

Building Fund Overlap Lab: From Surface Labels to Real Exposure

Why It Exists

Core Overlap Model

Data Pipeline: What Changed and Why

How Data Access Works

Ultimate Look-Through Mode (Recursive)

Example Questions It Answers Quickly

Project Structure

Run It

Final Thought

Building a Quant Developer Reference Library

Why This Exists

What The Library Tries To Do

What Is In The Repo

Core product chapters

Quant engineering chapters

The Point Of View

Who It Is For

What Makes It Different

Why I Am Sharing It Early

Where I Want To Take It

If You Work In This Space

Repository

Closing Thought

Short Version For Social Posts

Building a CLI Firework Simulation in Python, Just for Fun

Running Gemma 4 Locally on Android: Surprisingly Good

TL;DR

What This Is

First Impressions

1. Setup Experience

2. Performance

3. Model Quality

Why This Matters (Strategically)

1. True Edge AI Is Finally Here

2. Cost Model Disruption

3. UX Is the Real Breakthrough

Where It Fits in a Serious Stack

Hybrid Model Strategy

Limitations (Be Realistic)

The missing layer: `AGENTS.md` + skills + scripts

`investigate-before-patching`

`summarize-test-failures`

`legacy-codebase-recon`

`review-change-safely`

`OPENAI_API_KEY is not set`

`Image file not found`

`Unsupported image extension`

What `csv-stream-diff` Does