Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/ismael-sarmiento/kimera_python/llms.txt

Use this file to discover all available pages before exploring further.

By the end of this guide you will have kimera-core installed, a working in-memory cache storing and retrieving a Python dictionary with TTL expiry, a KimeraSerializer round-tripping a complex object that contains a datetime and a tuple, and a deterministic MD5 hash key generated from a plain dict — all with real, runnable code drawn directly from the library’s source.
1

Install kimera-core

Install the package from PyPI using pip. No extra flags or indexes are required for the core feature set.
pip install kimera-core
After installation completes, you can verify it by opening a Python shell and importing one of the engines — see the Verify Installation section for a one-liner check.
2

Use the in-memory cache

InMemoryCacheEngine stores key-value pairs in a plain Python dict inside your process. Every entry carries a TTL (time-to-live) in seconds; once the TTL elapses, get and exists treat the entry as absent. The engine also enforces a maximum number of entries via size_regulator, evicting the oldest item when the limit is breached.
from components.storage.dynamic.cache.local.engines import InMemoryCacheEngine

cache = InMemoryCacheEngine()
cache.set('user:1', {'name': 'Alice'}, timeout=60)
print(cache.exists('user:1'))   # True
print(cache.get('user:1'))      # {'name': 'Alice'}
cache.delete('user:1')
print(cache.exists('user:1'))   # False
The timeout parameter is expressed in seconds and defaults to 300.0 when omitted. The size parameter defaults to 300 entries. Both defaults are defined as class-level constants on BaseCacheEngine.
3

Serialize a Python object

KimeraSerializer performs round-trip JSON serialization for Python types that the standard json module cannot handle natively, including datetime, date, tuple, and nested combinations. It selects the correct handler automatically by inspecting the object’s type.
from components.tools.serializers.custom import KimeraSerializer
from datetime import datetime

serializer = KimeraSerializer()
obj = {'timestamp': datetime.now(), 'values': [1, 2, (3, 4)]}
serialized = serializer.serialize(obj)
restored = serializer.deserialize(serialized)
assert restored == obj
The serialize method returns a JSON string. The deserialize method reconstructs the original Python object, including the correct types — the datetime comes back as a datetime instance, and the tuple comes back as a tuple.
4

Hash an object

build_hash creates a deterministic MD5 hex digest from any Python object by encoding both its string representation and its type. The same object always produces the same hash, making it safe to use as a cache key.
from components.tools.hash.md5 import build_hash

key = build_hash({'user_id': 42, 'role': 'admin'})
print(key)   # deterministic MD5 hex string
The hash is computed as hashlib.md5(str(obj).encode() + str(type(obj)).encode()).hexdigest(). Because the type is included in the digest, a string "1" and an integer 1 produce different hashes even though their string representations are identical.
The import paths above — such as components.storage.dynamic.cache.local.engines — assume you are running Python from within the kimera-core package directory (i.e., the directory that contains the components/ folder). If you have installed the package into a virtualenv via pip and the package registers its own top-level namespace, adjust the import path to match your environment.
The set method on InMemoryCacheEngine also accepts a size parameter that caps the total number of entries. When the cache exceeds this limit the oldest item is evicted automatically. See the Local Cache reference for a full breakdown of TTL behaviour, size regulation, and the ThreadCacheEngine alternative.

Build docs developers (and LLMs) love

Get started for freeTalk to us