ID Generator

10xGraph uses ID generators to create unique identifiers for threads, messages, and other persisted records. The generator determines both the ID format and the ID type used in the system.

Base ID generator interface

The core interface is BaseIDGenerator in tenxgraph/utils/id_generator.py. It defines:

• id_type — the ID type returned by the generator (STRING, INTEGER, or BIGINT).
• generate() — method that returns a new unique ID.

This interface lets 10xGraph support standard UUIDs, timestamp-based integers, and Snowflake-style distributed IDs.

Built-in generators

10xGraph includes several built-in ID generators:

• DefaultIDGenerator

  • Returns an empty string.
  • This signals the framework to use a default UUID-based generator elsewhere in the stack.
  • Use this when you want a normal UUID fallback.

• UUIDGenerator

  • Produces UUID version 4 strings.
  • ID type: STRING.
  • Good for global uniqueness without coordination.

• BigIntIDGenerator

  • Produces a large integer based on current Unix time in nanoseconds.
  • ID type: BIGINT.
  • Sortable by creation time, but not ideal for extremely high-concurrency distributed systems.

Snowflake ID generator

The API package includes SnowFlakeIdGenerator in agentflow-api/agentflow_cli/src/app/utils/snowflake_id_generator.py.

This generator uses the optional snowflakekit dependency and returns a 64-bit integer suitable for distributed systems.

Configuration options

If you do not pass explicit constructor values, SnowFlakeIdGenerator reads these environment variables:

• SNOWFLAKE_EPOCH — default 1723323246031
• SNOWFLAKE_TOTAL_BITS — default 64
• SNOWFLAKE_TIME_BITS — default 39
• SNOWFLAKE_NODE_BITS — default 7
• SNOWFLAKE_NODE_ID — default 0
• SNOWFLAKE_WORKER_ID — default 0
• SNOWFLAKE_WORKER_BITS — default 5

It reads os.environ directly, so these are process environment variables. A .env file loaded through 10xgraph.json is loaded before the graph module is imported, which covers the normal case where the generator is constructed inside your graph module.

The constructor is all-or-nothing

There are exactly two supported ways to construct it:

1. Pass nothing. All seven parameters are None, so the generator builds its config from the environment variables above.
2. Pass all seven. snowflake_epoch, total_bits, snowflake_time_bits, snowflake_node_bits, snowflake_node_id, snowflake_worker_id, and snowflake_worker_bits must all be supplied.

Example usage

from agentflow_cli import SnowFlakeIdGenerator

id_generator = SnowFlakeIdGenerator()

Or configure explicitly:

id_generator = SnowFlakeIdGenerator(
    snowflake_epoch=1723323246031,
    total_bits=64,
    snowflake_time_bits=39,
    snowflake_node_bits=7,
    snowflake_node_id=1,
    snowflake_worker_id=2,
    snowflake_worker_bits=5,
)

Deployment notes

• Assign a unique SNOWFLAKE_NODE_ID per host or cluster node.
• Assign a unique SNOWFLAKE_WORKER_ID per worker process on the same host.
• Do not reuse node or worker IDs while old IDs are still valid in storage.
• Install the optional dependency with pip install snowflakekit.

When to use Snowflake IDs

Choose SnowFlakeIdGenerator when you need:

• globally unique IDs across multiple servers,
• time-sortable identifiers,
• IDs without a central coordination service.

For local development, UUIDGenerator is usually sufficient.