Skills

A skill is a package of structured files that teaches an AI coding agent how to work with a specific tool or framework. The skill below was generated by Great Docs from this project’s documentation. Install it in your agent and it will be able to run commands, edit configuration, write content, and troubleshoot problems without step-by-step guidance from you.

Any agent — install with npx:

npx skills add https://ghga-de.github.io/hexkit/

Codex / OpenCode

Tell the agent:
Fetch the skill file at https://ghga-de.github.io/hexkit/skill.md and follow the instructions.

Manual — download the skill file:

curl -O https://ghga-de.github.io/hexkit/skill.md

Or browse the SKILL.md file.

SKILL.md

---
name: hexkit
description: >
  A Toolkit for Building Microservices using the Hexagonal Architecture. Use when writing Python code that uses the hexkit package.
license: Apache-2.0
compatibility: Requires Python >=3.10.
---

# hexkit

A Toolkit for Building Microservices using the Hexagonal Architecture

## Installation

```bash
pip install hexkit
```

## API overview

### Core Types & Base Classes

Shared type aliases and provider base classes

- `custom_types.ID`
- `custom_types.JsonObject`
- `custom_types.Ascii`
- `custom_types.AsyncConstructable`
- `custom_types.AsyncContextConstructable`
- `custom_types.KafkaCompressionType`
- `custom_types.PytestScope`
- `base.InboundProviderBase`

### General Utilities

Dependency-light helper functions and related errors

- `utils.calc_part_size`
- `utils.check_ascii`
- `utils.validate_fields_in_model`
- `utils.round_datetime_to_ms`
- `utils.now_utc_ms_prec`
- `utils.FieldNotInModelError`
- `utils.NonAsciiStrError`

### Correlation IDs

Correlation-ID context management and helpers

- `correlation.get_correlation_id`
- `correlation.new_correlation_id`
- `correlation.validate_correlation_id`
- `correlation.correlation_id_from_str`
- `correlation.set_context_var`
- `correlation.set_correlation_id`
- `correlation.set_new_correlation_id`
- `correlation.CorrelationIdContextError`
- `correlation.InvalidCorrelationIdError`

### OpenTelemetry

Observability / tracing configuration

- `opentelemetry.OpenTelemetryConfig`
- `opentelemetry.configure_opentelemetry`

### Logging

Structured logging configuration and formatters

- `log.LoggingConfig`
- `log.configure_logging`
- `log.JsonFormatter`
- `log.RecordCompiler`

### Protocols — Events

Ports for event publishing and subscription

- `protocols.eventpub.EventPublisherProtocol`
- `protocols.eventsub.EventSubscriberProtocol`
- `protocols.eventsub.DLQSubscriberProtocol`

### Protocols — Data Access Objects

Ports for DAOs and outbox publishing/subscription

- `protocols.dao.Dao`
- `protocols.dao.DaoFactoryProtocol`
- `protocols.dao.DaoFactoryBase`
- `protocols.dao.FindResult`
- `protocols.daopub.DaoPublisher`
- `protocols.daopub.DaoPublisherFactoryProtocol`
- `protocols.daosub.DaoSubscriberProtocol`
- `protocols.daosub.DtoValidationError`
- `protocols.dao.DaoError`
- `protocols.dao.ResourceNotFoundError`
- `protocols.dao.ResourceAlreadyExistsError`
- `protocols.dao.UniqueConstraintViolationError`
- `protocols.dao.FindError`
- `protocols.dao.InvalidFindMappingError`
- `protocols.dao.MultipleHitsFoundError`
- `protocols.dao.NoHitsFoundError`
- `protocols.dao.DbTimeoutError`

### Protocols — Storage

Ports for key-value and object storage

- `protocols.kvstore.KeyValueStoreProtocol`
- `protocols.objstorage.ObjectStorageProtocol`
- `protocols.objstorage.PresignedPostURL`

### Provider — Apache Kafka

Event pub/sub backed by Apache Kafka

- `providers.akafka.KafkaConfig`
- `providers.akafka.KafkaEventPublisher`
- `providers.akafka.KafkaEventSubscriber`
- `providers.akafka.KafkaOutboxSubscriber`
- `providers.akafka.ComboTranslator`

### Provider — MongoDB

DAO and key-value stores backed by MongoDB

- `providers.mongodb.MongoDbConfig`
- `providers.mongodb.MongoDbDaoFactory`
- `providers.mongodb.MongoDbDao`
- `providers.mongodb.MongoDbBytesKeyValueStore`
- `providers.mongodb.MongoDbStrKeyValueStore`
- `providers.mongodb.MongoDbJsonKeyValueStore`
- `providers.mongodb.MongoDbDtoKeyValueStore`

### MongoDB Migration Tooling

Versioned database migration framework for MongoDB

- `providers.mongodb.migrations.MigrationConfig`
- `providers.mongodb.migrations.MigrationManager`
- `providers.mongodb.migrations.MigrationDefinition`
- `providers.mongodb.migrations.Reversible`
- `providers.mongodb.migrations.check_db_version`
- `providers.mongodb.migrations.validate_doc`
- `providers.mongodb.migrations.MigrationStepError`
- `providers.mongodb.migrations.DbVersionMismatchError`
- `providers.mongodb.migrations.helpers.convert_uuids_and_datetimes_v6`
- `providers.mongodb.migrations.helpers.convert_outbox_correlation_id_v6`
- `providers.mongodb.migrations.helpers.convert_persistent_event_v6`

### Provider — MongoDB + Kafka

Persistent / outbox event publishing

- `providers.mongokafka.MongoKafkaConfig`
- `providers.mongokafka.MongoKafkaDaoPublisherFactory`
- `providers.mongokafka.PersistentKafkaPublisher`
- `providers.mongokafka.PersistentKafkaEvent`

### Provider — S3

Object storage and key-value stores backed by S3

- `providers.s3.S3Config`
- `providers.s3.S3ObjectStorage`
- `providers.s3.S3BytesKeyValueStore`
- `providers.s3.S3StrKeyValueStore`
- `providers.s3.S3JsonKeyValueStore`
- `providers.s3.S3DtoKeyValueStore`

### Provider — Redis

Key-value stores backed by Redis

- `providers.redis.RedisConfig`
- `providers.redis.RedisBytesKeyValueStore`
- `providers.redis.RedisStrKeyValueStore`
- `providers.redis.RedisJsonKeyValueStore`
- `providers.redis.RedisDtoKeyValueStore`

### Provider — HashiCorp Vault

Key-value stores backed by Vault

- `providers.vault.VaultConfig`
- `providers.vault.VaultBytesKeyValueStore`
- `providers.vault.VaultStrKeyValueStore`
- `providers.vault.VaultJsonKeyValueStore`
- `providers.vault.VaultDtoKeyValueStore`

### Provider — In-Memory (Testing)

In-memory providers and mocks for tests

- `providers.testing.InMemEventPublisher`
- `providers.testing.InMemEventStore`
- `providers.testing.InMemBytesKeyValueStore`
- `providers.testing.InMemStrKeyValueStore`
- `providers.testing.InMemJsonKeyValueStore`
- `providers.testing.InMemDtoKeyValueStore`
- `providers.testing.new_mock_dao_class`
- `providers.testing.MockDAOEmptyError`
- `providers.testing.TopicExhaustedError`

## Resources

- [Full documentation](https://ghga-de.github.io/hexkit/)
- [llms.txt](llms.txt) — Indexed API reference for LLMs
- [llms-full.txt](llms-full.txt) — Comprehensive documentation for LLMs
- [Source code](https://github.com/ghga-de/hexkit)