DEV Community: Puneet Gupta

Database Indexing and Query Optimization for Python Developers

Puneet Gupta — Sat, 04 Jul 2026 15:29:37 +0000

Introduction

Fixing N+1 queries with select_related/prefetch_related or selectinload (see the previous post) gets you down to a small, sane number of queries per request. The next bottleneck is what each query costs once the table has millions of rows — and that is almost always about indexing.

An index turns "scan every row" into "look it up directly." Skip it, and a query that's instant in development takes seconds once real data volume shows up in production.

How Indexes Work: The B-Tree Intuition

Without an index, a WHERE clause forces a sequential scan: the database reads every row and checks the condition — O(n), cost grows linearly with table size.

An index is a separate, sorted structure (almost always a B-tree) mapping column values to row locations. Because it's sorted and balanced, finding a value is a tree walk: O(log n). On a 10-million-row table, that's the difference between reading 10 million rows and roughly 23 tree nodes.

This isn't free:

Writes get slower — every INSERT/UPDATE/DELETE on an indexed column also updates the index.
Storage grows — each index is a sorted copy of (part of) the data.

An index trades write cost and storage for read speed. Indexing a column you rarely filter or sort on is pure cost, no benefit.

Reading Query Plans: EXPLAIN ANALYZE

Postgres' EXPLAIN ANALYZE shows what the planner actually did, not an estimate.

Before an index, filtering orders by customer_id:

EXPLAIN ANALYZE
SELECT * FROM orders WHERE customer_id = 48291;

Seq Scan on orders  (cost=0.00..21453.00 rows=42 width=96) (actual time=0.021..118.442 rows=41 loops=1)
  Filter: (customer_id = 48291)
  Rows Removed by Filter: 1199959
Planning Time: 0.112 ms
Execution Time: 118.471 ms

Seq Scan means Postgres read all ~1.2 million rows and discarded all but 41. actual time is real elapsed time — 118ms for one lookup.

After CREATE INDEX idx_orders_customer_id ON orders (customer_id);:

Index Scan using idx_orders_customer_id on orders  (cost=0.42..8.53 rows=42 width=96) (actual time=0.018..0.041 rows=41 loops=1)
  Index Cond: (customer_id = 48291)
Planning Time: 0.098 ms
Execution Time: 0.061 ms

Index Scan walks the B-tree straight to the matching rows: 118ms down to 0.06ms, roughly 1,900x — and the gap only widens as the table grows. What to check in any plan:

Seq Scan vs Index Scan / Index Only Scan — the single biggest signal.
rows (estimate) vs actual … rows — a large gap means stale table statistics (run ANALYZE).
cost=startup..total — the planner's internal unit, useful for comparing plans, not wall-clock time.
Rows Removed by Filter — a high number on a Seq Scan is a strong signal an index would help.

Composite Indexes and Column Order

An index on (customer_id, status) is not the same as (status, customer_id). B-tree indexes are searchable by their leftmost prefix: sorted first by the first column, then by the second within each value of the first.

CREATE INDEX idx_orders_customer_status ON orders (customer_id, status);

Usable for:

WHERE customer_id = 48291                          -- uses leftmost column
WHERE customer_id = 48291 AND status = 'SHIPPED'    -- uses both columns

Not usable (as an index scan on this index) for:

WHERE status = 'SHIPPED'   -- status alone isn't a leftmost prefix

Order columns by how they're actually queried: the column used alone or most selectively goes first.

Covering Indexes and Index-Only Scans

If an index includes every column a query needs, Postgres can answer straight from the index — an Index Only Scan:

CREATE INDEX idx_orders_customer_status_total
    ON orders (customer_id, status) INCLUDE (total_amount);

EXPLAIN ANALYZE
SELECT status, total_amount FROM orders WHERE customer_id = 48291;

Index Only Scan using idx_orders_customer_status_total on orders
  (cost=0.42..4.65 rows=41 width=13) (actual time=0.015..0.028 rows=41 loops=1)
  Index Cond: (customer_id = 48291)
  Heap Fetches: 0

Heap Fetches: 0 confirms the table itself was never touched.

When an Index Is NOT Used

The planner will happily ignore an index that exists. Common reasons:

A function wraps the column: WHERE UPPER(email) = 'X' can't use a plain index on email (a functional index, CREATE INDEX ON users (UPPER(email)), fixes this).
A leading wildcard: WHERE name LIKE '%smith' can't use a standard B-tree — the sorted prefix is useless without a known prefix. LIKE 'smith%' can.
Low selectivity: if 90% of rows match, a Seq Scan genuinely costs less than following an index and fetching almost every row anyway — the planner correctly skips the index.
Implicit type casts: comparing a text column to an integer literal, or a timestamp column to an unparsed string, can force a scan. Match types explicitly.

Selectivity and Cardinality

Selectivity is the fraction of rows a condition matches; cardinality is the number of distinct values in a column. An index on a boolean is_active column has cardinality 2 — following it typically still means fetching close to half the table, which costs more than scanning it outright. Indexes pay off on high-cardinality, selective columns (customer IDs, emails, timestamps), not on flags. If you must filter efficiently on a low-cardinality column, pair it in a composite index behind a selective column, or use a partial index (CREATE INDEX ... WHERE is_active = true for a rare status).

Pagination: Keyset vs OFFSET

The earlier ORM post flagged that slicing a queryset after a prefetch_related/join doesn't page cleanly. The same physics show up at the SQL level with OFFSET.

-- Deep page: Postgres must still generate and discard the first 100,000 rows
SELECT * FROM orders ORDER BY id LIMIT 20 OFFSET 100000;

OFFSET can't skip rows using the index alone — it still walks past them. Keyset (seek) pagination remembers the last row seen and uses an indexed condition instead of an offset:

-- Keyset: uses the index on id directly, same cost on page 1 or page 5,000
SELECT * FROM orders WHERE id > :last_seen_id ORDER BY id LIMIT 20;

Django and SQLAlchemy both express this as an ordinary indexed filter:

# Django: keyset pagination instead of Paginator's OFFSET-based pages
Order.objects.filter(id__gt=last_seen_id).order_by("id")[:20]

# SQLAlchemy
session.query(Order).filter(Order.id > last_seen_id).order_by(Order.id).limit(20)

This requires (and benefits from) an index on the ordering column — exactly the idx_orders_customer_id-style index above.

The Django and SQLAlchemy Angle

Neither ORM invents the right indexes for you — that's still informed by the plans above, not by the model definition alone.

Django — `Meta.indexes` and `db_index`

class Order(models.Model):
    customer_id = models.IntegerField(db_index=True)
    status = models.CharField(max_length=20)
    total_amount = models.DecimalField(max_digits=10, decimal_places=2)

    class Meta:
        indexes = [
            models.Index(fields=["customer_id", "status"], name="idx_orders_customer_status"),
        ]

db_index=True is fine for a single column; for composite/covering indexes use Meta.indexes. Either way, this only takes effect through a migration — Django generates one when you run makemigrations, and that migration file (not the model) is what actually creates the index:

# orders/migrations/0007_add_customer_status_index.py
operations = [
    migrations.AddIndex(
        model_name="order",
        index=models.Index(fields=["customer_id", "status"], name="idx_orders_customer_status"),
    ),
]

Review the generated SQL with python manage.py sqlmigrate orders 0007 before applying it in production, and consider Postgres' CREATE INDEX CONCURRENTLY for large existing tables (Django's AddIndexConcurrently on Postgres, run outside an atomic migration).

SQLAlchemy — `Index(...)` / `index=True` + Alembic

from sqlalchemy import Column, Integer, String, Numeric, Index

class Order(Base):
    __tablename__ = "orders"
    id = Column(Integer, primary_key=True)
    customer_id = Column(Integer, index=True)
    status = Column(String(20))
    total_amount = Column(Numeric(10, 2))

    __table_args__ = (
        Index("idx_orders_customer_status", "customer_id", "status"),
    )

The model declares intent; the actual DDL ships through Alembic:

# alembic/versions/xxxx_add_customer_status_index.py
def upgrade():
    op.create_index(
        "idx_orders_customer_status", "orders", ["customer_id", "status"]
    )

def downgrade():
    op.drop_index("idx_orders_customer_status", table_name="orders")

Spotting a plan-hostile query

Log or inspect the generated SQL rather than guessing:

# Django: see queries actually executed (DEBUG=True)
from django.db import connection
print(connection.queries[-1]["sql"])

# SQLAlchemy: echo generated SQL, or inspect a specific query's plan
engine = create_engine(url, echo=True)

result = session.execute(
    text("EXPLAIN ANALYZE SELECT * FROM orders WHERE customer_id = :cid"),
    {"cid": 48291},
)
for row in result:
    print(row)

A query that looks fine in Python can compile to a function-wrapped predicate that defeats an index:

Order.objects.filter(status__iexact="shipped")   # Django: often compiles to UPPER(status) = 'SHIPPED'

That's the "function on the column" case above. Either add a functional index (CREATE INDEX ON orders (UPPER(status))) or normalize status on write so the query can compare it directly.

Anti-Patterns

Indexing every column "just in case." Each index slows every write on that table and adds storage; index only what real queries filter, join, or sort on.
Redundant indexes. A single-column index on customer_id is redundant once (customer_id, status) exists — the composite index already serves lookups on customer_id alone.
Not indexing foreign keys used in joins. Postgres does not automatically index FK columns; Django adds one for ForeignKey fields by default, but a raw SQLAlchemy ForeignKey column does not get an index unless you add index=True or an explicit Index.
Trusting the model definition alone in production. Neither db_index=True nor SQLAlchemy's index=True does anything until a migration actually runs the DDL.

Practical Checklist

Situation	Action
Query does a Seq Scan on a large table with a selective filter	Add an index on the filtered column(s)
Filtering/sorting on two columns together	Composite index, most selective / most-used-alone column first
Query reads only indexed columns	Add `INCLUDE` columns for an Index Only Scan
`.filter(x__iexact=...)` or leading `%wildcard%`	Functional index or rewrite the predicate
Boolean/low-cardinality filter	Partial index, or pair behind a selective column
Deep pagination (`OFFSET 100000`)	Keyset pagination on an indexed column
FK column used in joins (SQLAlchemy)	Explicitly set `index=True` — it isn't automatic
Schema managed by Django/SQLAlchemy models	Ship the DDL via a migration (Django migration / Alembic), not just the model

Final Thoughts

Indexes are not a checkbox on a model — they're a targeted trade of write cost and storage for read speed, and the only way to know if the trade pays off is to read the actual query plan. Learn to read EXPLAIN ANALYZE, order composite indexes by how you really query, watch for the handful of things that silently defeat an index, and keep the DDL in migrations where it belongs. The ORM writes the SQL; the query plan tells you the truth about it.

Database Indexing and Query Optimization for Java Developers

Puneet Gupta — Sat, 04 Jul 2026 15:29:35 +0000

Introduction

Fixing N+1 queries (see the previous post) gets your Hibernate app down to a handful of queries per request. The next bottleneck is what each of those queries costs once your tables have millions of rows — and that is almost always a question of indexing.

An index turns "scan every row" into "look it up directly." Get the index wrong — or skip it — and a query that took 2ms in development takes 4 seconds in production once real data volume shows up.

How Indexes Work: The B-Tree Intuition

Without an index, a WHERE clause forces a sequential scan: the database reads every row and checks the condition. That's O(n) — cost grows linearly with table size.

An index is a separate, sorted data structure (almost always a B-tree) that maps column values to row locations. Because it's sorted and balanced, finding a value is a tree walk: O(log n). On a 10-million-row table, that's the difference between reading 10 million rows and reading roughly 23 tree nodes.

The cost is not free:

Writes get slower. Every INSERT/UPDATE/DELETE on an indexed column must also update the index structure.
Storage grows. Each index is a copy of (part of) the data, sorted differently.

An index is a trade: you pay on every write so that specific reads become fast. Indexing a column you rarely filter or sort on is pure cost with no benefit.

Reading Query Plans: EXPLAIN ANALYZE

Postgres' EXPLAIN ANALYZE shows what the planner actually did — not what you hope it did.

Before an index, filtering orders by customer_id:

EXPLAIN ANALYZE
SELECT * FROM orders WHERE customer_id = 48291;

Seq Scan on orders  (cost=0.00..21453.00 rows=42 width=96) (actual time=0.021..118.442 rows=41 loops=1)
  Filter: (customer_id = 48291)
  Rows Removed by Filter: 1199959
Planning Time: 0.112 ms
Execution Time: 118.471 ms

Seq Scan means Postgres read all ~1.2 million rows and threw away all but 41 of them. actual time is the real elapsed time, not an estimate — 118ms for one lookup.

After CREATE INDEX idx_orders_customer_id ON orders (customer_id);, the same query:

Index Scan using idx_orders_customer_id on orders  (cost=0.42..8.53 rows=42 width=96) (actual time=0.018..0.041 rows=41 loops=1)
  Index Cond: (customer_id = 48291)
Planning Time: 0.098 ms
Execution Time: 0.061 ms

Index Scan walks the B-tree straight to the matching rows. Execution time drops from 118ms to 0.06ms — roughly 1,900x, and the gap only widens as the table grows. What to check in any plan:

Seq Scan vs Index Scan / Index Only Scan — the single biggest signal.
rows (estimate) vs actual … rows — a big gap means the planner's statistics are stale (ANALYZE the table).
cost=startup..total — the planner's internal unit, useful for comparing two plans, not wall-clock time.
Rows Removed by Filter — a high number on a Seq Scan is a strong sign an index would help.

Composite Indexes and Column Order

An index on (customer_id, status) is not the same as one on (status, customer_id). B-tree indexes are searchable by their leftmost prefix: the index is sorted first by the first column, then by the second within each value of the first.

CREATE INDEX idx_orders_customer_status ON orders (customer_id, status);

This index is usable for:

WHERE customer_id = 48291                         -- uses leftmost column
WHERE customer_id = 48291 AND status = 'SHIPPED'   -- uses both columns

But not usable (as an index scan on this index) for:

WHERE status = 'SHIPPED'   -- status alone isn't a leftmost prefix

Order the columns by how they're actually queried: the column used alone or most selectively goes first.

Covering Indexes and Index-Only Scans

If an index includes every column a query needs, Postgres can answer the query straight from the index without touching the table at all — an Index Only Scan:

CREATE INDEX idx_orders_customer_status_total
    ON orders (customer_id, status) INCLUDE (total_amount);

EXPLAIN ANALYZE
SELECT status, total_amount FROM orders WHERE customer_id = 48291;

Index Only Scan using idx_orders_customer_status_total on orders
  (cost=0.42..4.65 rows=41 width=13) (actual time=0.015..0.028 rows=41 loops=1)
  Index Cond: (customer_id = 48291)
  Heap Fetches: 0

Heap Fetches: 0 confirms the table itself was never read.

When an Index Is NOT Used

The planner will happily ignore an index that exists. Common reasons:

A function wraps the column: WHERE UPPER(email) = 'X' cannot use a plain index on email (a functional index, CREATE INDEX ON users (UPPER(email)), fixes this).
A leading wildcard: WHERE name LIKE '%smith' can't use a standard B-tree — the sorted prefix is useless when you don't know the prefix. LIKE 'smith%' can.
Low selectivity: if 90% of rows match, a Seq Scan is genuinely cheaper than following an index and then fetching almost every row anyway — the planner will (correctly) skip the index.
Implicit type casts: comparing a text column to an integer literal, or a timestamp column to a string that requires parsing, can force a scan. Match types explicitly.

Selectivity and Cardinality

Selectivity is the fraction of rows a condition matches; cardinality is the number of distinct values in a column. An index on a boolean is_active column has cardinality 2 — no matter how the tree is shaped, following it typically still means fetching close to half the table, which costs more than just scanning it. Indexes pay off on high-cardinality, selective columns (customer IDs, emails, timestamps) — not on flags. If you must filter on a low-cardinality column efficiently, pair it in a composite index behind a selective column, or use a partial index (CREATE INDEX ... WHERE is_active = true for a rare status).

Pagination: Keyset vs OFFSET

The earlier ORM post flagged that a LIMIT on top of a collection fetch join doesn't page cleanly. The same physics show up at the SQL level with OFFSET.

-- Deep page: Postgres must still generate and discard the first 100,000 rows
SELECT * FROM orders ORDER BY id LIMIT 20 OFFSET 100000;

OFFSET cannot skip rows using the index alone — it still has to walk past them. Keyset (seek) pagination avoids this by remembering the last row seen and using an indexed condition instead of an offset:

-- Keyset: uses the index on id directly, same cost on page 1 or page 5,000
SELECT * FROM orders WHERE id > :last_seen_id ORDER BY id LIMIT 20;

This requires (and benefits from) an index on the ordering column — exactly the idx_orders_customer_id-style index discussed above.

The JPA/Hibernate Angle

Hibernate generates SQL from JPQL/Criteria queries, but it does not know your query patterns well enough to invent the right indexes — that's still your job, informed by the plans above.

`@Table(indexes = ...)` is a hint, not the source of truth

@Entity
@Table(name = "orders", indexes = {
    @Index(name = "idx_orders_customer_id", columnList = "customer_id"),
    @Index(name = "idx_orders_customer_status", columnList = "customer_id, status")
})
public class Order {
    @Id
    private Long id;

    @Column(name = "customer_id")
    private Long customerId;

    private String status;
    private BigDecimal totalAmount;
}

This annotation only takes effect if Hibernate is generating your DDL (hibernate.hbm2ddl.auto), which production systems should not rely on. Indexes belong in versioned migrations (Flyway or Liquibase), so they're reviewed, ordered, and applied identically across environments:

-- V12__add_orders_customer_status_index.sql (Flyway)
CREATE INDEX CONCURRENTLY idx_orders_customer_status
    ON orders (customer_id, status);

(CONCURRENTLY avoids locking the table for writes while the index builds — worth using on any table already in production.) Keep the @Index annotation as documentation/for test environments that do use hbm2ddl.auto=create, but treat the migration as authoritative.

Spotting a plan-hostile query from Hibernate

Turn on SQL logging to see what Hibernate actually sends:

# application.properties
spring.jpa.show-sql=true
spring.jpa.properties.hibernate.format_sql=true

A JPQL query that looks innocent can generate a function-wrapped predicate that defeats an index:

@Query("SELECT o FROM Order o WHERE FUNCTION('lower', o.status) = :status")
List<Order> findByStatusCaseInsensitive(@Param("status") String status);

This compiles to WHERE lower(status) = ? — exactly the "function on the column" case above. Either add a functional index (CREATE INDEX ON orders (lower(status))) or normalize status on write so the query can compare it directly.

Anti-Patterns

Indexing every column "just in case." Each index slows every write on that table and adds storage; index only columns your real queries filter, join, or sort on.
Redundant indexes. (customer_id) is redundant once (customer_id, status) exists — the composite index already serves lookups on customer_id alone.
Not indexing foreign keys used in joins. Postgres does not automatically index FK columns. A JOIN orders o ON o.customer_id = c.id without an index on orders.customer_id forces a scan on the large side of the join.
Trusting @Table(indexes=...) alone in production. If hbm2ddl.auto isn't generating your schema, that annotation does nothing — the migration is what ships.

Practical Checklist

Situation	Action
Query does a Seq Scan on a large table with a selective filter	Add an index on the filtered column(s)
Filtering/sorting on two columns together	Composite index, most selective / most-used-alone column first
Query reads only indexed columns	Add `INCLUDE` columns for an Index Only Scan
`WHERE UPPER(col) = ...` or leading `%wildcard%`	Functional index or rewrite the predicate
Boolean/low-cardinality filter	Partial index, or pair behind a selective column
Deep pagination (`OFFSET 100000`)	Keyset pagination on an indexed column
FK column used in joins	Explicitly index it — Postgres won't do it for you
Schema managed by JPA entities	Ship the DDL via Flyway/Liquibase, not `hbm2ddl.auto`

Final Thoughts

Indexes are not a checkbox — they're a targeted trade of write cost and storage for read speed, and the only way to know if the trade is worth it is to read the actual query plan. Learn to read EXPLAIN ANALYZE, order composite indexes by how you really query, watch for the handful of things that silently defeat an index, and keep the DDL in migrations where it belongs. The ORM writes the SQL; the query plan tells you the truth about it.

Testing Best Practices in Python

Puneet Gupta — Sat, 04 Jul 2026 15:29:34 +0000

Introduction

Python's testing tools are lightweight enough that it's easy to write a lot of tests without writing good ones. A suite that mocks every collaborator, duplicates the same assertion ten times with different inputs pasted in by hand, or chases a coverage number will pass in CI and still miss real bugs.

pytest gives you fixtures, parametrize, and monkeypatch — the tools that make it just as easy to write the right tests as the wrong ones. This post covers how to use them well.

Test at the Right Level: the Pyramid

Not every test should look the same. The test pyramid is a rough guide to where your effort should go:

Unit tests — the bulk of the suite. Pure functions and classes, no I/O, no real database. Milliseconds each.
Integration tests — fewer of these. Verify the seams: does your ORM query actually produce correct SQL against a real database, does your HTTP client actually parse a real response.
End-to-end tests — a handful. Cover the critical flows through the whole stack, accepting they're slower and more brittle.

# Unit — pure logic, no database, no framework
def test_applies_ten_percent_discount_for_orders_over_100():
    calculator = DiscountCalculator()

    total = calculator.apply(order_total=150.0)

    assert total == pytest.approx(135.0)

# Integration — the seam that matters: our query against a real database
import pytest

@pytest.fixture
def db_session(postgres_container):
    # real Postgres in a test container, not mocked
    with postgres_container.session() as session:
        yield session

def test_finds_orders_placed_in_the_last_week(db_session):
    db_session.add(Order(id="ord-1", placed_at=datetime.now(UTC)))
    db_session.commit()

    recent = order_repository.find_recent(db_session, within=timedelta(days=7))

    assert len(recent) == 1

A unit suite that never touches a database runs in seconds and catches most logic bugs. A handful of integration tests catch what only shows up at the boundary — the query that's syntactically fine but semantically wrong, the serialization mismatch.

Test Behavior, Not Implementation

A test that asserts how a function works internally breaks the moment you refactor, even when the observable behavior hasn't changed. That kind of test actively works against you.

# DON'T: coupled to implementation details
def test_uses_a_list_internally(mocker):
    service = OrderService()
    spy = mocker.spy(service, "_items")  # asserting internal storage

    service.add_item("sku-1")

    assert spy.append.called  # breaks if _items becomes a dict

# DO: coupled to the observable contract
def test_adding_an_item_includes_it_in_the_order_total():
    service = OrderService()
    service.add_item("sku-1", price=25.0)

    assert service.total() == 25.0

If OrderService is rewritten to store items in a dict or a different order internally, the second test still passes as long as total() behaves correctly. That's the point — tests should protect behavior, not internal structure.

Cover the Unhappy Path with `parametrize`

One happy-path test tells you a function works for one input. Real bugs live at the boundaries — empty strings, negative numbers, None, malformed data. @pytest.mark.parametrize runs the same assertion across a matrix of inputs without copy-pasting the test body.

import pytest


@pytest.mark.parametrize("raw", ["80", "443", "8080", "65535"])
def test_parses_valid_ports(raw):
    assert parse_port(raw) == int(raw)


@pytest.mark.parametrize("raw", ["-1", "0", "65536", "not-a-number", ""])
def test_rejects_invalid_ports(raw):
    with pytest.raises(ValueError):
        parse_port(raw)


@pytest.mark.parametrize(
    "a, b, expected",
    [
        (100, 10, 90),
        (0, 5, -5),
        (-20, -20, 0),
    ],
)
def test_subtracts_correctly(a, b, expected):
    assert a - b == expected

pytest.raises asserts a failure mode is a contract, not an accident — the test fails loudly if a future change silently stops rejecting invalid input.

Arrange–Act–Assert, One Assertion per Test

Structure every test in three clear sections and name it after the behavior, not the function under test:

def test_withdrawing_more_than_balance_raises_insufficient_funds():
    # Arrange
    account = Account(balance=50)

    # Act + Assert
    with pytest.raises(InsufficientFundsError):
        account.withdraw(100)

Prefer one logical assertion (or a tightly related group) per test. A name like test_withdrawing_more_than_balance_raises_insufficient_funds reads like a spec — when it fails, you know what broke without opening the test body.

Fixtures for Setup, Test Doubles for Collaborators

pytest fixtures replace repetitive setup and teardown; monkeypatch (or unittest.mock) replaces collaborators.

import pytest


@pytest.fixture
def gateway(mocker):
    return mocker.Mock(spec=PaymentGateway)


@pytest.fixture
def service(gateway):
    return OrderService(gateway=gateway)


def test_placing_an_order_charges_the_gateway(service, gateway):
    gateway.charge.return_value = ChargeResult(success=True, transaction_id="txn-1")

    result = service.place_order(Order(customer_id="cust-1", amount=49.99))

    assert result.is_successful
    gateway.charge.assert_called_once_with("cust-1", 49.99)


def test_gateway_decline_surfaces_as_order_failure(service, gateway):
    gateway.charge.return_value = ChargeResult(success=False, reason="insufficient funds")

    result = service.place_order(Order(customer_id="cust-1", amount=49.99))

    assert not result.is_successful

Mock what you own the interface of — PaymentGateway is our own abstraction over a third-party API, so mocking it (with spec= to keep the mock honest about the real interface) is appropriate.
Don't mock what you don't own. Patching internals of a third-party library (monkeypatch.setattr("requests.Session.send", ...)) couples your tests to that library's implementation and can silently drift from what it actually does. Wrap the dependency behind your own thin interface, then mock that.
Prefer a fake for your own seams when the real behavior is cheap to reproduce — an in-memory dict-backed repository exercises real lookup/insert logic instead of just returning canned values.
Over-mocking is the real anti-pattern. A test that patches five collaborators and asserts every call it made is testing the implementation graph, not the behavior. It breaks on every refactor and proves nothing about correctness. If a test needs that much patching, the function under test is probably doing too much.

Determinism: No Real Clock, Network, or Randomness

A unit test that depends on datetime.now(), a live network call, or random.random() isn't really a unit test — it's a test that fails on Tuesdays, in CI, or 1% of the time for no visible reason. Inject anything non-deterministic, or patch it explicitly at the boundary, so the test controls it.

from datetime import date


class InvoiceService:
    def __init__(self, clock):
        self._clock = clock  # a callable returning "today"

    def generate(self, order):
        return Invoice(order=order, issued_on=self._clock())


def test_invoice_date_matches_the_fixed_clock():
    fixed_clock = lambda: date(2026, 7, 3)
    service = InvoiceService(clock=fixed_clock)

    invoice = service.generate(Order(id="ord-1"))

    assert invoice.issued_on == date(2026, 7, 3)

def test_retry_uses_patched_sleep(monkeypatch):
    sleep_calls = []
    monkeypatch.setattr("time.sleep", lambda seconds: sleep_calls.append(seconds))

    call_with_retry(flaky_operation, max_attempts=3)

    assert len(sleep_calls) == 2  # slept between retries, but the test ran instantly

The same applies to network calls (fake or mock the client) and randomness (inject a seeded random.Random instance). A suite that is fast, isolated, and repeatable is one you can trust to fail only when something is actually broken.

Coverage Is a Signal, Not a Target

A coverage percentage tells you which lines ran during the suite — it says nothing about whether the assertions made were meaningful. It's entirely possible to hit 95% line coverage while asserting almost nothing:

# 100% line coverage, zero value: no assertion on the actual result
def test_calls_calculate():
    calculator = DiscountCalculator()
    calculator.apply(order_total=150.0)  # executed, but the return value is never checked

Chasing a coverage number as the goal rewards exactly this — tests written to touch code rather than to verify it. Use pytest --cov the way you'd use a linter warning: a prompt to look at what's untested, not a pass/fail gate by itself. A __repr__ method at 100% coverage is worth less than a 60%-covered parser with real edge-case assertions.

Practical Checklist

Practice	Why it matters
Match test type to what you're verifying (pyramid)	Fast unit tests catch most bugs; fewer, slower tests catch the rest
Assert behavior, not internals	Tests survive refactors instead of breaking on them
Parametrize input matrices, cover failure modes	Edge cases get exercised, not just the one happy path
Arrange–Act–Assert, one assertion per test	Failures point directly at what broke
Mock what you own, prefer fakes for your own seams	Avoids drift and over-coupling to third-party internals
Inject or patch the clock, network, and randomness	Tests stay fast, isolated, and repeatable
Treat coverage as a signal, not a target	High coverage of trivial code isn't a good test suite

Final Thoughts

A pytest suite earns trust the same way production code does: by being deliberate about what it verifies. Pick the right level for each test, assert the contract instead of the wiring, push failure modes through parametrize, keep collaborators honest with fixtures and monkeypatch used appropriately, and eliminate non-determinism at the source.

Do that, and a green pytest run actually means something — instead of just meaning the tests executed.

Testing Best Practices in Java

Puneet Gupta — Sat, 04 Jul 2026 15:29:34 +0000

Introduction

Most Java codebases have plenty of tests and still get burned by production bugs. The problem is rarely quantity — it's that the tests exercise the wrong things: they assert internal wiring instead of behavior, they mock away every collaborator until nothing real is left, or they cover the happy path ten times and the failure path zero times.

Good tests are fast, deterministic, and tell you something true about behavior. This post covers the practices that make JUnit 5 and Mockito tests actually earn their keep.

Test at the Right Level: the Pyramid

Not every test should be the same shape. The test pyramid is a rough guide to where effort should go:

Unit tests — the bulk of your suite. Pure logic, no I/O, no framework startup. Milliseconds each.
Integration tests — fewer of these. Verify the seams: does your repository actually talk to the real database dialect, does your HTTP client actually parse the real response shape.
End-to-end tests — a handful. Cover the critical user flows through the whole stack, accepting that they're slow and more brittle.

// Unit — pure logic, no Spring context, no database
class DiscountCalculatorTest {

    private final DiscountCalculator calculator = new DiscountCalculator();

    @Test
    void appliesTenPercentForOrdersOverHundred() {
        var total = calculator.apply(new Order(150.0));

        assertEquals(135.0, total, 0.001);
    }
}

// Integration — the seam that matters: our SQL against a real database dialect
@SpringBootTest
@Testcontainers
class OrderRepositoryIntegrationTest {

    @Container
    static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("postgres:16-alpine");

    @Autowired
    private OrderRepository repository;

    @Test
    void findsOrdersPlacedInTheLastWeek() {
        repository.save(new Order("ord-1", Instant.now()));

        var recent = repository.findRecentOrders(Duration.ofDays(7));

        assertThat(recent).hasSize(1);
    }
}

A unit test suite of a thousand tests that never touches a database runs in seconds and catches most logic bugs. A handful of integration tests catch the ones that only show up at the boundary — the dialect quirk, the serialization mismatch.

Test Behavior, Not Implementation

A test that asserts how a method works, rather than what it produces, breaks the moment you refactor — even when the behavior is unchanged. That's a test actively working against you.

// DON'T: coupled to implementation details
@Test
void usesArrayListInternally() {
    var service = new OrderService();
    service.addItem("sku-1");

    verify(service.getInternalList()).add("sku-1"); // brittle, meaningless to callers
}

// DO: coupled to the observable contract
@Test
void addingAnItemIncludesItInTheOrderTotal() {
    var service = new OrderService();
    service.addItem("sku-1", 25.0);

    assertEquals(25.0, service.total());
}

If you rewrite OrderService to use an array, a map, or a different sort order internally, the second test still passes as long as the public contract holds. That's the point: tests should protect behavior, not architecture.

Cover the Unhappy Path with Parameterized Tests

A single happy-path test tells you the code works for one input. Real bugs live at the boundaries — empty input, negative numbers, nulls, malformed strings. @ParameterizedTest lets you assert the same behavior across a whole matrix of inputs without duplicating the test body.

class PortParserTest {

    @ParameterizedTest
    @ValueSource(strings = {"80", "443", "8080", "65535"})
    void parsesValidPorts(String raw) {
        assertDoesNotThrow(() -> PortParser.parse(raw));
    }

    @ParameterizedTest
    @ValueSource(strings = {"-1", "0", "65536", "not-a-number", ""})
    void rejectsInvalidPorts(String raw) {
        assertThrows(IllegalArgumentException.class, () -> PortParser.parse(raw));
    }

    @ParameterizedTest
    @CsvSource({
        "100, 10, 90",
        "0, 5, -5",
        "-20, -20, 0"
    })
    void subtractsCorrectly(int a, int b, int expected) {
        assertEquals(expected, a - b);
    }
}

assertThrows is the tool for asserting a failure mode is a contract, not an accident — the test fails loudly if a future change silently stops rejecting invalid input.

Arrange–Act–Assert, One Assertion per Test

Structure every test in three clear sections, and give it a name that states the behavior, not the method under test:

@Test
void withdrawingMoreThanBalanceThrowsInsufficientFundsException() {
    // Arrange
    var account = new Account(BigDecimal.valueOf(50));

    // Act + Assert
    assertThrows(InsufficientFundsException.class,
        () -> account.withdraw(BigDecimal.valueOf(100)));
}

Prefer one logical assertion (or one tightly related group) per test. shouldDoX_whenY style names read like a spec: when this test fails, its name tells you what broke without opening the body.

Test Doubles: Mock, Stub, Fake — and When Not To

Mockito makes it easy to replace a collaborator, but "easy" is not the same as "correct."

class OrderServiceTest {

    private final PaymentGateway gateway = mock(PaymentGateway.class);
    private final OrderService service = new OrderService(gateway);

    @BeforeEach
    void setUp() {
        // fresh mocks per test — no shared state leaking between tests
    }

    @Test
    void placingAnOrderChargesTheGateway() {
        when(gateway.charge(any(), eq(BigDecimal.valueOf(49.99))))
            .thenReturn(ChargeResult.success("txn-1"));

        var result = service.placeOrder(new Order("cust-1", BigDecimal.valueOf(49.99)));

        assertTrue(result.isSuccessful());
        verify(gateway).charge(eq("cust-1"), eq(BigDecimal.valueOf(49.99)));
    }

    @Test
    void gatewayDeclineSurfacesAsOrderFailure() {
        when(gateway.charge(any(), any())).thenReturn(ChargeResult.declined("insufficient funds"));

        var result = service.placeOrder(new Order("cust-1", BigDecimal.valueOf(49.99)));

        assertFalse(result.isSuccessful());
    }
}

Mock what you own the interface of — PaymentGateway is our own abstraction over a third party, so mocking it is fine.
Don't mock what you don't own. Mocking a third-party library's internal classes couples your tests to that library's implementation details, and the mock can silently drift from what the real library actually does. Wrap the dependency behind your own interface, then mock that.
Prefer a fake for your own seams when the real behavior is cheap to reproduce — an in-memory Map-backed repository is more honest than a mock that returns canned values, because it actually exercises lookup/insert logic.
Over-mocking is the real anti-pattern. A test that mocks five collaborators and verifies ten interactions is asserting the implementation graph, not the behavior. It breaks on every refactor and tells you nothing about correctness. If a test needs that much setup, the class under test probably has too many responsibilities.

Determinism: No Real Clock, Network, or Randomness

A unit test that depends on the wall clock, the network, or Math.random() is not really a unit test — it's a test that fails on Tuesdays, or in CI, or 1% of the time for no visible reason. Inject anything non-deterministic so it can be controlled in the test.

public class InvoiceService {
    private final Clock clock;

    public InvoiceService(Clock clock) {
        this.clock = clock;
    }

    public Invoice generate(Order order) {
        return new Invoice(order, LocalDate.now(clock));
    }
}

@Test
void invoiceDateMatchesTheFixedClock() {
    var fixedClock = Clock.fixed(Instant.parse("2026-07-03T00:00:00Z"), ZoneOffset.UTC);
    var service = new InvoiceService(fixedClock);

    var invoice = service.generate(new Order("ord-1"));

    assertEquals(LocalDate.of(2026, 7, 3), invoice.date());
}

The same applies to network calls (fake or mock the client) and randomness (inject a seeded Random or a supplier you control). A test suite that is fast, isolated, and repeatable is one you can trust to fail only when something is actually broken.

Coverage Is a Signal, Not a Target

A number on a coverage report tells you which lines ran during the suite — it says nothing about whether the right assertions were made. It is entirely possible to hit 95% line coverage while asserting almost nothing meaningful:

// 100% line coverage, zero value: no assertion on the actual result
@Test
void callsCalculate() {
    var calculator = new DiscountCalculator();
    calculator.apply(new Order(150.0)); // executed, but never checked
}

Chasing a coverage percentage as the goal incentivizes exactly this: tests written to touch code rather than to verify it. Use coverage the way you'd use a linter warning — as a prompt to look at what's untested, not as a pass/fail gate on its own. A getter with 100% coverage and no branches is worth less than a 60%-covered parser with real edge-case assertions.

Practical Checklist

Practice	Why it matters
Match test type to what you're verifying (pyramid)	Fast unit tests catch most bugs; fewer, slower tests catch the rest
Assert behavior, not internals	Tests survive refactors instead of breaking on them
Parameterize input matrices, cover failure modes	Edge cases get exercised, not just the one happy path
Arrange–Act–Assert, one assertion per test	Failures point directly at what broke
Mock what you own, prefer fakes for your own seams	Avoids drift and over-coupling to third-party internals
Inject the clock, network, and randomness	Tests stay fast, isolated, and repeatable
Treat coverage as a signal, not a target	High coverage of trivial code isn't a good test suite

Final Thoughts

A test suite earns trust the same way production code does: by being deliberate about what it verifies. Pick the right level for each test, assert the contract instead of the wiring, push failure modes through parameterized cases, keep collaborators honest with mocks and fakes used appropriately, and eliminate non-determinism at the source.

Do that, and a green build actually means something — instead of just meaning the tests ran.

Building Agentic Workflows in Python

Puneet Gupta — Sat, 04 Jul 2026 15:29:32 +0000

Introduction

"Agent" has become the word for any program that calls an LLM more than once, which makes it a word worth being precise about. An agent, in the sense this post uses, is a loop: the model decides which tool to call next, your code executes it, and the result feeds back in — repeating until the model decides it's done. That's a genuinely different (and riskier) shape than a single request/response call.

This post builds on Building Reliable LLM Applications in Python: everything said there about retries, structured output, and evaluation still applies once you add a loop — it just applies to every iteration, and now the model is also choosing which side effects to trigger. We'll cover when an agent is actually warranted, the loop itself (manual and SDK-assisted), and the safety controls that make handing a model the wheel defensible.

When to Build an Agent — and When Not To

Reach for an agent only when the task is genuinely multi-step and open-ended: the number and order of actions can't be known ahead of time, so a fixed pipeline can't express it. Most tasks that feel agentic are actually better served by something simpler and more debuggable. There's a ladder, and you should stop climbing it the moment the task is satisfied:

A single LLM call. Classify this ticket. Summarize this document. If one prompt in, one answer out solves it, that's the whole system.
A code-orchestrated workflow. A fixed sequence of LLM calls and deterministic steps — call the model to extract fields, validate them in code, call the model again to draft a reply. The order of steps is known in advance and lives in Python, not in the model's head.
An agent. The model itself decides which tool to call, how many times, and in what order, based on what it learns from each result. Reserve this for tasks where that open-endedness is the point — a research assistant that doesn't know in advance how many searches it needs, a debugging helper that has to react to whatever the last command printed.

Before building step 3, run the task past four checks. If any answer is "no," stay at step 1 or 2:

Complexity — is the task actually variable enough that a fixed sequence can't express it? If you can already write down the steps, write them down — in code, not in a system prompt.
Value — does solving it well matter enough to justify the added latency, cost, and failure surface of a loop? A loop that runs five model calls to do what one call could do is a net loss.
Viability — can the model reliably succeed at each step with the tools you can realistically give it? An agent whose tools are unreliable or ambiguous will loop, retry the wrong thing, or confidently do the wrong thing with confidence.
Cost of error — what happens when it gets a step wrong? An agent that can send an email or delete a record needs a fundamentally different safety posture than one that only reads.

An agent is a deliberate escalation, not a default. Most production LLM features never need one.

The Agentic Loop

Once an agent is warranted, the shape is the same regardless of the tools involved: call the model with a list of available tools; if it responds asking to use one (stop_reason == "tool_use"), execute that tool in your own code and send the result back as a tool_result; repeat until the model responds with end_turn. Two ways to run that loop in Python — write it by hand for full control, or let the SDK's tool runner drive it for you.

The Manual Loop — Full Control

Writing the loop yourself means every tool call passes through your code before it executes, which is where you validate arguments, log the decision, and gate anything irreversible:

import anthropic

client = anthropic.Anthropic()  # reads ANTHROPIC_API_KEY from env — never hardcode

MAX_ITERATIONS = 10

messages = [{"role": "user", "content": user_input}]
iterations = 0

while True:
    iterations += 1
    if iterations > MAX_ITERATIONS:
        raise RuntimeError("Agent exceeded iteration cap — stopping")

    response = client.messages.create(
        model="claude-opus-4-8",
        max_tokens=16000,
        thinking={"type": "adaptive"},
        tools=tools,
        messages=messages,
    )

    if response.stop_reason == "end_turn":
        break

    tool_use_blocks = [b for b in response.content if b.type == "tool_use"]

    # Log the assistant turn (including any tool_use requests) before acting on it
    messages.append({"role": "assistant", "content": response.content})

    tool_results = []
    for tool in tool_use_blocks:
        # Validate BEFORE executing — tool.input is model-provided, untrusted data
        result = execute_validated_tool(tool.name, tool.input)
        tool_results.append({
            "type": "tool_result",
            "tool_use_id": tool.id,
            "content": result,
        })
    messages.append({"role": "user", "content": tool_results})

final_text = next(b.text for b in response.content if b.type == "text")

Two things earn their keep here that a convenience runner would hide: the MAX_ITERATIONS cap, and the log point right before the tool result round-trip. Both are cheap to add and expensive to retrofit after an agent has looped in production for an hour.

The SDK Tool Runner — Convenience

When you don't need to intercept every call — a low-stakes, read-only agent, or a prototype — the beta tool runner drives the same loop for you. Decorate a plain function with @beta_tool; its docstring becomes the tool description the model sees:

from anthropic import beta_tool

@beta_tool
def get_weather(location: str) -> str:
    """Get current weather for a location.

    Args:
        location: City and state, e.g. San Francisco, CA.
    """
    return f"Sunny, 72°F in {location}"

runner = client.beta.messages.tool_runner(
    model="claude-opus-4-8",
    max_tokens=16000,
    tools=[get_weather],
    messages=[{"role": "user", "content": "Weather in Paris?"}],
)
for message in runner:
    ...  # each iteration is a BetaMessage; loop ends when Claude is done

The trade-off is explicit: the runner is fewer lines, but your validation and approval logic has to live inside the tool function rather than at a single choke point between the model and execution. For anything past a read-only demo, the manual loop's explicit checkpoint is worth the extra code.

Determinism Where It Matters

The loop's shape — how many iterations are allowed, what counts as done, how a failed tool call is retried — belongs in Python, not in a system prompt asking the model to "keep trying until it works." As covered in Building Reliable LLM Applications in Python, use the model for judgment (which tool, with what arguments, when to stop) and code for bookkeeping (the loop, the retry policy, the cap, the audit log). An agent that reasons its own way through retry logic in natural language is slower, more expensive, and less predictable than an except block that already knows what to do with a transient failure.

Structured Hand-offs Between Steps

Free-text hand-offs between agent steps are where errors compound silently — a slightly malformed field from step two becomes a wrong argument in step three's tool call. Where a step's output needs to be used by the next step (not just displayed to a person), get it back as a validated, typed object instead of prose to re-parse:

from pydantic import BaseModel

class PlanStep(BaseModel):
    action: str
    done: bool

response = client.messages.parse(
    model="claude-opus-4-8",
    max_tokens=16000,
    messages=[{"role": "user", "content": "What is the next step, and are we done?"}],
    output_format=PlanStep,
)

step = response.parsed_output   # a validated PlanStep, not a string to parse
if step.done:
    ...  # stop the loop deterministically — no guessing from prose

A validated PlanStep either parses or raises; there's no regex trying to guess whether the model meant "done" or "we're basically done."

Safety and Cost — Mandatory, Not Optional

An agent is a program that decides, at runtime, which of your functions to call and with what arguments — based on text it read. Treat every tool as an attack surface accordingly:

Validate and whitelist tool inputs. tool.input (or a tool function's arguments) is model-provided data and must be treated as untrusted, exactly like a request body from the network. Whitelist allowed values, bound numeric ranges, and reject anything that doesn't fit the tool's contract before it reaches your execution code — never string-interpolate a model-supplied argument into a shell command or a SQL query.
Require human approval before irreversible or outward-facing actions. Reading a file or querying an API is one risk tier; sending an email, deleting a record, or moving money is another. Gate the latter behind an explicit approval step — a human confirmation, a dry-run preview, or at minimum a hard-coded allowlist of safe operations — never let the model's own judgment be the last check before an irreversible effect.
Cap loop iterations. Every agentic loop needs a hard MAX_ITERATIONS (or a wall-clock timeout). Without one, a confused model can loop indefinitely, burning tokens and possibly retrying a failing tool call forever.
Track token cost and latency as first-class metrics. An agent's cost is the sum of every iteration, not one call — instrument response.usage per turn and alert on runaway loops the same way you'd alert on a runaway retry storm.
Never hardcode API keys. Every example above reads ANTHROPIC_API_KEY via anthropic.Anthropic() — no key ever appears in source, config committed to version control, or logs.

Practical Takeaways

Climb the ladder only as far as the task requires: single call → code-orchestrated workflow → agent. Most tasks stop at step one or two.
Run the four checks — complexity, value, viability, cost of error — before building a loop; any "no" is a reason to stay simpler.
The manual loop trades verbosity for a single choke point to validate, log, and gate every tool call; the SDK tool runner trades that control for convenience — pick deliberately, not by default.
Keep control flow (the loop, retries, the iteration cap) in Python; keep the model doing judgment.
Use structured, typed hand-offs between steps instead of parsing prose.
Validate tool inputs as untrusted data, gate irreversible actions behind approval, cap iterations, and instrument cost — an agent without these is a liability, not a feature.

Building Agentic Workflows in Java

Puneet Gupta — Sat, 04 Jul 2026 15:29:32 +0000

Introduction

This post builds on Building Reliable LLM Applications in Java: everything said there about retries, typed output, and evaluation still applies once you add a loop — it just applies to every iteration, and now the model is also choosing which side effects to trigger. We'll cover when an agent is actually warranted, the loop itself (manual and SDK-assisted), and the safety controls that make handing a model the wheel defensible.

When to Build an Agent — and When Not To

A single LLM call. Classify this ticket. Summarize this document. If one prompt in, one answer out solves it, that's the whole system.
A code-orchestrated workflow. A fixed sequence of LLM calls and deterministic steps — call the model to extract fields, validate them in code, call the model again to draft a reply. The order of steps is known in advance and lives in Java, not in the model's head.
An agent. The model itself decides which tool to call, how many times, and in what order, based on what it learns from each result. Reserve this for tasks where that open-endedness is the point — a research assistant that doesn't know in advance how many searches it needs, a debugging helper that has to react to whatever the last command printed.

Before building step 3, run the task past four checks. If any answer is "no," stay at step 1 or 2:

Complexity — is the task actually variable enough that a fixed sequence can't express it? If you can already write down the steps, write them down — in code, not in a system prompt.
Value — does solving it well matter enough to justify the added latency, cost, and failure surface of a loop? A loop that runs five model calls to do what one call could do is a net loss.
Viability — can the model reliably succeed at each step with the tools you can realistically give it? An agent whose tools are unreliable or ambiguous will loop, retry the wrong thing, or confidently do the wrong thing with confidence.
Cost of error — what happens when it gets a step wrong? An agent that can send an email or delete a record needs a fundamentally different safety posture than one that only reads.

An agent is a deliberate escalation, not a default. Most production LLM features never need one.

The Agentic Loop

Once an agent is warranted, the shape is the same regardless of the tools involved: call the model with a list of available tools; if it responds asking to use one (stop_reason is tool_use), execute that tool in your own code and send the result back as a tool_result; repeat until the model responds with end_turn. Two ways to run that loop in Java — write it by hand for full control, or let the SDK's tool runner drive it for you.

The Manual Loop — Full Control

Writing the loop yourself means every tool call passes through your code before it executes, which is where you validate arguments, log the decision, and gate anything irreversible:

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.messages.*;
import java.util.List;
import java.util.ArrayList;

AnthropicClient client = AnthropicOkHttpClient.fromEnv(); // reads ANTHROPIC_API_KEY

List<MessageParam> messages = new ArrayList<>();
messages.add(MessageParam.builder()
    .role(MessageParam.Role.USER)
    .content(userInput)
    .build());

Message response;
int iterations = 0;
while (true) {
    if (++iterations > MAX_ITERATIONS) {
        throw new IllegalStateException("Agent exceeded iteration cap — stopping");
    }

    MessageCreateParams params = MessageCreateParams.builder()
        .model(Model.CLAUDE_OPUS_4_8)
        .maxTokens(16000L)
        .thinking(ThinkingConfigAdaptive.builder().build())
        .tools(tools)
        .messages(messages)
        .build();

    response = client.messages().create(params);

    if (response.stopReason().isPresent()
            && response.stopReason().get().toString().equals("end_turn")) {
        break;
    }

    // Log the assistant turn (including any tool_use requests) before acting on it
    messages.add(MessageParam.builder()
        .role(MessageParam.Role.ASSISTANT)
        .contentOfBlockParams(toBlockParams(response.content()))
        .build());

    List<ContentBlockParam> toolResults = new ArrayList<>();
    for (ContentBlock block : response.content()) {
        block.toolUse().ifPresent(toolUse -> {
            // Validate BEFORE executing — tool.input is model-provided, untrusted data
            String result = executeValidatedTool(toolUse.name(), toolUse.input());
            toolResults.add(ContentBlockParam.ofToolResult(
                ToolResultBlockParam.builder()
                    .toolUseId(toolUse.id())
                    .content(result)
                    .build()));
        });
    }
    messages.add(MessageParam.builder()
        .role(MessageParam.Role.USER)
        .contentOfBlockParams(toolResults)
        .build());
}

The SDK Tool Runner — Convenience

When you don't need to intercept every call — a low-stakes, read-only agent, or a prototype — the beta tool runner drives the same loop for you. Define each tool as a small class implementing Supplier, annotated so the SDK can derive its JSON schema:

import com.anthropic.models.beta.messages.MessageCreateParams;
import com.anthropic.models.beta.messages.BetaMessage;
import com.anthropic.helpers.BetaToolRunner;
import com.fasterxml.jackson.annotation.JsonClassDescription;
import com.fasterxml.jackson.annotation.JsonPropertyDescription;
import java.util.function.Supplier;

@JsonClassDescription("Get the weather in a given location")
static class GetWeather implements Supplier<String> {
    @JsonPropertyDescription("The city and state, e.g. San Francisco, CA")
    public String location;

    @Override
    public String get() {
        return "Sunny, 72F in " + location;
    }
}

BetaToolRunner runner = client.beta().messages().toolRunner(
    MessageCreateParams.builder()
        .model("claude-opus-4-8")
        .maxTokens(16000L)
        .addTool(GetWeather.class)
        .addUserMessage("What's the weather in San Francisco?")
        .build());

for (BetaMessage message : runner) {
    // each iteration is a BetaMessage; the loop ends when Claude is done
}

The trade-off is explicit: the runner is fewer lines, but your validation and approval logic has to live inside the tool's get() method rather than at a single choke point between the model and execution. For anything past a read-only demo, the manual loop's explicit checkpoint is worth the extra code.

Determinism Where It Matters

The loop's shape — how many iterations are allowed, what counts as done, how a failed tool call is retried — belongs in Java, not in a system prompt asking the model to "keep trying until it works." As covered in Building Reliable LLM Applications in Java, use the model for judgment (which tool, with what arguments, when to stop) and code for bookkeeping (the loop, the retry policy, the cap, the audit log). An agent that reasons its own way through retry logic in natural language is slower, more expensive, and less predictable than a catch block that already knows what to do with a transient failure.

Structured Hand-offs Between Steps

Free-text hand-offs between agent steps are where errors compound silently — a slightly malformed field from step two becomes a wrong argument in step three's tool call. Where a step's output needs to be used by the next step (not just displayed to a person), get it back as a typed, schema-validated object instead of prose to re-parse:

import com.anthropic.models.messages.StructuredMessageCreateParams;

record PlanStep(String action, boolean done) {}

StructuredMessageCreateParams<PlanStep> params = MessageCreateParams.builder()
    .model(Model.CLAUDE_OPUS_4_8)
    .maxTokens(16000L)
    .outputConfig(PlanStep.class)
    .addUserMessage("What is the next step, and are we done?")
    .build();

client.messages().create(params).content().stream()
    .flatMap(block -> block.text().stream())
    .forEach(typed -> {
        PlanStep step = typed.text(); // a validated PlanStep, not a String to parse
        if (step.done()) {
            // stop the loop deterministically — no guessing from prose
        }
    });

A typed PlanStep either deserializes or it doesn't; there's no regex trying to guess whether the model meant "done" or "we're basically done."

Safety and Cost — Mandatory, Not Optional

An agent is a program that decides, at runtime, which of your functions to call and with what arguments — based on text it read. Treat every tool as an attack surface accordingly:

Validate and whitelist tool inputs. toolUse.input() is model-provided data and must be treated as untrusted, exactly like a request body from the network. Whitelist allowed values, bound numeric ranges, and reject anything that doesn't fit the tool's contract before it reaches your execution code — never string-interpolate a model-supplied argument into a shell command or a SQL query.
Require human approval before irreversible or outward-facing actions. Reading a file or querying an API is one risk tier; sending an email, deleting a record, or moving money is another. Gate the latter behind an explicit approval step — a human confirmation, a dry-run preview, or at minimum a hard-coded allowlist of safe operations — never let the model's own judgment be the last check before an irreversible effect.
Cap loop iterations. Every agentic loop needs a hard MAX_ITERATIONS (or a wall-clock timeout). Without one, a confused model can loop indefinitely, burning tokens and possibly retrying a failing tool call forever.
Track token cost and latency as first-class metrics. An agent's cost is the sum of every iteration, not one call — instrument usage() per turn and alert on runaway loops the same way you'd alert on a runaway retry storm.
Never hardcode API keys. Every example above reads ANTHROPIC_API_KEY via AnthropicOkHttpClient.fromEnv() — no key ever appears in source, config committed to version control, or logs.

Practical Takeaways

Climb the ladder only as far as the task requires: single call → code-orchestrated workflow → agent. Most tasks stop at step one or two.
Run the four checks — complexity, value, viability, cost of error — before building a loop; any "no" is a reason to stay simpler.
The manual loop trades verbosity for a single choke point to validate, log, and gate every tool call; the SDK tool runner trades that control for convenience — pick deliberately, not by default.
Keep control flow (the loop, retries, the iteration cap) in Java; keep the model doing judgment.
Use structured, typed hand-offs between steps instead of parsing prose.
Validate tool inputs as untrusted data, gate irreversible actions behind approval, cap iterations, and instrument cost — an agent without these is a liability, not a feature.

Designing for Change: Boundaries, Contracts, and Dependency Inversion in Python

Puneet Gupta — Sat, 04 Jul 2026 15:29:30 +0000

Introduction

Python's flexibility makes it easy to wire everything together directly — call the requests library from inside your business logic, import the ORM model straight into your pricing rules, instantiate a third-party SDK client wherever it's needed. It works, right up until the payment provider changes, or you want a fast unit test that doesn't need a live database.

Designing for change means drawing boundaries around the parts of the system likely to move — third-party services, storage, transport — so that a swap or a test double touches one small adapter instead of rippling through the codebase.

This post covers the practical mechanics in Python: Protocol and ABC for dependency inversion, a ports-and-adapters shape for a small service, and frozen dataclasses that make invalid states impossible to construct. Python needs no framework for any of it.

Coupling, Cohesion, and the Cost of Guessing Wrong

Coupling is how much one module knows about another's internals; cohesion is how tightly a module's own responsibilities hang together. The classic mistake is coupling business logic directly to something volatile because it's the fastest way to get a feature working:

# Tightly coupled: checkout() cannot run, or be tested, without a live Stripe account
import stripe

stripe.api_key = os.environ["STRIPE_KEY"]

def checkout(order: Order) -> None:
    stripe.Charge.create(amount=order.total_cents, currency="usd")
    # ...

This ships fast — but adding a second payment provider, unit-testing checkout without the network, or absorbing a breaking SDK change all become edits to checkout itself, not an isolated adapter swap.

The fix isn't "wrap everything in an abstraction." It's abstracting specifically at the seams likely to vary — I/O, third-party services, storage — and leaving pure computation (a discount calculation, a tax rule) as plain functions with no interface at all, because there's no second implementation and nothing to swap.

Dependency Inversion Without a Framework: `Protocol` and `ABC`

Python offers two idiomatic ways to define a contract the core code depends on, instead of a concrete implementation.

typing.Protocol gives you structural typing — anything with the right method shape satisfies the contract, with no inheritance required:

from typing import Protocol

class PaymentGateway(Protocol):
    def charge(self, amount: "Money", customer_reference: str) -> "PaymentResult": ...

from dataclasses import dataclass

@dataclass(frozen=True)
class Money:
    amount_minor_units: int
    currency_code: str

    def __post_init__(self) -> None:
        if self.amount_minor_units < 0:
            raise ValueError(f"amount cannot be negative: {self.amount_minor_units}")
        if len(self.currency_code) != 3:
            raise ValueError(f"currency_code must be a 3-letter ISO code: {self.currency_code!r}")

@dataclass(frozen=True)
class PaymentResult:
    approved: bool
    provider_reference: str

A concrete adapter — the only place that imports the third-party SDK — satisfies the Protocol just by having a matching charge method, with no explicit implements:

class StripePaymentGateway:
    def __init__(self, client: "stripe.Client") -> None:
        self._client = client

    def charge(self, amount: Money, customer_reference: str) -> PaymentResult:
        result = self._client.charges.create(
            amount=amount.amount_minor_units, currency=amount.currency_code
        )
        return PaymentResult(approved=result.is_successful, provider_reference=result.id)

The core depends only on the Protocol, injected through the constructor:

class OrderService:
    def __init__(self, payment_gateway: PaymentGateway) -> None:
        self._payment_gateway = payment_gateway

    def checkout(self, order: "Order") -> PaymentResult:
        amount = Money(order.total_minor_units, order.currency_code)
        return self._payment_gateway.charge(amount, order.customer_id)

OrderService never imports stripe. A test can pass any object with a matching charge method — a plain function, a lambda-like callable, or a hand-written fake — with zero mocking framework and zero inheritance:

class FakeGateway:
    def charge(self, amount: Money, customer_reference: str) -> PaymentResult:
        return PaymentResult(approved=True, provider_reference="fake-1")

def test_checkout_returns_approved_result() -> None:
    service = OrderService(payment_gateway=FakeGateway())
    order = Order(order_id="ord-1", customer_id="cust-1", total_minor_units=1999, currency_code="USD")

    result = service.checkout(order)

    assert result.approved is True

If you'd rather force implementers to explicitly opt in (nominal typing, useful when the contract carries real behavioral guarantees beyond method shape), abc.ABC is the alternative:

from abc import ABC, abstractmethod

class PaymentGatewayABC(ABC):
    @abstractmethod
    def charge(self, amount: Money, customer_reference: str) -> PaymentResult: ...

Either way, no framework is involved — this is constructor injection with plain Python objects. A framework like FastAPI's Depends or a DI container can automate the wiring, but the design decision (OrderService depends on an abstraction, not a concrete SDK) holds with or without one.

Ports and Adapters: The Domain Core Stays Framework-Free

The same idea structures a whole service: a domain core that defines ports (Protocols) for what it needs, and adapters at the edges that implement those ports against real infrastructure.

from typing import Protocol, Optional

class OrderRepository(Protocol):
    def find_by_id(self, order_id: str) -> Optional["Order"]: ...
    def save(self, order: "Order") -> None: ...

# Domain core: depends only on the ports, knows nothing about SQL or the ORM
class OrderProcessor:
    def __init__(self, repository: OrderRepository, payment_gateway: PaymentGateway) -> None:
        self._repository = repository
        self._payment_gateway = payment_gateway

    def process_payment(self, order_id: str) -> PaymentResult:
        order = self._repository.find_by_id(order_id)
        if order is None:
            raise LookupError(f"no order with id {order_id}")

        result = self._payment_gateway.charge(
            Money(order.total_minor_units, order.currency_code), order.customer_id
        )
        if result.approved:
            self._repository.save(order.mark_paid())
        return result

An in-memory adapter makes the core trivially testable — no database, no fixtures, no test containers:

class InMemoryOrderRepository:
    def __init__(self) -> None:
        self._store: dict[str, Order] = {}

    def find_by_id(self, order_id: str) -> Optional[Order]:
        return self._store.get(order_id)

    def save(self, order: Order) -> None:
        self._store[order.order_id] = order

def test_process_payment_marks_order_paid_when_charge_approved() -> None:
    repository = InMemoryOrderRepository()
    repository.save(Order("ord-1", "cust-1", 1999, "USD", paid=False))
    processor = OrderProcessor(repository=repository, payment_gateway=FakeGateway())

    result = processor.process_payment("ord-1")

    assert result.approved is True
    assert repository.find_by_id("ord-1").paid is True

A production adapter — SqlAlchemyOrderRepository, backed by a real session — implements the same OrderRepository shape and is wired in only at the application's composition root (where the app starts up), never imported by name inside OrderProcessor:

        ┌─────────────────────────────┐
        │        Domain Core          │
        │  OrderProcessor, Order,     │
        │  Money  (no I/O imports)    │
        └───────────┬─────────────────┘
                     │ depends on (ports/Protocols)
        ┌────────────┴─────────────┐
        │ OrderRepository           │  PaymentGateway
        └───┬───────────────┬──────┘
            │               │
   InMemoryOrderRepository  StripePaymentGateway   (adapters, at the edges)
   SqlAlchemyOrderRepository

Make Invalid States Unrepresentable

Money above already does this: frozen=True makes it immutable after construction, and __post_init__ runs its validation on the only path an instance can come into existence — there's no setter later that could skip the check.

Extend that to state transitions with an Enum instead of a loose status: str or a paid: bool flag that fails to capture "cancelled" at all:

from dataclasses import dataclass, replace
from enum import Enum, auto

class OrderStatus(Enum):
    PENDING = auto()
    PAID = auto()
    CANCELLED = auto()

@dataclass(frozen=True)
class Order:
    order_id: str
    customer_id: str
    total_minor_units: int
    currency_code: str
    status: OrderStatus = OrderStatus.PENDING

    def mark_paid(self) -> "Order":
        if self.status is not OrderStatus.PENDING:
            raise ValueError(f"cannot mark paid from status {self.status.name}")
        return replace(self, status=OrderStatus.PAID)

mark_paid returns a new Order rather than mutating in place — combined with frozen=True, an Order object can never silently drift into an inconsistent state from some far-away code path holding a reference to it. The guard clause makes the illegal transition (paying an already-cancelled order) raise immediately rather than corrupt state quietly.

For a stricter, type-checker-enforced version of the same idea, a small tagged union of dataclasses (mirroring the sealed-type pattern) works too — but for most services, a validated Enum plus a guarded transition method is the pragmatic default; reach for the union when different statuses genuinely carry different data (e.g., only a Cancelled variant has a reason field).

When Not to Do This

Every Protocol, every extra layer of indirection, has a cost: more files to open when tracing a call, and the real risk of premature abstraction — building a seam for a second implementation that never shows up.

Don't add a Protocol for:

A small, stable, in-house helper with no plausible second implementation and no test-isolation pressure.
Pure functions (formatting, arithmetic, validation rules) with no I/O — there's nothing to swap.
A prototype or one-off script where the entire point is learning fast, not building for reuse.

The signal a seam is worth it: you already have, or clearly will have, a second implementation — or the boundary is genuinely volatile I/O (a paid API, a datastore, a queue). Absent either, an interface is speculative generality: extra indirection for a change that may never come, making the one real implementation harder to read for no offsetting benefit.

Practical Takeaways

Practice	Why it matters
Depend on `Protocol`/`ABC` at I/O boundaries, not concrete SDKs	Swapping a provider touches one adapter, not the core
Inject dependencies through `__init__`, no framework required	Dependencies are explicit and easy to fake in tests
Keep the domain core free of SDK/ORM imports	The core stays portable and fast to test
Give every port an in-memory adapter for tests	Unit tests run with no network, no database
Validate in `__post_init__` on frozen dataclasses	Invalid objects simply cannot exist
Model state with `Enum` + guarded transitions (or tagged unions)	Illegal transitions raise instead of corrupting state
Don't add a `Protocol` with no second implementation	Premature abstraction costs more than it saves

Designing for change is a bet on where things will vary, not a guarantee against all future work. Spend the abstraction budget at the boundaries most likely to move — third-party services, storage, transport — and leave the stable, purely internal logic simple, direct, and framework-free.

Designing for Change: Boundaries, Contracts, and Dependency Inversion in Java

Puneet Gupta — Sat, 04 Jul 2026 15:29:29 +0000

Introduction

Most Java systems don't fail because a single class was written badly. They fail because the boundaries between classes were drawn in the wrong place — a database library leaks into business logic, a payment provider's SDK shows up in twelve unrelated files, and changing one third-party dependency means touching half the codebase.

Designing for change is not about predicting the future correctly. It's about isolating what varies so that when it inevitably does vary — a new payment provider, a swapped database, a different message broker — the blast radius is one adapter, not the whole system.

This post covers the practical mechanics: dependency inversion, ports-and-adapters, and making illegal states impossible to construct — plus where to stop.

Coupling, Cohesion, and the Cost of Guessing Wrong

Two forces pull against each other in every design:

Coupling — how much one module knows about another's internals. Low coupling means you can change a module without rippling changes elsewhere.
Cohesion — how tightly a module's responsibilities belong together. High cohesion means a class has one clear reason to change.

The classic mistake is coupling business logic directly to volatile, external things — HTTP clients, ORMs, cloud SDKs — because that's the fastest way to get something working:

// Tightly coupled: OrderService cannot exist without Stripe's SDK
public class OrderService {
    private final StripeClient stripeClient = new StripeClient(System.getenv("STRIPE_KEY"));

    public void checkout(Order order) {
        stripeClient.charges().create(order.totalCents(), "usd");
        // ...
    }
}

This compiles, ships, and works — until you need to add a second payment provider, or write a test without hitting the network, or the SDK does a breaking major-version bump. Every one of those becomes a rewrite of OrderService itself, not an isolated change.

The fix is not "add an abstraction for everything." It's to abstract specifically at the seams that are likely to vary: I/O, third-party services, storage. A pure computation with no external dependency (tax calculation, discount rules) usually doesn't need an interface at all — that would be an abstraction with no second implementation and no real caller-side benefit, just extra indirection to read through.

Dependency Inversion: Program to an Interface

The Dependency Inversion Principle says high-level policy (the order workflow) should not depend on low-level detail (a specific payment SDK). Both should depend on an abstraction owned by the high-level side:

// The core defines the contract it needs — no import of any SDK
public interface PaymentGateway {
    PaymentResult charge(Money amount, String customerReference);
}

public record Money(long amountMinorUnits, String currencyCode) {
    public Money {
        if (amountMinorUnits < 0) {
            throw new IllegalArgumentException("amount cannot be negative: " + amountMinorUnits);
        }
        if (currencyCode == null || currencyCode.length() != 3) {
            throw new IllegalArgumentException("currencyCode must be a 3-letter ISO code: " + currencyCode);
        }
    }
}

public record PaymentResult(boolean approved, String providerReference) {}

A concrete adapter implements the interface and is the only place that imports the third-party SDK:

public final class StripePaymentGateway implements PaymentGateway {
    private final StripeClient client;

    public StripePaymentGateway(StripeClient client) {
        this.client = client;
    }

    @Override
    public PaymentResult charge(Money amount, String customerReference) {
        var charge = client.charges().create(amount.amountMinorUnits(), amount.currencyCode());
        return new PaymentResult(charge.isSuccessful(), charge.id());
    }
}

The order workflow now depends only on the interface, injected through its constructor:

public final class OrderService {
    private final PaymentGateway paymentGateway;

    // Constructor injection: the dependency is explicit, required, and immutable
    public OrderService(PaymentGateway paymentGateway) {
        this.paymentGateway = paymentGateway;
    }

    public PaymentResult checkout(Order order) {
        var amount = new Money(order.totalMinorUnits(), order.currencyCode());
        return paymentGateway.charge(amount, order.customerId());
    }
}

OrderService compiles and runs with zero knowledge of Stripe, a competitor's SDK, or a fake used in tests. Swapping providers means writing one new adapter class — OrderService never changes.

A framework like Spring can wire new StripePaymentGateway(...) into OrderService's constructor automatically via @Bean/@Autowired, but nothing above requires it — this is plain constructor injection, and you could wire it by hand in a main method just as validly. The design decision (depend on the interface) is independent of whether a DI container does the wiring.

Ports and Adapters: The Domain Core Stays Framework-Free

Zoom out from a single dependency and the same idea structures the whole application: a domain core in the center that defines ports (interfaces) for everything it needs from the outside world, and adapters at the edges that implement those ports against real infrastructure.

// Port — owned by the domain, expresses what the domain needs, not how storage works
public interface OrderRepository {
    Optional<Order> findById(String orderId);
    void save(Order order);
}

// Domain core: depends only on the port, knows nothing about SQL or JDBC
public final class OrderProcessor {
    private final OrderRepository repository;
    private final PaymentGateway paymentGateway;

    public OrderProcessor(OrderRepository repository, PaymentGateway paymentGateway) {
        this.repository = repository;
        this.paymentGateway = paymentGateway;
    }

    public PaymentResult processPayment(String orderId) {
        var order = repository.findById(orderId)
            .orElseThrow(() -> new NoSuchElementException("no order with id " + orderId));
        var result = paymentGateway.charge(
            new Money(order.totalMinorUnits(), order.currencyCode()), order.customerId());
        if (result.approved()) {
            repository.save(order.markPaid());
        }
        return result;
    }
}

An in-memory adapter makes the core trivially testable, with no database and no test containers:

public final class InMemoryOrderRepository implements OrderRepository {
    private final Map<String, Order> store = new HashMap<>();

    @Override
    public Optional<Order> findById(String orderId) {
        return Optional.ofNullable(store.get(orderId));
    }

    @Override
    public void save(Order order) {
        store.put(order.orderId(), order);
    }
}

@Test
void processPayment_marksOrderPaid_whenChargeApproved() {
    var repository = new InMemoryOrderRepository();
    repository.save(new Order("ord-1", "cust-1", 1999, "USD", false));
    var processor = new OrderProcessor(repository, (amount, ref) -> new PaymentResult(true, "px_1"));

    var result = processor.processPayment("ord-1");

    assertTrue(result.approved());
    assertTrue(repository.findById("ord-1").orElseThrow().paid());
}

Notice the test passes a lambda as the PaymentGateway — since it's a single-method interface, no mocking framework is required for this seam. A production adapter (JdbcOrderRepository, backed by a real DataSource) implements the same OrderRepository port and is wired in only at the application's composition root (main, or a Spring @Configuration class) — never referenced by name inside OrderProcessor.

        ┌─────────────────────────────┐
        │        Domain Core          │
        │   OrderProcessor, Order,    │
        │   Money  (no I/O imports)   │
        └───────────┬─────────────────┘
                     │ depends on (ports)
        ┌────────────┴─────────────┐
        │ OrderRepository           │  PaymentGateway
        └───┬───────────────┬──────┘
            │               │
   InMemoryOrderRepository  StripePaymentGateway   (adapters, at the edges)
   JdbcOrderRepository

Make Invalid States Unrepresentable

The Money record above already does this: it is impossible to construct a Money with a negative amount or a malformed currency code, because the compact constructor validates on every construction path — there is no way to get an instance into an invalid state later. Compare that to a class with a public setter for amount that some far-away code path forgets to validate.

Sealed hierarchies extend the same idea to state transitions. An order shouldn't be payable twice, and a cancelled order shouldn't be payable at all — encode that in the type instead of a boolean flag and scattered if checks:

public sealed interface OrderStatus permits Pending, Paid, Cancelled {}
public record Pending() implements OrderStatus {}
public record Paid(String providerReference) implements OrderStatus {}
public record Cancelled(String reason) implements OrderStatus {}

public PaymentResult processPayment(Order order, PaymentGateway gateway) {
    return switch (order.status()) {
        case Paid p -> throw new IllegalStateException("order already paid: " + p.providerReference());
        case Cancelled c -> throw new IllegalStateException("order cancelled: " + c.reason());
        case Pending p -> gateway.charge(order.amount(), order.customerId());
    };
}

The switch over a sealed interface is exhaustive — the compiler rejects the code if a fourth OrderStatus variant is ever added and this method isn't updated. A boolean isPaid field offers no such guarantee; it's easy to leave a call site unhandled.

When Not to Do This

Every interface, every port, every extra layer has a cost: more files to navigate, more indirection to trace through when reading the code, and a real risk of premature abstraction — building a seam for a second implementation that never arrives.

Don't introduce a PaymentGateway-style interface for:

A single, stable, in-house utility with no plausible second implementation and no test-isolation need.
Pure logic (tax rules, string formatting) that has no I/O and nothing to swap.
A prototype or spike where the entire point is to learn something before committing to a design.

The signal that a seam is earning its keep is concrete: you have (or clearly will have) a second implementation, or the boundary is exactly the kind of volatile I/O this post is about (a paid third-party service, a datastore, a queue). Abstracting "in case we need it later" without either of those is speculative generality — it adds a layer of indirection for a change that may never come, and makes the one implementation you do have harder to read for no offsetting benefit.

Practical Takeaways

Practice	Why it matters
Depend on interfaces at I/O boundaries, not concrete SDKs	Swapping a provider touches one adapter, not the core
Inject dependencies through the constructor	Dependencies are explicit, required, and easy to fake in tests
Keep the domain core free of framework/SDK imports	The core stays portable and fast to test
Give every port an in-memory adapter for tests	Unit tests run with no network, no database
Validate in constructors (records, compact constructors)	Invalid objects simply cannot exist
Model state transitions with sealed types, not booleans	The compiler enforces exhaustive handling
Don't abstract a seam with no second implementation	Premature abstraction costs more than it saves

Building Reliable LLM Applications in Java

Puneet Gupta — Sat, 04 Jul 2026 15:29:29 +0000

Introduction

LLMs are usually associated with Python, but a great deal of production software — banking, enterprise backends, long-lived services — runs on the JVM, and those systems increasingly need to call language models too. Java's strong typing and mature tooling are genuine assets here: they push you toward exactly the discipline reliable LLM applications require.

The core mindset is the same in any language: treat model output as a hypothesis to verify, not a fact to trust. This post covers the practices that make Java LLM applications production-grade, using Anthropic's Claude and the official anthropic-java SDK.

Pick the Right Model for the Task

Model choice is a decision, not a default. Match the tier to the difficulty of the task — the strongest model for hard reasoning, a cheaper capable model for high-volume simple work:

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.messages.MessageCreateParams;
import com.anthropic.models.messages.Model;

AnthropicClient client = AnthropicOkHttpClient.fromEnv(); // reads ANTHROPIC_API_KEY

MessageCreateParams params = MessageCreateParams.builder()
    .model(Model.CLAUDE_OPUS_4_8)   // strongest tier for hard tasks
    .maxTokens(4096L)
    .addUserMessage("...")
    .build();

For high-volume classification, Model.CLAUDE_HAIKU_4_5 costs a fraction as much. Never run an expensive model where a cheap one suffices; cost and latency are features to track, not afterthoughts.

Get Typed Output — Don't Parse Prose

The biggest source of fragility in LLM apps is scraping structured data out of free-form text. Java's type system makes the better path natural: define a record for the shape you want and let the SDK derive a JSON schema, constrain the model to it, and hand you back a typed object.

import com.anthropic.models.messages.StructuredMessageCreateParams;
import java.util.List;

record Invoice(String vendor, double total, String dueDate) {}

StructuredMessageCreateParams<Invoice> params = MessageCreateParams.builder()
    .model(Model.CLAUDE_OPUS_4_8)
    .maxTokens(1024L)
    .outputConfig(Invoice.class)            // schema derived from the record
    .addUserMessage("Extract invoice fields:\n" + rawText)
    .build();

client.messages().create(params).content().stream()
    .flatMap(block -> block.text().stream())
    .forEach(typed -> {
        Invoice invoice = typed.text();     // a validated Invoice, not a String
        System.out.println(invoice.total()); // a double — no manual JSON parsing
    });

This turns "the model usually returns JSON" into "the model returns this record." No ObjectMapper gymnastics, no defensive null-checking of hand-parsed fields.

Ground the Model — Don't Let It Hallucinate

An LLM will confidently invent facts. For anything that must be correct, supply the source material and instruct the model to answer only from it, with an explicit escape hatch:

String prompt = """
    Answer the question using ONLY the context below.
    If the answer is not in the context, say "I don't know."

    <context>
    %s
    </context>

    Question: %s""".formatted(retrievedDocuments, userQuestion);

The "only from context" instruction plus the "say I don't know" escape hatch together stop the model from fabricating to fill a gap. For auditability, have it cite which passage it used so a human can verify.

Handle the Unhappy Path

Networks fail and rate limits happen. The Java SDK retries transient errors (429, 5xx, connection failures) with backoff — configure it rather than reinventing it:

AnthropicClient client = AnthropicOkHttpClient.builder()
    .fromEnv()
    .maxRetries(4)
    .build();

Catch typed exceptions and branch on retryable vs. terminal — a 400 is a bug in your request, not something to retry:

import com.anthropic.errors.RateLimitException;
import com.anthropic.errors.BadRequestException;

try {
    client.messages().create(params);
} catch (RateLimitException e) {
    // back off and retry
} catch (BadRequestException e) {
    // malformed request — fix the payload, do NOT retry
    throw e;
}

For any operation with side effects driven by a model decision — a payment, an outbound email — make it idempotent. A retry, or the model, may trigger the same action twice.

Put Control Flow in Code, Judgment in the Model

Use the model for judgment; use Java for bookkeeping. Loops, branching, and fan-out belong in deterministic code. For tool-using (agentic) tasks, drive the loop yourself so you can validate, gate, and log every tool call before executing it:

// Pseudocode shape — loop until the model stops requesting tools
while (true) {
    Message response = client.messages().create(paramsWithTools);
    if ("end_turn".equals(response.stopReason().orElse(null))) {
        break;
    }
    for (ContentBlock block : response.content()) {
        block.toolUse().ifPresent(toolUse -> {
            // YOUR code decides whether this call is allowed, then executes it
            String result = executeValidatedTool(toolUse.name(), toolUse.input());
            // append a tool_result and continue the loop
        });
    }
}

The model decides what to do; your code decides whether it's permitted and records what happened. This is where Java's guardrails — type checks, validation at boundaries, explicit error handling — pay off.

Evaluate Output Like Any Other Untrusted Input

You wouldn't ship a method without a JUnit test. Don't ship a prompt without an eval. Keep a small dataset of representative inputs with known-good outputs and score the model against it whenever you change a prompt or switch models:

double evaluate(List<TestCase> cases) {
    long passed = cases.stream()
        .filter(c -> extractInvoice(c.input()).total() == c.expectedTotal())
        .count();
    return (double) passed / cases.size();
}

Evals catch the regression where a prompt tweak that helped one case quietly broke ten others — the LLM equivalent of a failing test suite.

Cache Repeated Context to Cut Cost and Latency

When many requests share a large fixed prefix — a system prompt, a big document, few-shot examples — prompt caching serves that prefix at a fraction of the cost and latency. Mark the stable block with a cache control and keep it first:

import com.anthropic.models.messages.TextBlockParam;
import com.anthropic.models.messages.CacheControlEphemeral;
import java.util.List;

MessageCreateParams params = MessageCreateParams.builder()
    .model(Model.CLAUDE_OPUS_4_8)
    .maxTokens(1024L)
    .systemOfTextBlockParams(List.of(
        TextBlockParam.builder()
            .text(largeSharedContext)
            .cacheControl(CacheControlEphemeral.builder().build())
            .build()))
    .addUserMessage(question)
    .build();

Message response = client.messages().create(params);
System.out.println(response.usage().cacheReadInputTokens()); // >0 means cache hit

Caching is a prefix match — put the stable content first and anything that varies per request (the user's question, a timestamp) after it. If cacheReadInputTokens stays zero across repeated calls, something volatile is invalidating the prefix.

Practical Checklist

Practice	Why it matters
Match model tier to task difficulty	Don't overpay or under-provision
Use typed structured outputs	Records, not hand-parsed JSON
Ground answers in provided context + cite	Curbs hallucination
Configure SDK retries; catch typed exceptions	Survive transients, fail fast on bugs
Make side-effecting actions idempotent	Retries and re-decisions are safe
Control flow in code, judgment in the model	Deterministic, debuggable
Keep an eval set; score on every change	Catch prompt/model regressions
Cache large shared prefixes	Lower cost and latency
Never send secrets/PII you don't need to	Anything sent externally may be retained

Final Thoughts

Reliable LLM applications aren't built by finding the perfect prompt. They're built with the same engineering discipline Java developers already practice: strong types at the boundary, verification of untrusted output, deterministic control flow, explicit error handling, and measurable tests.

The model provides judgment. The typed, tested, guard-railed system around it is what makes that judgment safe to depend on — and that system is exactly the kind of thing the JVM ecosystem is built to run well.

Building Reliable LLM Applications in Python

Puneet Gupta — Sat, 04 Jul 2026 15:29:27 +0000

Introduction

Calling an LLM API is easy. Building an application on top of one that is reliable — that fails predictably, doesn't hallucinate its way into wrong answers, and doesn't surprise you with a bill — is a real engineering discipline.

The core mindset shift: treat model output as a hypothesis to verify, not a fact to trust. This post covers the practices that make Python LLM applications production-grade, using Anthropic's Claude and the official anthropic SDK.

Pick the Right Model for the Task

Model choice is a decision, not a default. Match the tier to the difficulty of the task:

import anthropic

client = anthropic.Anthropic()  # reads ANTHROPIC_API_KEY from the environment

# Hard reasoning / agentic work → the strongest model
response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=4096,
    messages=[{"role": "user", "content": "..."}],
)

# High-volume, cost-sensitive classification → a cheaper capable model
cheap = client.messages.create(
    model="claude-haiku-4-5",
    max_tokens=256,
    messages=[{"role": "user", "content": "Classify sentiment: ..."}],
)

Never run an expensive model where a cheap one suffices, and never under-provision where quality matters. Cost and latency are features — track them.

Get Structured Output — Don't Parse Prose

The single biggest source of fragility in LLM apps is scraping structured data out of free-form text. Prefer typed outputs validated against a schema. With the Anthropic SDK, messages.parse() validates the response against a Pydantic model for you:

from pydantic import BaseModel

class Invoice(BaseModel):
    vendor: str
    total: float
    due_date: str

response = client.messages.parse(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[{"role": "user", "content": f"Extract invoice fields:\n{raw_text}"}],
    output_format=Invoice,
)

invoice = response.parsed_output   # a validated Invoice instance
print(invoice.total)               # a float, guaranteed — no regex, no json.loads

The validation happens against a schema the model is constrained to, so you get a typed object instead of a string you have to hope parses. Structured output turns "the model usually returns JSON" into "the model returns this shape."

Ground the Model — Don't Let It Hallucinate

An LLM will confidently invent facts. For anything that must be correct, give the model the source material and instruct it to answer only from that material — retrieval-augmented generation (RAG) in its simplest form:

prompt = f"""Answer the question using ONLY the context below.
If the answer is not in the context, say "I don't know."

<context>
{retrieved_documents}
</context>

Question: {user_question}"""

Two things make this reliable: the explicit "only from context" instruction, and an explicit escape hatch ("say I don't know") so the model isn't pressured to fabricate. Then cite — have the model point at which passage it used, so a human can verify.

Handle the Unhappy Path

Networks fail and rate limits happen. The Anthropic SDK already retries transient errors (429, 5xx, connection errors) with exponential backoff — configure it rather than reinventing it:

client = anthropic.Anthropic(max_retries=4, timeout=30.0)

Catch the specific exceptions and branch on retryable vs. terminal:

try:
    response = client.messages.create(...)
except anthropic.RateLimitError as exc:
    retry_after = int(exc.response.headers.get("retry-after", "60"))
    # back off and retry
except anthropic.BadRequestError:
    # a 400 is a bug in our request — do NOT retry, fix the payload
    raise

For any operation with side effects (charging a card, sending an email based on a model decision), make it idempotent — the model, or a retry, may trigger the same action twice.

Put Control Flow in Code, Judgment in the Model

Use the model for judgment; use code for bookkeeping. Loops, branching, and fan-out belong in deterministic Python — not in a prompt asking the model to "keep going until done." For agentic tasks with tools, drive the loop yourself so you can intercept, validate, and log each tool call:

messages = [{"role": "user", "content": user_input}]
while True:
    response = client.messages.create(
        model="claude-opus-4-8", max_tokens=4096,
        tools=tools, messages=messages,
    )
    if response.stop_reason == "end_turn":
        break
    messages.append({"role": "assistant", "content": response.content})

    tool_results = []
    for block in response.content:
        if block.type == "tool_use":
            result = execute_tool(block.name, block.input)   # YOUR validated code
            tool_results.append({
                "type": "tool_result",
                "tool_use_id": block.id,
                "content": result,
            })
    messages.append({"role": "user", "content": tool_results})

The model decides what to do; your code decides whether it's allowed and records what happened.

Evaluate Output Like Any Other Untrusted Input

You wouldn't ship a function without tests. Don't ship a prompt without evals. Build a small dataset of representative inputs with known-good outputs, and score the model against it whenever you change a prompt or model:

def evaluate(cases: list[dict]) -> float:
    passed = 0
    for case in cases:
        out = extract_invoice(case["input"])
        if out.total == case["expected_total"]:
            passed += 1
    return passed / len(cases)

Evals catch the regression where a prompt tweak that helped one case quietly broke ten others — the LLM equivalent of a failing unit test.

Cache Repeated Context to Cut Cost and Latency

If many requests share a large fixed prefix — a system prompt, a big document, few-shot examples — prompt caching serves that prefix at a fraction of the price and latency:

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    system=[{
        "type": "text",
        "text": large_shared_context,
        "cache_control": {"type": "ephemeral"},
    }],
    messages=[{"role": "user", "content": question}],
)
# Verify it worked:
print(response.usage.cache_read_input_tokens)  # >0 means the cache was hit

Caching is a prefix match: keep the stable content first and put anything that varies per request (timestamps, the user's question) after it. If cache_read_input_tokens stays zero across repeated calls, something volatile is invalidating the prefix.

Practical Checklist

Practice	Why it matters
Match model tier to task difficulty	Don't overpay or under-provision
Use structured outputs, not prose parsing	Typed data, no brittle regex
Ground answers in provided context + cite	Curbs hallucination
Configure SDK retries; branch on error type	Survive transient failures, fail fast on bugs
Make side-effecting actions idempotent	Retries and re-decisions are safe
Control flow in code, judgment in the model	Deterministic, debuggable
Keep an eval set; score on every change	Catch prompt/model regressions
Cache large shared prefixes	Lower cost and latency
Never send secrets/PII you don't need to	Anything sent externally may be retained

Final Thoughts

Reliable LLM applications aren't built by finding the perfect prompt. They're built with the same engineering discipline as any other system: strong typing at the boundary, verification of untrusted output, deterministic control flow, graceful failure handling, and measurable evaluation.

The model provides judgment. Everything around it — the structure, the checks, the guardrails — is your job. Get that right, and the LLM becomes a dependable component instead of a source of surprises.

Avoiding ORM Traps and the N+1 Problem in Python

Puneet Gupta — Sat, 04 Jul 2026 15:29:26 +0000

Introduction

Python's ORMs — SQLAlchemy and the Django ORM — are a joy to write and dangerously easy to make slow. A loop over a queryset that reads one related field can silently fire hundreds of queries. It looks fine in development and falls over on real data.

This post covers the ORM traps Python teams hit most, starting with the N+1 query problem, in both SQLAlchemy and Django.

The N+1 Problem

You load authors and print each author's book count:

# Django
for author in Author.objects.all():        # 1 query
    print(author.books.count())             # 1 query PER author

# SQLAlchemy
for author in session.query(Author).all():  # 1 query
    print(len(author.books))                # 1 lazy-load query PER author

One query to fetch the authors, then N more — one per author — to fetch each author's books. A hundred authors is 101 round trips. It works on three test rows and collapses in production.

Fix It: Eager Loading

Django — `select_related` and `prefetch_related`

select_related — for forward ForeignKey/OneToOne. Uses a SQL join, one query.
prefetch_related — for reverse FKs and ManyToMany. Runs a second query and joins in Python.

# One query for authors + one for all their books, joined in Python
for author in Author.objects.prefetch_related("books"):
    print(len(author.books.all()))

# Forward FK: a single join query
for book in Book.objects.select_related("author"):
    print(book.author.name)

SQLAlchemy — `selectinload` and `joinedload`

from sqlalchemy.orm import selectinload, joinedload

# selectinload: a 2nd query with WHERE author_id IN (...) — best for collections
authors = session.query(Author).options(selectinload(Author.books)).all()

# joinedload: a single LEFT JOIN — best for many-to-one / one-to-one
books = session.query(Book).options(joinedload(Book.author)).all()

A good rule of thumb: selectinload for to-many collections (avoids row multiplication), joinedload for to-one relations.

Don't Fetch Whole Objects to Read a Few Columns

Hydrating full model instances to display two fields wastes memory and time. Select only what you need.

# Django: .values() / .only() skip full model construction
Author.objects.values("name", "email")            # dicts, no model overhead
Author.objects.only("name")                        # deferred other columns

# SQLAlchemy: select specific columns
session.query(Author.name, Author.email).all()

For aggregates, push the work into the database rather than counting in Python:

# Django: annotate a count in SQL — no N+1, no Python-side counting
from django.db.models import Count
Author.objects.annotate(num_books=Count("books"))

Pagination Pitfalls

Two things bite here.

1. Counting for pagination is a full second query. LIMIT/OFFSET pagination runs a COUNT(*) to compute total pages, which can be expensive on large tables. For big datasets prefer keyset (cursor) pagination — WHERE id > :last_seen ORDER BY id LIMIT n — which stays fast regardless of how deep you page.

2. Slicing after a to-many prefetch/join can multiply or mis-limit rows. As in Java's JPA, a LIMIT applied on top of a collection join doesn't page the way you expect. In Django, prefetch_related sidesteps this by issuing a separate query; slice the base queryset (Author.objects.all()[:20]) and let the prefetch fetch relations for that page.

Beware Implicit Lazy Loads Outside a Session

In SQLAlchemy, accessing a relationship after the Session is closed raises DetachedInstanceError. In Django, touching a related object in a template after the request's DB work is done can quietly re-query. The fix is the same in both: load everything the caller needs while the session/request is open, using eager loading — don't rely on lazy access leaking out of scope.

Always Look at the Queries

The ORM hides the SQL; make it visible in development.

# Django: inspect queries actually run
from django.db import connection
print(len(connection.queries))     # with DEBUG=True
# or use django-debug-toolbar to see counts and duplicates per request

# SQLAlchemy: echo generated SQL
engine = create_engine(url, echo=True)

Most ORM performance bugs are invisible in the Python and obvious in the query log. Watching the query count is how you catch an N+1 before your users do.

Practical Checklist

Trap	Django fix	SQLAlchemy fix
N+1 on forward FK	`select_related`	`joinedload`
N+1 on collection / M2M	`prefetch_related`	`selectinload`
Fetching whole objects to read	`.values()` / `.only()`	select columns
Counting in Python	`annotate(Count(...))`	`func.count()`
Deep `OFFSET` pagination	keyset pagination	keyset pagination
Lazy load out of scope	eager-load in request	eager-load in session

Final Thoughts

SQLAlchemy and the Django ORM are fast enough for almost anything — if you tell them how to load related data. Default to eager loading at the call sites that need relations, select only the columns you'll use, keep aggregation in the database, and watch the query count during development. The ORM's job is to hide SQL; your job is to make sure it isn't hiding an N+1.

Avoiding ORM Traps and the N+1 Problem in Java

Puneet Gupta — Sat, 04 Jul 2026 15:29:25 +0000

Introduction

An ORM like JPA/Hibernate makes database access feel like working with plain objects. That is exactly the problem: a single innocent-looking loop can fire hundreds of SQL queries, and you won't see it until production slows to a crawl.

This post covers the ORM traps that bite Java teams most often — starting with the notorious N+1 query problem — and the concrete techniques that fix them.

The N+1 Problem

Consider loading authors and printing their books:

List<Author> authors = authorRepository.findAll();   // 1 query
for (Author author : authors) {
    System.out.println(author.getBooks().size());     // 1 query EACH
}

With a lazy @OneToMany, this runs 1 query to fetch the authors, then N more — one per author — to fetch each author's books. One hundred authors means 101 round trips to the database. That is N+1.

The insidious part: it works perfectly in tests with three rows and quietly melts under real data.

Fix It With a Fetch Join

Tell the ORM to load the association in the same query using a JOIN FETCH:

@Query("SELECT DISTINCT a FROM Author a LEFT JOIN FETCH a.books")
List<Author> findAllWithBooks();

This produces a single SQL query with a join. DISTINCT collapses the duplicate author rows the join produces. One query instead of 101.

For a more reusable option, an entity graph declares what to fetch without hand-writing JPQL:

@EntityGraph(attributePaths = "books")
List<Author> findAll();

Understand Lazy vs Eager — and Default to Lazy

JPA associations have a fetch type:

LAZY — the association is loaded only when accessed.
EAGER — it is always loaded, on every query that touches the entity.

Making associations EAGER to "avoid N+1" is a classic mistake: now every query drags the association along, even when you don't need it, and multiple eager collections can trigger a Cartesian-product explosion. Default to LAZY and fetch explicitly (join fetch / entity graph) at the specific call sites that need the data.

Note that @ManyToOne and @OneToOne are EAGER by default — usually worth overriding to LAZY.

Don't Load Entities You Only Read — Use Projections

Fetching full entities to display three columns wastes memory and forces the persistence context to track objects you'll immediately discard. A projection selects only what you need:

public interface AuthorSummary {
    String getName();
    int getBookCount();
}

@Query("""
    SELECT a.name AS name, COUNT(b) AS bookCount
    FROM Author a LEFT JOIN a.books b
    GROUP BY a.id, a.name
    """)
List<AuthorSummary> findSummaries();

The generated SQL selects two columns and aggregates in the database — no entity hydration, no lazy associations, far less garbage.

Beware Pagination With Fetch Joins

Combining JOIN FETCH on a collection with pagination (setMaxResults) is a trap. Because the join multiplies rows, the database can't correctly apply the LIMIT — so Hibernate silently pulls the entire result set into memory and paginates there, often logging a warning like firstResult/maxResults specified with collection fetch; applying in memory.

The fix is a two-step fetch: page the IDs first, then fetch the collections for that page.

// Step 1: page the root IDs only (safe LIMIT)
List<Long> ids = em.createQuery(
        "SELECT a.id FROM Author a ORDER BY a.name", Long.class)
    .setFirstResult(offset).setMaxResults(pageSize).getResultList();

// Step 2: fetch full entities + collections for just those IDs
List<Author> page = em.createQuery(
        "SELECT DISTINCT a FROM Author a LEFT JOIN FETCH a.books WHERE a.id IN :ids", Author.class)
    .setParameter("ids", ids).getResultList();

Watch the Transaction Boundary: LazyInitializationException

Access a lazy association after the persistence context has closed and you get a LazyInitializationException. The right fix is to load what the caller needs inside the transaction (via fetch join / entity graph / a DTO), not to keep the session open across the web layer (the "Open Session in View" anti-pattern, which hides N+1 and holds connections too long).

Always Look at the Generated SQL

The ORM's convenience hides its cost. During development, log the actual SQL and watch the query count:

# application.properties
spring.jpa.show-sql=true
spring.jpa.properties.hibernate.format_sql=true
# Even better: add datasource-proxy or Hibernate statistics to count queries

Most ORM performance bugs are invisible in the Java code and obvious the moment you read the SQL log. Make looking at it a habit.

Practical Checklist

Trap	Fix
N+1 from lazy collections in a loop	`JOIN FETCH` or `@EntityGraph`
Everything `EAGER`	Default `LAZY`, fetch explicitly
Loading entities to read a few fields	Projections / DTOs
Pagination + collection fetch join	Page IDs, then fetch by ID
`LazyInitializationException`	Load inside the transaction
Hidden query counts	Log and read the SQL

Final Thoughts

JPA and Hibernate are powerful precisely because they hide the database — and dangerous for the same reason. The discipline that keeps ORM code fast is simple: default to lazy loading, fetch exactly what each use case needs and no more, project when you're only reading, and always look at the SQL the ORM actually generates. The abstraction is a convenience, not an excuse to stop thinking about queries.

DEV Community: Puneet Gupta

Database Indexing and Query Optimization for Python Developers

Introduction

How Indexes Work: The B-Tree Intuition

Reading Query Plans: EXPLAIN ANALYZE

Composite Indexes and Column Order

Covering Indexes and Index-Only Scans

When an Index Is NOT Used

Selectivity and Cardinality

Pagination: Keyset vs OFFSET

The Django and SQLAlchemy Angle

Django — Meta.indexes and db_index

SQLAlchemy — Index(...) / index=True + Alembic

Spotting a plan-hostile query

Anti-Patterns

Practical Checklist

Final Thoughts

Database Indexing and Query Optimization for Java Developers

Introduction

How Indexes Work: The B-Tree Intuition

Reading Query Plans: EXPLAIN ANALYZE

Composite Indexes and Column Order

Covering Indexes and Index-Only Scans

When an Index Is NOT Used

Selectivity and Cardinality

Pagination: Keyset vs OFFSET

The JPA/Hibernate Angle

@Table(indexes = ...) is a hint, not the source of truth

Spotting a plan-hostile query from Hibernate

Anti-Patterns

Practical Checklist

Final Thoughts

Testing Best Practices in Python

Introduction

Test at the Right Level: the Pyramid

Test Behavior, Not Implementation

Cover the Unhappy Path with parametrize

Arrange–Act–Assert, One Assertion per Test

Fixtures for Setup, Test Doubles for Collaborators

Determinism: No Real Clock, Network, or Randomness

Coverage Is a Signal, Not a Target

Practical Checklist

Final Thoughts

Testing Best Practices in Java

Introduction

Test at the Right Level: the Pyramid

Test Behavior, Not Implementation

Cover the Unhappy Path with Parameterized Tests

Arrange–Act–Assert, One Assertion per Test

Test Doubles: Mock, Stub, Fake — and When Not To

Determinism: No Real Clock, Network, or Randomness

Coverage Is a Signal, Not a Target

Practical Checklist

Final Thoughts

Building Agentic Workflows in Python

Introduction

When to Build an Agent — and When Not To

The Agentic Loop

The Manual Loop — Full Control

The SDK Tool Runner — Convenience

Determinism Where It Matters

Structured Hand-offs Between Steps

Safety and Cost — Mandatory, Not Optional

Practical Takeaways

Building Agentic Workflows in Java

Introduction

When to Build an Agent — and When Not To

The Agentic Loop

The Manual Loop — Full Control

The SDK Tool Runner — Convenience

Determinism Where It Matters

Structured Hand-offs Between Steps

Safety and Cost — Mandatory, Not Optional

Practical Takeaways

Designing for Change: Boundaries, Contracts, and Dependency Inversion in Python

Introduction

Coupling, Cohesion, and the Cost of Guessing Wrong

Dependency Inversion Without a Framework: Protocol and ABC

Ports and Adapters: The Domain Core Stays Framework-Free

Make Invalid States Unrepresentable

Django — `Meta.indexes` and `db_index`

SQLAlchemy — `Index(...)` / `index=True` + Alembic

`@Table(indexes = ...)` is a hint, not the source of truth

Cover the Unhappy Path with `parametrize`

Dependency Inversion Without a Framework: `Protocol` and `ABC`

Django — `select_related` and `prefetch_related`

SQLAlchemy — `selectinload` and `joinedload`