concresce 1.0.0

Transparent temporal coalescing and inline micro-batching for Python.

concresce 💧

Transparent temporal coalescing and inline micro-batching.

Standard solutions to N+1 database or network bottlenecks require spinning up external message queues, background workers, or complex task graphs. concresce solves this dynamically. You write the function as if it processes a single item, and the runtime transparently merges concurrent calls into a single batch in the background.

uv add concresce

The Difference

Concept	Standard Async Loop	Message Queues (Celery/Kafka)	concresce
Network Footprint	N requests for N items.	1 request for N items.	1 request for N items.
Architectural Overhead	None.	High (Requires external broker).	None (Pure inline code).
Return Routing	Native variables.	Complex (Webhooks / Polling).	Native variables (Futures resolve).

Usage

You need exactly two primitives: @batch to define the barrier constraint, and collect() to suspend the execution and pool data.

There is zero configuration. The batch window is dynamically defined by the event loop's microtask queue. The routing is handled natively by your return types.

import asyncio
from concresce import batch, collect

@batch
async def fetch_user_score(user_id):
    # 1. Execution pauses here.
    # Concurrent calls inside the current event loop tick pool their `user_id`s.
    batch_ids = await collect(user_id)

    # 2. Only ONE execution path (the leader) resumes from this point.
    # The others remain safely suspended via Exception-driven control flow.
    print(f"Making 1 network call for {len(batch_ids)} users...")
    bulk_results = await db.bulk_fetch_scores(batch_ids)

    # 3. The leader returns the raw bulk list or dictionary.
    # The decorator natively maps and distributes the results back to the followers.
    return bulk_results


async def main():
    # Fire off 5 requests simultaneously
    results = await asyncio.gather(
        fetch_user_score(1),
        fetch_user_score(2),
        fetch_user_score(3),
        fetch_user_score(4),
        fetch_user_score(5)
    )

    # Returns:[100, 250, 190, 300, 120]
    print(results)

asyncio.run(main())

Core Mechanics

• Event Loop Batching: There are no arbitrary max_size or max_window timers to tune. concresce yields exactly once (await asyncio.sleep(0)) to the event loop. Under heavy load, batches are massive. Under low load, batches execute instantly. The tuning emerges purely from the traffic itself.
• Native Type Routing: The leader does not need to call a special scatter function. If your database returns a list, the system unzips it by index. If it returns out-of-order or missing data, just return a dictionary ({id: result}) and concresce handles exact key-based routing automatically.
• Fault Propagation: If the leader crashes during the heavy processing phase, the exception is intercepted and safely replicated to all suspended followers. Nobody hangs, and the stack unwinds naturally.