gunn.storage package

Submodules

gunn.storage.dedup_store module

Deduplication storage using SQLite for intent idempotency.

This module provides persistent storage for intent deduplication with TTL cleanup and warmup guards for relaxed deduplication after restart.

class gunn.storage.dedup_store.DedupStore(db_path=':memory:', dedup_ttl_minutes=60, max_entries=10000, cleanup_interval_minutes=10, warmup_duration_minutes=5)

ベースクラス: object

SQLite-based deduplication store for intent idempotency.

Provides persistent storage for tracking processed intents with TTL-based cleanup and warmup guards for relaxed deduplication after restart.

Requirements addressed: - 3.3: Two-phase commit with idempotency checking - 10.1: Idempotent ingestion where duplicate req_id must not create duplicate effects - 10.2: TTL cleanup for expired entries

パラメータ:

• db_path (str | Path)

• dedup_ttl_minutes (int | float)

• max_entries (int)

• cleanup_interval_minutes (int | float)

• warmup_duration_minutes (int | float)

async initialize()

Initialize database connection and schema.

戻り値の型:

None

async close()

Close database connection and cleanup task.

戻り値の型:

None

async check_and_record(world_id, agent_id, req_id, global_seq)

Check if intent was already processed and record if not.

戻り値の型:

int | None

パラメータ:

• world_id (str)

• agent_id (str)

• req_id (str)

• global_seq (int)

Args:

world_id: World identifier agent_id: Agent identifier req_id: Request identifier global_seq: Global sequence number for this intent

Returns:

None if intent is new (and was recorded) Existing global_seq if intent was already processed

Raises:

RuntimeError: If database is not initialized ValueError: If any identifier is empty

async cleanup_expired()

Clean up expired deduplication entries.

戻り値の型:

int

Returns:

Number of entries cleaned up

async cleanup_excess_entries()

Clean up excess entries when max_entries is exceeded.

戻り値の型:

int

Returns:

Number of entries cleaned up

async get_stats()

Get deduplication store statistics.

戻り値の型:

dict[str, Any]

Returns:

Dictionary with store statistics

class gunn.storage.dedup_store.InMemoryDedupStore(dedup_ttl_minutes=60, max_entries=10000, warmup_duration_minutes=5)

ベースクラス: object

In-memory deduplication store for testing.

Provides the same interface as DedupStore but uses in-memory storage for faster testing without SQLite overhead.

パラメータ:

• dedup_ttl_minutes (int | float)

• max_entries (int)

• warmup_duration_minutes (int | float)

async initialize()

Initialize store (no-op for in-memory).

戻り値の型:

None

async close()

Close store (no-op for in-memory).

戻り値の型:

None

async check_and_record(world_id, agent_id, req_id, global_seq)

Check if intent was already processed and record if not.

戻り値の型:

int | None

パラメータ:

• world_id (str)

• agent_id (str)

• req_id (str)

• global_seq (int)

async cleanup_expired()

Clean up expired entries.

戻り値の型:

int

async cleanup_excess_entries()

Clean up excess entries when max_entries is exceeded.

戻り値の型:

int

async get_stats()

Get store statistics.

戻り値の型:

dict[str, Any]

Module contents

Persistent storage layer.

This package provides storage components for the multi-agent simulation, including deduplication stores and snapshot management.

class gunn.storage.DedupStore(db_path=':memory:', dedup_ttl_minutes=60, max_entries=10000, cleanup_interval_minutes=10, warmup_duration_minutes=5)

ベースクラス: object

SQLite-based deduplication store for intent idempotency.

Provides persistent storage for tracking processed intents with TTL-based cleanup and warmup guards for relaxed deduplication after restart.

Requirements addressed: - 3.3: Two-phase commit with idempotency checking - 10.1: Idempotent ingestion where duplicate req_id must not create duplicate effects - 10.2: TTL cleanup for expired entries

パラメータ:

• db_path (str | Path)

• dedup_ttl_minutes (int | float)

• max_entries (int)

• cleanup_interval_minutes (int | float)

• warmup_duration_minutes (int | float)

async check_and_record(world_id, agent_id, req_id, global_seq)

Check if intent was already processed and record if not.

戻り値の型:

int | None

パラメータ:

• world_id (str)

• agent_id (str)

• req_id (str)

• global_seq (int)

Args:

world_id: World identifier agent_id: Agent identifier req_id: Request identifier global_seq: Global sequence number for this intent

Returns:

None if intent is new (and was recorded) Existing global_seq if intent was already processed

Raises:

RuntimeError: If database is not initialized ValueError: If any identifier is empty

async cleanup_excess_entries()

Clean up excess entries when max_entries is exceeded.

戻り値の型:

int

Returns:

Number of entries cleaned up

async cleanup_expired()

Clean up expired deduplication entries.

戻り値の型:

int

Returns:

Number of entries cleaned up

async close()

Close database connection and cleanup task.

戻り値の型:

None

async get_stats()

Get deduplication store statistics.

戻り値の型:

dict[str, Any]

Returns:

Dictionary with store statistics

async initialize()

Initialize database connection and schema.

戻り値の型:

None

class gunn.storage.InMemoryDedupStore(dedup_ttl_minutes=60, max_entries=10000, warmup_duration_minutes=5)

ベースクラス: object

In-memory deduplication store for testing.

Provides the same interface as DedupStore but uses in-memory storage for faster testing without SQLite overhead.

パラメータ:

• dedup_ttl_minutes (int | float)

• max_entries (int)

• warmup_duration_minutes (int | float)

async check_and_record(world_id, agent_id, req_id, global_seq)

Check if intent was already processed and record if not.

戻り値の型:

int | None

パラメータ:

• world_id (str)

• agent_id (str)

• req_id (str)

• global_seq (int)

async cleanup_excess_entries()

Clean up excess entries when max_entries is exceeded.

戻り値の型:

int

async cleanup_expired()

Clean up expired entries.

戻り値の型:

int

async close()

Close store (no-op for in-memory).

戻り値の型:

None

async get_stats()

Get store statistics.

戻り値の型:

dict[str, Any]

async initialize()

Initialize store (no-op for in-memory).

戻り値の型:

None