async-kinesis AGENTS.md

Guidance for AI coding agents working in the async-kinesis repository.

This file defines repository-specific operating rules for autonomous or semi-autonomous coding agents. Follow these instructions unless a maintainer explicitly tells you otherwise.

---

Project Overview

async-kinesis is an AsyncIO-based Python library for producing to and consuming from AWS Kinesis Data Streams. It is published to PyPI as async-kinesis and consumed as a library by downstream services.

• Python: 3.10 - 3.14
• Core deps: aiobotocore, async-timeout, asyncio-throttle
• Optional extras: redis, dynamodb, prometheus, kpl, msgpack, cli, testing

---

First Principles

When making changes, follow these priorities:

1. Correctness over convenience
2. Keep the public API stable (this is a library; downstream consumers depend on it)
3. Add tests for new bugs, edge cases, and behaviour changes
4. Narrow, focused changes; avoid drive-by refactors
5. Prefer editing existing code over introducing new abstractions

Critical rules:

• Do not change public method signatures or exception types without a clear deprecation story
• Do not add backwards-compatibility shims for features that never shipped; just change the code
• Do not silently swallow exceptions, specifically in checkpointer / producer / consumer paths
• Document behaviour changes in the PR body (Summary + Backwards compatibility). Release notes are generated from tagged GitHub releases; there is no CHANGELOG.md

---

Package Layout

kinesis/
  base.py            # Shared async client setup and aiobotocore lifecycle
  producer.py        # Producer: batching, aggregation, flush
  consumer.py        # Consumer: shard iteration, checkpointing hook, metrics
  checkpointers.py   # MemoryCheckPointer, RedisCheckPointer
  dynamodb.py        # DynamoDBCheckPointer
  aggregators.py     # KPL aggregation helpers
  serializers.py     # JSON / msgpack serializers
  processors.py      # Record post-processing hooks
  metrics.py         # Metrics collector interface
  prometheus.py      # Prometheus adapter for metrics
  exceptions.py      # Public exception types
  testing.py         # In-memory mock Producer/Consumer + pytest plugin
  timeout_compat.py  # async-timeout / asyncio.timeout shim across Python versions
  utils.py           # Shared helpers
  cli/               # Optional CLI (install with [cli] extra)

tests/               # Integration + unit tests (Floci + redis for integration)
docs/                # User-facing documentation