Release v0.3.1

Author: squld

CHANGELOG.md

@@ -7,6 +7,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.1] - 2026-03-19
+
+### Changed
+- Internal ID generation now uses `ulid.generate_ulid()` (ULID,
+  26-character Crockford Base32, timestamp-sortable) in a dedicated
+  module, replacing the former `generate_id` embedded in
+  `runtime.scoping`.
+
 ## [0.3.0] - 2026-03-18
 
 ### Added
@@ -41,7 +49,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Step executor abstraction and provider integration foundation.
 - Core documentation and project scaffolding.
 
-[Unreleased]: https://github.com/kurusugawa-computer/nighthawk-python/compare/v0.3.0...HEAD
+[Unreleased]: https://github.com/kurusugawa-computer/nighthawk-python/compare/v0.3.1...HEAD
+[0.3.1]: https://github.com/kurusugawa-computer/nighthawk-python/compare/v0.3.0...v0.3.1
 [0.3.0]: https://github.com/kurusugawa-computer/nighthawk-python/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/kurusugawa-computer/nighthawk-python/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/kurusugawa-computer/nighthawk-python/tree/v0.1.0

CONTRIBUTING.md

@@ -148,7 +148,7 @@ def run(
 
     Args:
         step_executor: The step executor to use for Natural block execution.
-        run_id: Optional identifier for the run. If not provided, a UUID is
+        run_id: Optional identifier for the run. If not provided, a ULID is
             generated automatically.
 
     Yields:

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "nighthawk-python"
-version = "0.3.0"
+version = "0.3.1"
 description = "An experimental Python library that embeds Natural blocks inside Python functions and executes them using an LLM."
 readme = "README.md"
 requires-python = ">=3.13"
@@ -32,11 +32,12 @@ dependencies = [
 [project.urls]
 Repository = "https://github.com/kurusugawa-computer/nighthawk-python"
 Documentation = "https://kurusugawa-computer.github.io/nighthawk-python/"
+Changelog = "https://github.com/kurusugawa-computer/nighthawk-python/blob/main/CHANGELOG.md"
 "Bug Tracker" = "https://github.com/kurusugawa-computer/nighthawk-python/issues"
 
 [project.optional-dependencies]
 claude-code-sdk = [
-  "claude-agent-sdk>=0.1",
+  "claude-agent-sdk==0.1.48",
 ]
 claude-code-cli = [
   "mcp>=1.26",

src/nighthawk/runtime/scoping.py

@@ -1,7 +1,6 @@
 from __future__ import annotations
 
 import importlib.metadata
-import uuid
 from collections.abc import Iterator
 from contextlib import contextmanager
 from contextvars import ContextVar
@@ -13,6 +12,7 @@
 from ..configuration import StepExecutorConfiguration, StepExecutorConfigurationPatch
 from ..errors import NighthawkError
 from ..tools.registry import tool_scope
+from ..ulid import generate_ulid
 
 if TYPE_CHECKING:
     from .step_executor import AgentStepExecutor, StepExecutor
@@ -53,9 +53,6 @@ def span(span_name: str, /, **attributes: Any) -> Iterator[Span]:
         yield current_span
 
 
-def _generate_id() -> str:
-    return uuid.uuid4().hex
-
 
 _step_executor_var: ContextVar[StepExecutor | None] = ContextVar(
     "nighthawk_step_executor",
@@ -172,7 +169,7 @@ def run(
 
     Args:
         step_executor: The step executor to use for Natural block execution.
-        run_id: Optional identifier for the run. If not provided, a UUID is
+        run_id: Optional identifier for the run. If not provided, a ULID is
             generated automatically.
 
     Yields:
@@ -188,8 +185,8 @@ def run(
         ```
     """
     execution_context = ExecutionContext(
-        run_id=run_id or _generate_id(),
-        scope_id=_generate_id(),
+        run_id=run_id or generate_ulid(),
+        scope_id=generate_ulid(),
     )
 
     with tool_scope():
@@ -282,7 +279,7 @@ def scope(
 
     next_execution_context = replace(
         current_execution_context,
-        scope_id=_generate_id(),
+        scope_id=generate_ulid(),
     )
 
     next_system_fragments = _system_prompt_suffix_fragments_var.get()

src/nighthawk/runtime/tool_calls.py

@@ -1,17 +1,18 @@
 from __future__ import annotations
 
 import json
-import uuid
 from collections.abc import Awaitable, Callable, Iterator
 from contextlib import contextmanager
 from typing import Any
 
 from pydantic_ai import RunContext
 from pydantic_ai._instrumentation import InstrumentationNames
 
+from ..ulid import generate_ulid
+
 
 def generate_tool_call_id() -> str:
-    return str(uuid.uuid4())
+    return generate_ulid()
 
 
 def _resolve_instrumentation_names(*, run_context: RunContext[Any]) -> InstrumentationNames:

src/nighthawk/ulid.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+import os
+import time
+
+_CROCKFORD = "0123456789ABCDEFGHJKMNPQRSTVWXYZ"
+
+
+def generate_ulid() -> str:
+    """Generate a ULID string (timestamp-based, sortable, 26 chars, Crockford Base32)."""
+    timestamp_ms = int(time.time() * 1000)
+    random_int = int.from_bytes(os.urandom(10))
+    chars: list[str] = []
+    for shift in (45, 40, 35, 30, 25, 20, 15, 10, 5, 0):
+        chars.append(_CROCKFORD[(timestamp_ms >> shift) & 0x1F])
+    for shift in (75, 70, 65, 60, 55, 50, 45, 40, 35, 30, 25, 20, 15, 10, 5, 0):
+        chars.append(_CROCKFORD[(random_int >> shift) & 0x1F])
+    return "".join(chars)