DEV Community: William

How Liquet became an autonomous marketplace dispute arbitrator powered by three Qwen models, and a 2,000-year-old Roman legal principle

William — Fri, 10 Jul 2026 15:21:41 +0000

The Problem We Couldn't Ignore

A buyer files a dispute: "Item not as described. The bag in the photo was leather. What arrived is plastic." The seller responds: "Item matches the listing exactly. Buyer is lying."

Two conflicting narratives. One order record. One blurry product photo. Somewhere in there is the truth — but no human agent will read it carefully at 11 PM on a Friday.

Online marketplaces collectively handle hundreds of millions of disputes every year. The resolution process at most platforms is, charitably, a keyword filter with a confidence score hardcoded to sound decisive. The systems that call themselves "AI-powered" are almost always rule engines that optimize for throughput over correctness. On genuinely ambiguous cases, they guess.

We kept asking: what would it look like if the AI actually reasoned over a dispute the way a careful adjudicator would? And — critically — what would it look like if it knew when to stop and say "I'm not sure"?

That question led us to Roman law.

The Latin Phrase That Named the Project

In ancient Roman courts, when a jury had heard all the evidence and still could not decide, a juror was entitled to return a verdict of non liquet — "it is not clear" — rather than force a guess. That option, the structured right to abstain, is what separates honest adjudication from fast adjudication.

The moment we articulated that principle, the project had a name and a north star: LIQUET — build an agent that resolves disputes it can resolve, and says so clearly when it cannot.

Every existing dispute-automation tool we examined had the same flaw: no principled abstention mechanism. The most dangerous failure mode in automated dispute resolution isn't slow resolution — it's a system that is wrong with high confidence.

What We Built

Liquet is a fully autonomous dispute arbitration agent. A dispute enters the system — through email, API, or the web dashboard — and Liquet runs a complete three-stage AI pipeline, stress-tests its own verdict with a built-in adversarial pass, runs adjudication three times to verify the reasoning is stable, and then makes a binary decision:

LIQUET ✅ — confidence ≥ 80%, order value < $500, no hard contradictions, verdict stable → resolved autonomously, both parties notified, webhook fired
NON LIQUET ⚠ — any condition violated → escalated to human reviewer with a complete decision brief

The gate is entirely deterministic Python. It cannot be hallucinated past.

The Three-Model Pipeline

One of the earliest and most important decisions we made was: don't route everything through one model.

Stage 1: qwen3.6-flash — Triage

Before spending a single premium token on full investigation, every incoming dispute goes through a fast triage pass. In milliseconds, qwen3.6-flash classifies the dispute category, scores its complexity, assigns a priority, and estimates resolution time. This pre-classification routes simple cases efficiently and prevents the expensive pipeline from wasting compute on disputes that can be resolved with minimal evidence.

Stage 2: qwen3.6-plus — Visual Evidence

Many marketplace disputes live or die on physical evidence: the product photo in the listing versus the photo the buyer uploaded. qwen3.6-plus handles every call that carries images — damage detection, label verification, packaging inspection, screenshot analysis of tracking pages. The vision model doesn't write verdicts; it writes evidence summaries that the reasoning model then weighs.

Stage 3: qwen3.7-max — Reasoning and Adjudication

The flagship model handles the calls where extended chain-of-thought actually improves correctness: the full adjudication pass over the assembled case file, the adversarial skeptic rebuttal, the email parsing that turns a buyer's complaint email into a structured case. qwen3.7-max also powers ReasoningGlass — a live stream of the model's extended-thinking tokens displayed in the dashboard as the adjudicator works, so reviewers can watch the agent reason in real time.

The Feature That Changed Everything: The Skeptic

Early versions of Liquet had a critical flaw we didn't notice until we started reading the verdicts carefully.

The adjudicator was too confident. Given both narratives and all evidence, it reliably produced a verdict — and then the human reviewer would read it and immediately see the one thing it missed: the seller's counter-claim about return shipping that, if true, changed the outcome entirely.

We added a Skeptic Pass: after the primary verdict, a second qwen3.7-max call receives only the losing party's narrative and the primary verdict. Its instruction is to generate the strongest possible case against the verdict. It has no access to the primary reasoning, only the evidence that favors the side that lost.

The first version still agreed with the primary verdict most of the time — because it could see the same evidence the adjudicator saw. The fix was forced adversarial asymmetry: give the skeptic only the losing narrative, nothing else. That produced real rebuttals. On cases where the skeptic raised a hard contradiction the primary pass had underweighted, the case correctly escalated.

A system with a built-in mechanism for arguing against itself is harder to fool than one that always confirms its own reasoning.

Stability Scoring: Running It Three Times on Purpose

Here's a non-obvious thing we discovered: a model that gives the same answer every time is not the same as a model that gives the right answer.

We ran the adjudicator on the same case file with temperature set to zero — perfectly deterministic — and got identical outputs across three runs. But when we introduced slight temperature variation and shuffled the order of evidence items in the system prompt between runs, something interesting happened: about 15% of cases produced different outcomes across the three passes.

Those cases were almost always the ones where a human reviewer, reading the brief, would say "I can see why someone could go either way here." The variance was real signal about genuine ambiguity — not noise.

So we kept it. Stability scoring runs three adjudication passes with slightly varied conditions, measures the fraction that agree, and applies a stability penalty to the effective confidence when they don't. A verdict that holds across all three runs earns its confidence score. One that splits is penalised. One that produces three different resolutions cannot pass the LIQUET gate regardless of what the nominal confidence number says.

effective_confidence = raw_confidence × stability_score

Ghost Cases: Grounding the Agent in History

One of the subtler features — and one of the most impactful — is ghost case injection.

Before the primary adjudication pass, Liquet queries the historical case database for disputes with matching category, overlapping order value bracket, and the same set of evidence types present. Up to five matching historical cases, with their final resolution and outcome, are injected into the adjudicator's system prompt as precedent examples.

The practical effect is that the model reasons over what the platform has actually decided before, not just its general prior about disputes. On categories where the platform has established a strong track record — "never arrived" cases with confirmed non-delivery scan carry a 92% buyer-favor rate in the database — the adjudicator grounds its reasoning in that pattern rather than starting from scratch.

When no close historical matches exist, the case adjudicates on first principles and Liquet says so explicitly in the brief.

Closing the Loop: Email-to-Resolution with No Human Touch

The full closed loop that we're most proud of:

Buyer sends a complaint email
The IMAP poller detects it, passes it to qwen3.7-max for parsing
The parser extracts buyer narrative, order ID, dispute category, and any attached photos
A new case is automatically submitted and queued for investigation
The orchestrator runs the full pipeline
On LIQUET: both buyer and seller receive a verdict email; a signed webhook fires to the external system
On NON LIQUET: the human reviewer receives a decision brief and a HMAC-SHA256 signed one-click approval link
The reviewer clicks approve or override — no separate login, no UI navigation required
The case closes with a full immutable audit trail

End-to-end, zero human involvement on LIQUET cases. For the reviewer on NON LIQUET cases, the cognitive load is minimized: every piece of information needed to decide is pre-surfaced on one screen, with confidence breakdown, stability scores, and the exact reason the case abstained.

What Working with Qwen Cloud Taught Us

Model tier selection matters more than always reaching for the biggest model. The naive approach — route everything through qwen3.7-max — would have made the system 4–5× more expensive and no more accurate on the simple cases that make up the majority of volume. qwen3.6-flash at triage costs a fraction of a qwen3.7-max call and makes decisions that are good enough to route correctly. Using the right model for the right task is an architectural decision, not an afterthought.

Extended thinking is genuinely valuable, but only for the right calls. qwen3.7-max's extended chain-of-thought pass improved our adjudication quality measurably on complex cases with conflicting evidence. But for the skeptic pass — where we want a focused adversarial rebuttal, not an essay — it added latency without benefit. Knowing when to turn it on versus off took experimentation.

The QwenCloud API's reliability under concurrent load held up throughout. Running three stability passes concurrently, with a vision call happening in parallel, under our semaphore-limited concurrency of 3 simultaneous investigations, we didn't see unexpected rate limit failures once we respected the concurrency model. The structured output support for JSON schema enforcement made our Pydantic integration clean.

The Architecture: Why It's Built to Last

Liquet's core pattern — fast triage → deep evidence analysis → adversarial stress test → deterministic gate → human escalation with brief — is not specific to marketplace disputes. The same structure applies to insurance claim routing, vendor invoice disputes, content moderation appeals, and any domain where:

Inputs are ambiguous and partially contradictory human narratives
Some cases can be resolved confidently and some genuinely cannot
Wrong confident answers are more dangerous than honest abstentions
A human reviewer needs to be fast and correct on the cases that escalate

The domain models and policy document change. The orchestration, gate logic, and audit trail do not. We designed Liquet to be a reference implementation of a pattern, not a one-off tool.

What's Next

The gap between "useful demo" and "production system" in dispute resolution is: real EHR integration, multi-currency jurisdiction-aware policy selection, and longitudinal seller risk scoring. We know exactly where the seams are. The architecture is already async SQLAlchemy on top of SQLite — switching to PostgreSQL for real concurrent load is a DATABASE_URL change. The repository layer is already abstracted.

The next version of Liquet doesn't need a new system. It needs a real data feed, a real policy library, and time.

Try It

Live demo: http://liquet.43.98.167.71.sslip.io
Source code: https://github.com/nnam-droid12/Liquet

Deployed on Alibaba Cloud ECS, Singapore. QwenCloud API at dashscope-intl.aliyuncs.com/compatible-mode/v1.

Liquet knows when it's clear — and admits when it isn't.

Building HELPIT, a memory layer for robotic dental surgery on Qwen Cloud — and the bugs that taught me more than the features did.

William — Fri, 03 Jul 2026 14:34:01 +0000

The problem that started this

Picture the second right before a robotic arm lowers a drill bit toward a patient's jaw. It has sub-millimeter precision. It has a plan, loaded and ready. What it doesn't have is any idea that this same patient's last implant failed on the other side of their mouth three years ago.

That's not hypothetical. Robotic dental implant surgery isn't science fiction anymore — implant-placement robots are already in clinical use, drilling and seating implants with precision no human hand can match. But precision was never the missing piece. Memory was.

Every one of these systems starts every procedure the exact same way: cold. The robot has no idea this patient's bone density scan looked different six months ago than it does today. It has no idea the last patient with this exact bone-density class and this exact implant brand had a 30% higher rejection rate the moment torque crossed 45 Ncm. That knowledge lives in one dentist's head, in a paper chart nobody cross-references mid-procedure, or nowhere at all — a robot with world-class precision and the situational awareness of a stranger.

So I built HELPIT — a memory layer that sits between the dentist, the patient record, and the robot, and refuses to let a procedure start without the full picture: this patient's own history, what's worked across thousands of similar patients, and a hard gate that can say pause or stop before anything happens.

What HELPIT actually does

Before any robotic procedure begins, HELPIT runs a memory-and-safety pipeline and hands the dentist a cited, evidence-backed brief — never a robot's own unsupervised call:

Retrieve memory — episodic history for this patient (prior procedures, complications, healing trajectory) and semantic memory (population-level outcome patterns for this bone-density class), pulled in parallel.
Evaluate the gate — a deterministic PROCEED / PAUSE / ESCALATE decision. One hard contraindication (a material allergy, an anticoagulant flag, a scan contradiction) always outranks an otherwise-good composite score. This part is plain Python, not a model call — more on why below, because it's the decision I'd defend hardest.
Approve & monitor — the dentist reviews a cited brief and approves. Every step is tracked live against plan, with automatic pause on deviation — and, mid-procedure, a live co-pilot that checks whether anything like this deviation has happened before and speaks back what actually worked last time.
Consolidate outcomes — post-procedure results get written back into memory automatically, so the next patient with similar anatomy benefits from what was just learned.

Why the gate itself isn't an LLM call

This is the design decision I'd defend hardest, so let me actually defend it.

It would have been trivial to have Qwen just... decide. Feed it the patient's history and the population data, ask for PROCEED, PAUSE, or ESCALATE, done. It would have demoed fine. It also would have been the kind of decision that quietly changes on a re-roll, or that a model gets subtly wrong in a way nobody notices until it matters. A safety-critical branch that can silently drift isn't something I was willing to ship, hackathon or not.

So gate_evaluator.py decides nothing with a model. It's deterministic Python, full stop:

if has_allergy_or_systemic_flag or has_anatomy_contradiction or risk_score >= settings.gate_risk_escalate_threshold:
    gate_result = GateResult.ESCALATE
elif (
    memory_completeness < settings.gate_memory_completeness_threshold
    or anatomy_match_score < settings.gate_anatomy_match_threshold
    or risk_score >= settings.gate_risk_pause_threshold
):
    gate_result = GateResult.PAUSE
else:
    gate_result = GateResult.PROCEED

Qwen's job is everything around that decision — writing the narrative that explains it, citing the specific records it's grounded in, generating the anatomy-drift summary a dentist actually reads. The decision itself is reproducible, testable, and immune to a bad generation. I have an entire pytest file whose only job is proving a hard contraindication can never be masked by an otherwise-good composite score, no matter what any model outputs on any given run.

How Qwen Cloud actually gets used, model by model

I didn't want one model doing everything by default. A hackathon build where every call just goes to "whichever model is handy" would have been both slower and dishonest about what each call actually needs. So the routing here is deliberate, not default:

Model	Used for	Why this one
`qwen3.7-max`	The surgery-ready brief	The single highest-stakes generation call in the pipeline — worth the deepest reasoning model available
`qwen3.6-flash`	The anatomy-drift narrative, and the live co-pilot's mid-procedure advisory	Short, grounded output that doesn't need the flagship model — and for the co-pilot, latency is the feature: a surgeon mid-procedure needs one sentence in under two seconds, not a paragraph in ten
`qwen-vl-plus`	X-ray/CBCT analysis, post-op video-frame review	The only calls that actually carry images
`text-embedding-v3`	Cross-patient case recall and deviation-event recall	Ranks by cosine similarity against every other patient's history — a practice-wide semantic index, not a per-patient linear scan
`wan2.6-t2v`	AI-generated, narrated procedure preview video	Not a chat-completion model at all — goes through DashScope's native async task API (submit, poll by `task_id`) instead of the OpenAI-compatible surface everything else uses
`cosyvoice-v3-plus`	Spoken co-pilot advisories and video-analysis Q&A	The one model in this stack that talks back — over a WebSocket, not a REST call

The anatomy narrative and the surgery brief run concurrently via asyncio.gather, since neither depends on the other's output — that alone keeps end-to-end gate evaluation to about 9 seconds instead of stacking two model calls sequentially.

The bug that taught me the most about Qwen3.x specifically

When I switched the brief generator to qwen3.7-max — to use the strongest reasoning model for the highest-stakes call — gate evaluation quietly went from ~9 seconds to ~50 seconds. Same prompt. Same output quality. Five times slower, for nothing.

The cause: the Qwen3.x family defaults to an extended chain-of-thought "thinking" pass before the actual answer. Genuinely useful for open-ended reasoning. Completely wasted here, because the decision is already deterministic Python by the time the model is called — there's nothing left for extended thinking to improve when the model's only job is writing narrative around an answer that's already been computed.

response = await _client.chat.completions.create(
    model=model or settings.model_reasoning,
    messages=messages,
    temperature=temperature,
    max_tokens=max_tokens,
    extra_body={"enable_thinking": False},
)

One flag. Verified with direct before/after timing against the live API: straight back to ~9 seconds, identical eval-harness accuracy — 100% gate accuracy, 0% false-PROCEED rate, both before and after. I would not have caught this by trusting that "point at the flagship model" meant the job was done. I caught it by actually timing real calls against a real API and refusing to believe a 5x slowdown was just "how it is."

Making MCP actually real, not just decorative

HELPIT runs on 7 FastMCP tool servers — patient memory, imaging, procedure tracking, a semantic knowledge base, risk scoring, dentist preferences, outcome tracking. The honest first version of this only ever called them as plain Python functions, in-process. @mcp.tool() was doing nothing but organizing code into folders with an official-looking decorator on top. Functionally fine. Not actually "using MCP" in any way a skeptical reader should accept.

So two of the servers now also carry a real standalone entrypoint:

if __name__ == "__main__":
    mcp.run(transport="stdio")

And I wrote a client script that proves it isn't decorative — a genuine MCP initialize() handshake, list_tools(), call_tool(), over the actual protocol, against the same live SQLite database the running app uses:

async def call_server(module, tool_name, arguments):
    params = StdioServerParameters(command=sys.executable, args=["-m", module], cwd=str(REPO_ROOT))
    async with stdio_client(params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()
            result = await session.call_tool(tool_name, arguments)

Running it against patient_memory_server returns the same five seeded patients the web app shows. A standalone MCP client and the FastAPI app, reading identical memory through two completely different transports. That's the difference between "we used MCP" as a slide bullet and "we used MCP" as something you can actually go run.

Real anatomy, and the decimation algorithm nobody asked for

I wanted the 3D tooth and implant previews to be actual anatomy, not procedural boxes-and-spheres wearing a tooth costume. Three separate attempts at hand-built geometry all read as "blocky toy" or, memorably, "light bulb" — a fully round, radially-symmetric shape structurally can't represent a tooth's flat mesial, distal, buccal, and lingual walls. No amount of clever code fixes that. Only a real scan does.

So I sourced one — a full maxillary arch, public domain, from NIH 3D. 951,316 vertices at 34MB, straight off a real scan. Beautiful. Also completely unusable: a browser tab auto-rotating that mesh next to several other live 3D canvases ground to a crawl. Three.js's standard edge-collapse simplifier was still churning after twenty minutes and counting.

So I wrote a decimator instead — the simplest one that could possibly work. Snap every vertex to a 3D grid cell sized as a fraction of the mesh's bounding-box diagonal. Average every vertex that lands in the same cell into one point. Remap every triangle's indices through that old-to-new mapping. Drop anything that degenerated into a zero-area sliver in the process.

cell_size = diagonal * 0.0026
cell = tuple(int((v[axis] - bbox_min[axis]) / cell_size) for axis in range(3))
# accumulate all vertices sharing a cell, average, remap triangle indices

951,316 vertices became 128,720 (13.5%). 1.9 million triangles became 264,000. 34MB became 13.2MB. Twenty-plus minutes became a few seconds. It is not a clever algorithm — it's arguably the crudest spatial hash you could write — and that's exactly the point. The textbook-correct simplifier was strictly better geometry and strictly useless for what I actually needed, which was "finishes before I lose interest in waiting for it."

Where it stands right now

100% gate accuracy, 0% false-PROCEED rate on a labeled eval harness — the single most dangerous failure mode a system like this can have (a false PROCEED on a patient who should PAUSE or ESCALATE) is checked explicitly, and hard-fails the eval run the moment it's ever non-zero.
42 pytest tests, gating every deploy in CI — including a permanent regression test for a genuinely nasty SQLAlchemy bug: mutating a JSON column's cached list in place and reassigning the same object reference is a silent no-op for the ORM's dirty-tracking. The API response looked completely correct. The database write just never happened, and nothing said otherwise until a second, independent read proved it.
A live memory co-pilot that speaks up the instant a step deviates mid-procedure, grounded in what actually happened the last time something similar occurred — and honest enough to say "nothing similar on file" instead of fabricating confidence when it has nothing to go on.
Deployed on Alibaba Cloud ECS, redeployed automatically on every push to main, gated by that same test suite.

What's next

Real EHR integration instead of synthetic patient data.
A second reference implementation of the same episodic + semantic + gate + live-co-pilot pattern in a non-dental domain, to make the "this architecture generalizes" claim concrete instead of just argued.
Feeding the live co-pilot a real practice's historical deviation/outcome records on day one, instead of starting its memory from zero.

If you're working with Qwen Cloud's model family and have run into the enable_thinking latency trap yourself, or have opinions on where the PROCEED/PAUSE/ESCALATE line should actually sit for a safety-critical gate — I'd genuinely like to hear about it in the comments.

Building Choragi: How We Orchestrated a 6-Agent Concert Planning System with Gemini Live and Google Cloud

William — Fri, 13 Mar 2026 11:35:52 +0000

*We created this piece of content for the purposes of entering the Gemini Live Agent Challenge.

GeminiLiveAgentChallenge*

Music has a universal power to heal and bring communities together. But behind every magical live concert is a grueling logistical nightmare. Independent artists and event planners spend weeks scouting venues, making stressful phone calls to negotiate rates, designing promotional materials, and manually wrestling with ad campaigns.

We thought: What if we could build an engine that takes away the logistical burden, turning a month of planning into a 5-minute automated sequence?

Enter Choragi—an autonomous, multi-agent event orchestration system triggered entirely by a natural voice conversation. In this post, I’ll break down how we built this system using Java Spring Boot, Gemini Live API, Google Cloud Run, and the absolute cutting edge of Google's generative AI models.

The Architecture: A Serverless Symphony

Choragi is not a single monolith; it is a highly specialized microservices architecture. We built 6 independent Spring Boot applications and deployed them entirely on Google Cloud Run.

By leveraging Cloud Run, we achieved a scalable, serverless backend where each agent scales independently based on its workload. We secured the entire internal network using Google Cloud's Application Default Credentials (ADC), entirely eliminating the need for hardcoded service account keys in our codebase.

Here is the breakdown of the fleet:

UI Dashboard (ui-client): The real-time WebSockets command center.
Venue Scout (venue-finder): Discovers potential concert spaces.
Live Negotiator (live-negotiator): Telephony agent connecting Twilio to Gemini.
Creative Director (creative-director): Generates 8K posters and cinematic video trailers.
Site Builder (site-builder): Autonomously deploys a live promotional website.
Digital Promoter (digital-promoter): Navigates Google Ads to launch campaigns.

The Brains: Integrating Google AI Models

To make this pipeline truly autonomous, we had to fuse multiple modalities of AI.

1. Real-Time Telephony with Gemini 2.5 Flash Native Audio

The most ambitious part of Choragi was the live-negotiator. We wanted the AI to actually call a venue owner over the phone and negotiate a booking space.

We bridged a Twilio WebSocket stream directly to the Gemini BidiGenerateContent API. Because Twilio streams audio in 8kHz MuLaw format and Gemini strictly requires 16kHz PCM, we had to build an on-the-fly byte transcoder in Java. We utilized the ["AUDIO"] response modality to ensure the model spoke naturally, and we implemented a custom Voice Activity Detection (VAD) algorithm using RMS thresholding to prevent noisy phone lines from interrupting the AI.

2. Multi-Modal Creative Generation

Once the venue is secured, the creative-director agent takes over to generate promotional assets, directly uploading the results to a public Google Cloud Storage bucket.

Tour Posters: We utilized Gemini 2.5 Flash Image to generate highly realistic, professional concert posters that strictly adhered to text prompts for the artist's name and location.
Cinematic Video Trailers: We integrated Vertex AI Veo 3.0 Fast via its Long-Running Operations REST API to generate photorealistic concert stage visuals.

3. Robotic Web Automation with Gemini Vision

For the digital-promoter, we didn't want to use standard APIs. We wanted the agent to navigate the web like a human. Using Microsoft Playwright in a headless Chromium container, the agent literally "looks" at the Google Ads dashboard using Gemini 2.5 Flash. The model analyzes the screenshot of the DOM and outputs precise visual coordinates and text commands (e.g., CLICK_TEXT: Page views, FILL_FIELD: businessName) to autonomously launch the campaign.

The Hardest Technical Challenge: Vertex AI REST Routing

When building hackathon projects, you quickly find the bleeding edge of new APIs. When integrating Veo 3.0 Fast, we bypassed the standard SDK and hit the raw Vertex AI predictLongRunning REST endpoints.

We successfully authenticated and triggered the video generation, receiving an Operation ID (a UUID) to poll for the video's completion. However, we discovered a routing quirk: polling the standard v1 API with a UUID resulted in a 400 Bad Request: The Operation ID must be a Long. The v1 endpoint was strictly expecting numeric legacy IDs!

The Solution: We engineered a resilient fallback mechanism. We stripped the publisher paths from the operation name and routed the polling request to the experimental v1beta1 endpoint. Furthermore, we wrapped the polling loop in a "God Mode" safety net—if the Google routing API threw an exception, our Spring Boot service caught the HttpStatusCodeException, gracefully waited 40 seconds for the backend Veo rendering to finish, and successfully returned the Cloud Storage URL anyway. The architecture held strong.

Conclusion

Building Choragi pushed us to the limits of real-time streaming, asynchronous microservices, and multi-modal AI orchestration. By combining the infrastructure of Google Cloud with the intelligence of Gemini and Vertex AI, we successfully transformed the logistical chaos of event planning into an elegant, autonomous engine.

Artists should spend their time creating music that heals, not navigating ad campaigns and making cold calls. With AI orchestration, we can finally let them get back to the music.

Check out our full repository and project submission for the #GeminiLiveAgentChallenge!

From First Issue to Merged PR: My Journey Contributing to Spring AI

William — Sun, 19 Oct 2025 14:42:48 +0000

INTRODUCTION

For a long time, I admired open-source contributors from afar, people who helped build the libraries, frameworks, and tools that power the software we use daily. This October, during Hacktoberfest 2025, I decided to finally take the leap and make my first real contribution to open source.

That experience, contributing to Spring AI, a project under the Spring Framework turned out to be both challenging and rewarding. In this post, I’ll share what I did, what I learned, and why I think everyone should try contributing at least once.

How It Started

I joined Hacktoberfest this year with a simple goal: to understand what contributing to open source really feels like. After exploring a few repositories, I noticed Spring AI, an application framework for AI engineering built by the Spring team.

As someone interested in backend development, Java, and AI integrations, this felt like the perfect project to dive into. I scanned through open issues, read contribution guidelines, and picked an issue related to fixing Azure OpenAI auto-configuration.

The Contribution

The task was small but technical, updating a Spring Boot auto-configuration class to include the correct dependency for ToolCallingAutoConfiguration.

I forked the repository, cloned it locally, and followed the contribution setup. Along the way, I ran into:

Checkstyle formatting errors I didn’t cause but had to understand.
Build failures that taught me how Maven and Spring’s formatting rules work.
A review cycle with one of the project maintainers, who helped me refine the PR.

After I made the requested updates and pushed the final changes, the maintainer rebased, squashed, and merged my code into the project. Seeing my work appear in a widely used open-source framework was an incredible moment.

What I Learned

This single PR taught me a lot more than I expected:

Read contribution guides carefully, every project has its own workflow and formatting rules.
Code reviews are learning opportunities, maintainers often suggest small but important details that improve your engineering mindset.
Even small contributions matter, fixing a line of configuration or documentation still improves the project.
Communication is key. Be polite, thank reviewers, and show that you’re open to feedback.

It’s okay if your PR isn’t merged directly, sometimes maintainers rebase or squash your commits for consistency; what matters is that your work becomes part of the codebase.

The Hacktoberfest Twist

Although my pull request was part of Hacktoberfest, it wasn’t counted automatically because the maintainer rebased and merged it manually, a common workflow for large enterprise projects.

Still, the real reward wasn’t the t-shirt. It was seeing my name in the Spring AI commit history and knowing that I contributed to one of the world’s most recognized Java frameworks.

What’s Next

This first experience gave me confidence to keep contributing, not just during Hacktoberfest, but throughout the year. My goal now is to explore more open-source projects, particularly those involving:

Java and Spring Boot
AI integrations
Cloud and backend architecture

If you’re thinking about contributing but haven’t yet, start small. Fix a typo, improve documentation, or pick a “good first issue.” The open-source community is more welcoming than it looks.

Final Thoughts

Contributing to open source is one of the best ways to grow as a developer. It pushes you beyond tutorials into real-world collaboration, code quality, and communication.

I’m grateful to the Spring AI maintainers, especially @ilayaperumalg
, for their guidance and patience during my first PR review.

This experience reminded me that even the smallest contributions make a lasting impact, not only on the project but on your growth as a developer.

Pull Request: Fix Azure OpenAI Auto-Configuration – spring-projects/spring-ai#4636

Project: Spring AI GitHub Repository

Author: William Nnamani

hacktoberfest

Event-Driven Microservices with Apache Kafka And Spring Boot: A Practical Guide

William — Fri, 07 Feb 2025 18:39:37 +0000

Introduction

In modern microservices architecture, event-driven systems play a crucial role in enabling scalable, decoupled, and efficient communication between services. Apache Kafka has emerged as a leading distributed event-streaming platform, widely used for real-time data processing.

In this article, we will explore how to build an event-driven microservices system using Java Spring Boot and Apache Kafka, with a practical example of decoupling order processing from inventory management.

Why Event-Driven Microservices?

Traditional REST-based communication introduces tight coupling between services, making them harder to scale and maintain. Event-driven microservices solve this problem by allowing services to communicate asynchronously using events.

Benefits of Event-Driven Architecture:

Decoupling: Services interact via events, reducing direct dependencies.
Scalability: Independent services can scale as needed.
Resilience: Failures in one service do not immediately impact others.
Flexibility: Easily extend systems by adding new consumers.

Setting Up Apache Kafka

Before implementing our example, make sure you have Apache Kafka installed and running.

Download and Extract Kafka:

  Head over to this website [Download Apache Kafka](https://kafka.apache.org/downloads)
unzip to your favorite location
for this article i created a folder called software in local c on windows and rename kafka_2.13-3.0.0 to just kafka

Start Zookeeper and Kafka Broker:

    FOR ZOOKEEPER

   * To Start Zookeeper
   * open command prompt or terminal and CD into C:\softwares\kafka\bin\windows>
  * Then run this,  zookeeper-server-start.bat ..\..\config\zookeeper.properties 

FOR KAFKA BROKER 
  * To start kafka broker
  * open another command prompt or terminal and CD into C:\softwares\kafka\bin\windows>
  * Then run this, kafka-server-start.bat ..\..\config\server.properties

Experiment with Kafka

create a Topic - With another cmd instance open with same path you cd into to run both kafka broker and zookper while your kafka broker and zookeeper is still open, then run this command to create a kafka topic, kafka-topic.bat --bootstrap-server --create --topic order-topic --partitions 3 --replication-factor 1
- list Topic - run this command to list a kafka topic, kafka-topic.bat --bootstrap-server localhost:9092 --list
- describe a Topic - run this command to describe a kafka topic, kafka-topic.bat --bootstrap-server localhost:9092 --describe --topic order-topic
- publish message from producer to consumer - Open another instance of the command prompt and then run this to publish message from producer to consumer kafka-console-producer.bat --broker-list localhost:9092 --topic order-topic
- subscribe/consume message from producer - Open another instance of the command prompt and then run this to subscribe to message from the producer kafka-console-consumer.bat --bootstrap-server localhost:9092 --topic order-topic --from-beginning

Implementing the Practical Example

Let's implement a scenario where an Order Service processes orders, and an Inventory Service listens to order events to update stock levels.

Create Spring Boot project

Head over to Spring Starter template
Create a Spring Boot Kafka Producer (Order Service)
add the dependency spring web and kafka

 <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.kafka</groupId>
    <artifactId>spring-kafka</artifactId>
</dependency>

Create a Kafka Producer:

import org.springframework.kafka.core.KafkaTemplate;
import org.springframework.stereotype.Service;

@Service
public class OrderProducer {
    private final KafkaTemplate<String, String> kafkaTemplate;

    public OrderProducer(KafkaTemplate<String, String> kafkaTemplate) {
        this.kafkaTemplate = kafkaTemplate;
    }

    public void sendOrderEvent(String message) {
        kafkaTemplate.send("order-topic", message);
    }
}

Expose an API to trigger order processing:

import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/orders")
public class OrderController {
    private final OrderProducer orderProducer;

    public OrderController(OrderProducer orderProducer) {
        this.orderProducer = orderProducer;
    }

    @PostMapping("/create")
    public String createOrder(@RequestBody String orderDetails) {
        orderProducer.sendOrderEvent(orderDetails);
        return "Order event sent!";
    }
}

2. Create a Spring Boot Kafka Consumer (Inventory Service)

Create a Kafka Consumer:

import org.apache.kafka.clients.consumer.ConsumerRecord;
import org.springframework.kafka.annotation.KafkaListener;
import org.springframework.stereotype.Service;

@Service
public class InventoryConsumer {
    @KafkaListener(topics = "order-topic", groupId = "inventory-group")
    public void listenOrderEvents(ConsumerRecord<String, String> record) {
        System.out.println("Received Order Event: " + record.value());
        updateInventory(record.value());
    }

    private void updateInventory(String orderDetails) {
        // Simulate inventory update logic
        System.out.println("Inventory updated for order: " + orderDetails);
    }
}

Running the Application

Start Kafka and Zookeeper (if not already running).
Run the Order Service: Start the producer microservice.
Run the Inventory Service: Start the consumer microservice.
Trigger an Order Event:

   curl -X POST http://localhost:8080/orders/create -H "Content-Type: application/json" -d '"{"orderId": "123", "productId": "456", "quantity": "2"}"'

Check the Consumer Logs: You should see the order event being processed and the inventory updated.

Conclusion

Event-driven microservices with Apache Kafka provide a powerful way to build decoupled, scalable systems. In this guide, we demonstrated how to implement a simple order processing system using Kafka producers and consumers in Spring Boot.

By adopting event-driven design, you can create robust, loosely coupled microservices that scale efficiently while ensuring smooth communication between components.

Please if you find the article interesting and valuable drop a like and comment. See you in the next one, keep building!
Follow me on socials my Linkedin Handle

How to Design a Scalable Microservices Architecture: Lessons from Real-World Systems

William — Fri, 07 Feb 2025 12:42:36 +0000

Introduction

Microservices architecture has become the poster child of modern software development. It promises scalability, flexibility, and the dream of independent deployability. But let’s be real—building a microservices-based system isn’t all sunshine and rainbows. It comes with its own set of challenges, especially when working with Java and Spring Boot.

In this article, we’ll dive into real-world lessons learned from implementing microservices.

Lesson 1: Microservices Doesn’t Mean Micro-Problems

Many teams start with microservices thinking, "Let’s break this monolith into smaller, manageable pieces." Sounds great, right? Until you realize you now have 20+ services talking to each other like a whole community fetching from a stagnant stream of water.

Solution: Proper Service Boundaries

Use Domain-Driven Design (DDD) to define proper service boundaries.
Avoid creating microservices that are too micro—sometimes a monolith is just a misunderstood hero.
Ensure each service has a clear, independent responsibility.

Lesson 2: Distributed Transactions Are a Nightmare

In monolithic applications, transactions are simple—you start one, do some operations, commit or rollback. But in microservices? Welcome to the Saga pattern and compensating transactions, where a failed step means you have to undo everything.

Solution: Handling Transactions Properly

Use the Saga pattern for long-running transactions.
Implement event-driven architectures with tools like Kafka or RabbitMQ.
Idempotency is your best friend—ensure your services can handle duplicate requests gracefully.

Lesson 3: Latency is the Silent Killer

Breaking down a monolith into microservices means your once-simple function call is now a network request. And we all know how reliable networks are. Suddenly, your ultra-fast system is moving at the speed of a sloth on a Monday morning.

Solution: Performance Optimization

Use circuit breakers (Resilience4j, Hystrix) to prevent cascading failures.
Implement caching (Redis, EhCache) to avoid unnecessary calls.
Monitor API latencies and optimize slow endpoints.

Lesson 4: Versioning is Inevitable

Deploying updates in a microservices world can be like trying to replace a car tire while speeding down the highway. One breaking change, and everything falls apart.

Solution: Backward-Compatible APIs

Use semantic versioning (e.g., v1, v2 endpoints).
Follow API-first design with OpenAPI and Swagger.

Lesson 5: Logging and Monitoring Save Lives

Debugging a microservices system without proper logging is like trying to solve a crime without evidence. You think you know what’s happening, but reality is a different story.

Solution: Observability Tools

Centralize logs using ELK Stack (Elasticsearch, Logstash, Kibana) or Grafana Loki.
Implement distributed tracing with Jaeger or Zipkin.
Monitor metrics with Prometheus and Grafana.

Lesson 6: Security is Not Optional

Exposing multiple microservices to the world without security is like leaving your house with the doors open and a sign that says, "Come on in, free valuables inside!"

Solution: Secure Your Services

Use OAuth 2.0 and JWT for authentication.
Implement API gateways (Spring Cloud Gateway) for centralized security.
Keep dependencies up to date to avoid vulnerabilities.

Conclusion

Microservices architecture, when done right, can bring immense benefits. But it requires careful planning, solid design principles, and the right set of tools. Java and Spring Boot provide a robust ecosystem to build scalable and resilient microservices, but they also come with challenges that need to be addressed.

So, before you jump headfirst into microservices, ask yourself: "Do I really need this, or can my monolith still do the job?" Because sometimes, the best microservice decision is not using microservices at all!

Please like this post and comment if you find it valuable and interesting, till next time keep building.
You can connect with me on socials: My Linkedin Handle