dossier 1.1.3__tar.gz

dossier-1.1.3/PKG-INFO

@@ -0,0 +1,302 @@
+Metadata-Version: 2.4
+Name: dossier
+Version: 1.1.3
+Summary: A structured logging library for AI agents with session management and object unpacking
+Keywords: logging,structlog,ai,agents,session-management
+Author: Ricardo Decal
+Author-email: Ricardo Decal <dossier-project@ricardodecal.com>
+License-Expression: Apache-2.0
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Logging
+Requires-Dist: beartype>=0.22.5
+Requires-Dist: better-exceptions>=0.3.3
+Requires-Dist: rich>=14.2.0
+Requires-Dist: structlog>=25.5.0
+Requires-Python: >=3.13
+Project-URL: Documentation, https://dossier.ricardodecal.com/
+Project-URL: Homepage, https://dossier.ricardodecal.com/
+Project-URL: Issues, https://github.com/crypdick/dossier/issues
+Project-URL: Repository, https://github.com/crypdick/dossier
+Description-Content-Type: text/markdown
+
+# dossier
+
+A structured logging library with session management and object unpacking, built on [structlog](https://www.structlog.org/).
+
+## Why `dossier`?
+
+`structlog` is great, but while I was using it for AI agents, I found myself writing a lot of boilerplate code to handle session management and object unpacking:
+
+- I want to organize my logs by agent session, so I can easily find logs for a specific session.
+- I want to throw objects like dataclasses, Pydantic models, or any other object at the logger and let it handle unpacking them for structured logging.
+
+With `dossier`, each session is automatically organized:
+
+```
+logs/
+└── session_20251118_120000/
+    └── events.jsonl      # Structured JSONL logs
+```
+
+And you can throw objects like dataclasses, Pydantic models, regular dicts, and `dossier` will handle the unpacking.
+
+## Installation
+
+```bash
+pip install dossier
+# or
+uv add dossier
+```
+
+## Quick Start
+
+```python
+from dataclasses import dataclass
+import dossier
+
+log = dossier.get_session()
+
+# Bind info to the logger for the entire session
+log.bind(model="gpt-4", mode="agent", user_id="user_123", experiment="feature_test")
+
+log.info("session_start")
+# logs: {"event": "session_start", "timestamp": "2025-11-18T12:00:00.000Z", "level": "info",
+#        "model": "gpt-4", "mode": "agent", "user_id": "user_123", "experiment": "feature_test"}
+
+
+# Unbind keys
+log.unbind("mode", "user_id")
+
+# Log similarly to structlog
+log.info("user_message", content="What's the weather?", role="user")
+
+# Or use dataclasses - event type auto-detected!
+@dataclass
+class ToolCall:
+    tool_name: str
+    arguments: dict
+
+tool_call = ToolCall(tool_name="web_search", arguments={"q": "weather"})
+log.info(tool_call)  # Same as log.info("tool_call", tool_name=tool_call.tool_name, arguments=tool_call.arguments)
+```
+Get current session information:
+
+```python
+session_id = logger.get_session_id()
+session_dir = logger.get_session_path()
+```
+
+## Reusing a session
+
+`dossier` implements a session registry similar to Python's standard `logging.getLogger(name)`. This means you can retrieve the same session instance from anywhere in your application using its `session_id` without needing to pass it around or set global variables.
+
+**How it works:** Session IDs are simple identifiers (like `"main"`), while log directories are automatically timestamped (like `main_20251118_120000/`). This gives you easy session retrieval while maintaining chronological log organization.
+
+```python
+from dossier import get_session
+
+# First call creates the session (creates logs/main_TIMESTAMP/)
+logger = get_session(session_id="main")
+logger.bind(app_version="1.0.0", user_id="user_123")
+
+# Later, anywhere else in your app: this returns the same instance
+logger2 = get_session(session_id="main")
+assert logger is logger2  # True!
+
+# Log to logs/main_NEW_TIMESTAMP/
+logger3 = get_session(session_id="main", force_new=True)
+```
+
+Sessions are isolated from each other by using different session_ids.
+
+## Namespaced logging
+
+Route logs to different files within the same session using the `namespace` parameter. This is useful for organizing logs by component, worker, or module:
+
+```python
+from dossier import get_session
+
+logger = get_session()  # logs to logs/session_TIMESTAMP/events.jsonl
+
+logger.info("task_started", namespace="worker")  # logs to logs/session_TIMESTAMP/worker.jsonl
+```
+
+## Custom processors
+
+Dossier allows you to register custom structlog processors for advanced use cases like cost tracking, metrics collection, or adding custom fields.
+
+#### Function processors
+
+Simple stateless processors that add fields or transform data:
+
+```python
+from dossier import get_session
+
+# Add a custom field to every log
+def add_hostname(logger, method_name, event_dict):
+    import socket
+    event_dict["hostname"] = socket.gethostname()
+    return event_dict
+
+# Add environment info
+def add_environment(logger, method_name, event_dict):
+    import os
+    event_dict["environment"] = os.environ.get("ENV", "development")
+    return event_dict
+
+logger = get_session(
+    log_dir="logs",
+    processors=[add_hostname, add_environment],
+)
+logger.bind(model="gpt-4")
+logger.info("test_event")
+# Output includes: hostname, environment, model
+```
+
+### Stateful processors
+
+For tracking state across log calls (like token counting, cost tracking, etc.):
+
+```python
+from dossier import get_session
+
+class TokenCounter:
+    """Track cumulative token usage across the session"""
+
+    def __init__(self):
+        self.total_tokens = 0
+        self.call_count = 0
+
+    def __call__(self, logger, method_name, event_dict):
+        # Only process token_usage events
+        if "input_tokens" in event_dict and "output_tokens" in event_dict:
+            total = event_dict["input_tokens"] + event_dict["output_tokens"]
+            self.total_tokens += total
+            self.call_count += 1
+
+            # Add cumulative info to the log
+            event_dict["cumulative_tokens"] = self.total_tokens
+            event_dict["token_call_count"] = self.call_count
+
+        return event_dict
+
+# Create the counter instance
+counter = TokenCounter()
+
+logger = get_session(log_dir="logs", processors=[counter])
+logger.bind(model="gpt-4")
+
+# Log token usage
+logger.info("token_usage", input_tokens=100, output_tokens=50)
+logger.info("token_usage", input_tokens=200, output_tokens=100)
+
+# Access the counter's state
+print(f"Total tokens used: {counter.total_tokens}")  # 450
+```
+
+#### Real-World Example: Cost Tracker
+
+Here's a complete cost tracking processor similar to OpenAI's pricing:
+
+```python
+from dossier import get_session
+
+# Pricing per million tokens (USD)
+PRICING = {
+    "gpt-4": {"input": 30.00, "output": 60.00},
+    "gpt-4-turbo": {"input": 10.00, "output": 30.00},
+    "gpt-3.5-turbo": {"input": 0.50, "output": 1.50},
+}
+
+class CostTracker:
+    """Track API costs across the session"""
+
+    def __init__(self):
+        self.total_cost = 0.0
+        self.total_calls = 0
+
+    def __call__(self, logger, method_name, event_dict):
+        # Process token_usage events
+        if event_dict.get("event") == "token_usage":
+            model = event_dict.get("model", "gpt-4")
+            input_tokens = event_dict.get("input_tokens", 0)
+            output_tokens = event_dict.get("output_tokens", 0)
+
+            if model in PRICING:
+                pricing = PRICING[model]
+                cost = (
+                    (input_tokens / 1_000_000) * pricing["input"] +
+                    (output_tokens / 1_000_000) * pricing["output"]
+                )
+                self.total_cost += cost
+                self.total_calls += 1
+
+                # Add cost info to log
+                event_dict["call_cost_usd"] = round(cost, 6)
+                event_dict["cumulative_cost_usd"] = round(self.total_cost, 6)
+
+        return event_dict
+
+    def get_summary(self):
+        """Get formatted summary"""
+        return f"Total cost: ${self.total_cost:.4f} across {self.total_calls} calls"
+
+# Use the cost tracker
+cost_tracker = CostTracker()
+logger = get_session(
+    log_dir="logs",
+    processors=[cost_tracker],
+)
+logger.bind(model="gpt-4-turbo")
+
+# Log some API usage
+logger.info("token_usage", model="gpt-4-turbo", input_tokens=1000, output_tokens=500)
+logger.info("token_usage", model="gpt-4-turbo", input_tokens=2000, output_tokens=1000)
+
+# Get cost summary
+print(cost_tracker.get_summary())
+# Output: Total cost: $0.0500 across 2 calls
+```
+
+## Integrations
+
+Dossier automatically unpacks objects from popular libraries.
+
+### LangChain
+
+Works seamlessly with LangChain objects:
+
+```python
+from langchain_core.messages import HumanMessage, AIMessage
+
+user_msg = HumanMessage(content="What's 2+2?")
+logger.info(user_msg)  # Event type: "human_message"
+
+ai_msg = AIMessage(content="4")
+logger.info(ai_msg)  # Event type: "ai_message"
+```
+
+### Pydantic
+
+```python
+from pydantic import BaseModel
+
+class RequestModel(BaseModel):
+    method: str
+    path: str
+    body: dict
+
+request = RequestModel(method="POST", path="/api/chat", body={"msg": "hi"})
+logger.info(request)  # Auto-unpacks to flat dict
+```
+
+
+
+## License
+
+Apache 2.0

dossier-1.1.3/README.md

@@ -0,0 +1,276 @@
+# dossier
+
+A structured logging library with session management and object unpacking, built on [structlog](https://www.structlog.org/).
+
+## Why `dossier`?
+
+`structlog` is great, but while I was using it for AI agents, I found myself writing a lot of boilerplate code to handle session management and object unpacking:
+
+- I want to organize my logs by agent session, so I can easily find logs for a specific session.
+- I want to throw objects like dataclasses, Pydantic models, or any other object at the logger and let it handle unpacking them for structured logging.
+
+With `dossier`, each session is automatically organized:
+
+```
+logs/
+└── session_20251118_120000/
+    └── events.jsonl      # Structured JSONL logs
+```
+
+And you can throw objects like dataclasses, Pydantic models, regular dicts, and `dossier` will handle the unpacking.
+
+## Installation
+
+```bash
+pip install dossier
+# or
+uv add dossier
+```
+
+## Quick Start
+
+```python
+from dataclasses import dataclass
+import dossier
+
+log = dossier.get_session()
+
+# Bind info to the logger for the entire session
+log.bind(model="gpt-4", mode="agent", user_id="user_123", experiment="feature_test")
+
+log.info("session_start")
+# logs: {"event": "session_start", "timestamp": "2025-11-18T12:00:00.000Z", "level": "info",
+#        "model": "gpt-4", "mode": "agent", "user_id": "user_123", "experiment": "feature_test"}
+
+
+# Unbind keys
+log.unbind("mode", "user_id")
+
+# Log similarly to structlog
+log.info("user_message", content="What's the weather?", role="user")
+
+# Or use dataclasses - event type auto-detected!
+@dataclass
+class ToolCall:
+    tool_name: str
+    arguments: dict
+
+tool_call = ToolCall(tool_name="web_search", arguments={"q": "weather"})
+log.info(tool_call)  # Same as log.info("tool_call", tool_name=tool_call.tool_name, arguments=tool_call.arguments)
+```
+Get current session information:
+
+```python
+session_id = logger.get_session_id()
+session_dir = logger.get_session_path()
+```
+
+## Reusing a session
+
+`dossier` implements a session registry similar to Python's standard `logging.getLogger(name)`. This means you can retrieve the same session instance from anywhere in your application using its `session_id` without needing to pass it around or set global variables.
+
+**How it works:** Session IDs are simple identifiers (like `"main"`), while log directories are automatically timestamped (like `main_20251118_120000/`). This gives you easy session retrieval while maintaining chronological log organization.
+
+```python
+from dossier import get_session
+
+# First call creates the session (creates logs/main_TIMESTAMP/)
+logger = get_session(session_id="main")
+logger.bind(app_version="1.0.0", user_id="user_123")
+
+# Later, anywhere else in your app: this returns the same instance
+logger2 = get_session(session_id="main")
+assert logger is logger2  # True!
+
+# Log to logs/main_NEW_TIMESTAMP/
+logger3 = get_session(session_id="main", force_new=True)
+```
+
+Sessions are isolated from each other by using different session_ids.
+
+## Namespaced logging
+
+Route logs to different files within the same session using the `namespace` parameter. This is useful for organizing logs by component, worker, or module:
+
+```python
+from dossier import get_session
+
+logger = get_session()  # logs to logs/session_TIMESTAMP/events.jsonl
+
+logger.info("task_started", namespace="worker")  # logs to logs/session_TIMESTAMP/worker.jsonl
+```
+
+## Custom processors
+
+Dossier allows you to register custom structlog processors for advanced use cases like cost tracking, metrics collection, or adding custom fields.
+
+#### Function processors
+
+Simple stateless processors that add fields or transform data:
+
+```python
+from dossier import get_session
+
+# Add a custom field to every log
+def add_hostname(logger, method_name, event_dict):
+    import socket
+    event_dict["hostname"] = socket.gethostname()
+    return event_dict
+
+# Add environment info
+def add_environment(logger, method_name, event_dict):
+    import os
+    event_dict["environment"] = os.environ.get("ENV", "development")
+    return event_dict
+
+logger = get_session(
+    log_dir="logs",
+    processors=[add_hostname, add_environment],
+)
+logger.bind(model="gpt-4")
+logger.info("test_event")
+# Output includes: hostname, environment, model
+```
+
+### Stateful processors
+
+For tracking state across log calls (like token counting, cost tracking, etc.):
+
+```python
+from dossier import get_session
+
+class TokenCounter:
+    """Track cumulative token usage across the session"""
+
+    def __init__(self):
+        self.total_tokens = 0
+        self.call_count = 0
+
+    def __call__(self, logger, method_name, event_dict):
+        # Only process token_usage events
+        if "input_tokens" in event_dict and "output_tokens" in event_dict:
+            total = event_dict["input_tokens"] + event_dict["output_tokens"]
+            self.total_tokens += total
+            self.call_count += 1
+
+            # Add cumulative info to the log
+            event_dict["cumulative_tokens"] = self.total_tokens
+            event_dict["token_call_count"] = self.call_count
+
+        return event_dict
+
+# Create the counter instance
+counter = TokenCounter()
+
+logger = get_session(log_dir="logs", processors=[counter])
+logger.bind(model="gpt-4")
+
+# Log token usage
+logger.info("token_usage", input_tokens=100, output_tokens=50)
+logger.info("token_usage", input_tokens=200, output_tokens=100)
+
+# Access the counter's state
+print(f"Total tokens used: {counter.total_tokens}")  # 450
+```
+
+#### Real-World Example: Cost Tracker
+
+Here's a complete cost tracking processor similar to OpenAI's pricing:
+
+```python
+from dossier import get_session
+
+# Pricing per million tokens (USD)
+PRICING = {
+    "gpt-4": {"input": 30.00, "output": 60.00},
+    "gpt-4-turbo": {"input": 10.00, "output": 30.00},
+    "gpt-3.5-turbo": {"input": 0.50, "output": 1.50},
+}
+
+class CostTracker:
+    """Track API costs across the session"""
+
+    def __init__(self):
+        self.total_cost = 0.0
+        self.total_calls = 0
+
+    def __call__(self, logger, method_name, event_dict):
+        # Process token_usage events
+        if event_dict.get("event") == "token_usage":
+            model = event_dict.get("model", "gpt-4")
+            input_tokens = event_dict.get("input_tokens", 0)
+            output_tokens = event_dict.get("output_tokens", 0)
+
+            if model in PRICING:
+                pricing = PRICING[model]
+                cost = (
+                    (input_tokens / 1_000_000) * pricing["input"] +
+                    (output_tokens / 1_000_000) * pricing["output"]
+                )
+                self.total_cost += cost
+                self.total_calls += 1
+
+                # Add cost info to log
+                event_dict["call_cost_usd"] = round(cost, 6)
+                event_dict["cumulative_cost_usd"] = round(self.total_cost, 6)
+
+        return event_dict
+
+    def get_summary(self):
+        """Get formatted summary"""
+        return f"Total cost: ${self.total_cost:.4f} across {self.total_calls} calls"
+
+# Use the cost tracker
+cost_tracker = CostTracker()
+logger = get_session(
+    log_dir="logs",
+    processors=[cost_tracker],
+)
+logger.bind(model="gpt-4-turbo")
+
+# Log some API usage
+logger.info("token_usage", model="gpt-4-turbo", input_tokens=1000, output_tokens=500)
+logger.info("token_usage", model="gpt-4-turbo", input_tokens=2000, output_tokens=1000)
+
+# Get cost summary
+print(cost_tracker.get_summary())
+# Output: Total cost: $0.0500 across 2 calls
+```
+
+## Integrations
+
+Dossier automatically unpacks objects from popular libraries.
+
+### LangChain
+
+Works seamlessly with LangChain objects:
+
+```python
+from langchain_core.messages import HumanMessage, AIMessage
+
+user_msg = HumanMessage(content="What's 2+2?")
+logger.info(user_msg)  # Event type: "human_message"
+
+ai_msg = AIMessage(content="4")
+logger.info(ai_msg)  # Event type: "ai_message"
+```
+
+### Pydantic
+
+```python
+from pydantic import BaseModel
+
+class RequestModel(BaseModel):
+    method: str
+    path: str
+    body: dict
+
+request = RequestModel(method="POST", path="/api/chat", body={"msg": "hi"})
+logger.info(request)  # Auto-unpacks to flat dict
+```
+
+
+
+## License
+
+Apache 2.0

dossier-1.1.3/dossier/__init__.py

@@ -0,0 +1,21 @@
+from beartype.claw import beartype_this_package
+
+# Enable beartype runtime type-checking for all modules in this package
+beartype_this_package()
+
+from dossier.dossier import (  # noqa: E402
+    close_logger,  # deprecated alias
+    close_session,
+    get_logger,  # deprecated alias
+    get_session,
+)
+
+# Note: Dossier class is internal - use get_session() instead
+
+__all__ = [
+    "get_session",
+    "close_session",
+    # Backward compatibility
+    "get_logger",
+    "close_logger",
+]

dossier-1.1.3/dossier/dossier.py

@@ -0,0 +1,379 @@
+import functools
+import logging
+from collections.abc import Callable
+from datetime import datetime
+from pathlib import Path
+from typing import Any, cast
+
+import structlog
+
+from dossier.processors import (
+    make_json_safe,
+    unpack_dataclasses,
+    unpack_generic_objects,
+    unpack_pydantic_models,
+)
+
+# Module-level cache for logger instances (similar to logging.getLogger)
+_logger_cache: dict[str, Any] = {}
+
+# Track if structlog has been configured globally
+_structlog_configured = False
+
+
+def _infer_event_type_from_object(obj: Any) -> str | None:
+    """Infer event type from object class name."""
+    if isinstance(obj, (str, int, float, bool, type(None), list, tuple, dict)):
+        return None
+    return type(obj).__name__
+
+
+def infer_event(func: Callable[..., Any]) -> Callable[..., Any]:
+    """
+    Decorator that handles event type inference from objects.
+
+    If the first arg (event) is an object (not a string):
+    - Infers event type from class name
+    - Adds object to kwargs as "_obj" for unpacking processor
+    - Calls the underlying method with inferred event type
+    """
+
+    @functools.wraps(func)
+    def wrapper(self: "Dossier", event: str | Any | None = None, **kwargs: Any) -> Any:
+        # Handle event type inference
+        if event is not None and not isinstance(event, str):
+            # Event is an object - infer type
+            inferred = _infer_event_type_from_object(event)
+            if inferred is None:
+                raise ValueError(
+                    "Must provide event type string or object with inferrable type"
+                )
+            kwargs["_obj"] = event
+            event = inferred
+        elif event is None:
+            raise ValueError("Must provide event string or object")
+
+        # Call the original method
+        return func(self, event, **kwargs)
+
+    return wrapper
+
+
+class Dossier:
+    """
+    Session-based structured logger with smart object unpacking and flexible metadata.
+
+    Wraps structlog for session management and automatic object unpacking.
+    """
+
+    def __init__(
+        self,
+        session_id: str,
+        session_dir: Path,
+        stdlib_logger_base_name: str,
+        processors: list[Any] | None = None,
+    ) -> None:
+        """Internal initialization - use get_session() instead."""
+        self.session_id = session_id
+        self.session_dir = session_dir
+        self._stdlib_logger_base_name = stdlib_logger_base_name
+        self._processors = processors or []
+        self._namespaced_loggers: dict[str, Any] = {}
+
+    def _resolve_namespace(self, namespace: str | None) -> str:
+        """Resolve namespace to a canonical string, defaulting to 'events'."""
+        return "events" if not namespace else namespace
+
+    def _get_namespaced_logger(self, namespace: str | None) -> Any | None:
+        """Get a namespaced logger if it exists, return None otherwise."""
+        resolved = self._resolve_namespace(namespace)
+        return self._namespaced_loggers.get(resolved)
+
+    def _set_namespaced_logger(self, namespace: str | None, logger: Any) -> None:
+        """Set/update a namespaced logger in the cache."""
+        resolved = self._resolve_namespace(namespace)
+        self._namespaced_loggers[resolved] = logger
+
+    def _get_or_create_namespaced_logger(self, namespace: str | None) -> Any:
+        """Get or create a namespaced logger for routing logs to a separate file."""
+        # Return cached logger if it exists
+        cached = self._get_namespaced_logger(namespace)
+        if cached is not None:
+            return cached
+
+        # Create new namespaced logger
+        resolved = self._resolve_namespace(namespace)
+        log_file = self.session_dir / f"{resolved}.jsonl"
+        stdlib_logger_name = f"{self._stdlib_logger_base_name}.{resolved}"
+
+        structlog_logger = _create_logger_infrastructure(
+            log_file=log_file,
+            stdlib_logger_name=stdlib_logger_name,
+            processors=self._processors,
+        )
+
+        # Cache the logger using the setter
+        self._set_namespaced_logger(namespace, structlog_logger)
+        return structlog_logger
+
+    def _route_log(
+        self, method_name: str, event: str | Any | None, **kwargs: Any
+    ) -> Any:
+        """Route log to appropriate logger based on namespace kwarg."""
+        namespace = kwargs.pop("namespace", None)
+        logger = self._get_or_create_namespaced_logger(namespace)
+
+        # Call the appropriate log method
+        log_method = getattr(logger, method_name)
+        return log_method(event, **kwargs)
+
+    @infer_event
+    def info(self, event: str | Any | None = None, **kwargs: Any) -> Any:
+        """Log info-level event."""
+        return self._route_log("info", event, **kwargs)
+
+    @infer_event
+    def error(self, event: str | Any | None = None, **kwargs: Any) -> Any:
+        """Log error-level event."""
+        return self._route_log("error", event, **kwargs)
+
+    @infer_event
+    def debug(self, event: str | Any | None = None, **kwargs: Any) -> Any:
+        """Log debug-level event."""
+        return self._route_log("debug", event, **kwargs)
+
+    @infer_event
+    def warning(self, event: str | Any | None = None, **kwargs: Any) -> Any:
+        """Log warning-level event"""
+        return self._route_log("warning", event, **kwargs)
+
+    def bind(self, namespace: str | None = None, **kwargs: Any) -> "Dossier":
+        """Add context to logger for subsequent log calls.
+
+        Example:
+            logger.bind(request_id="abc-123", user_id="user_456")
+            logger.info("processing_request")
+            # Includes: request_id="abc-123", user_id="user_456"
+
+            # Bind to specific namespace:
+            logger.bind(worker_id="w1", namespace="worker")
+            logger.info("task", namespace="worker")  # Has worker_id="w1"
+        """
+        bound_logger = self._get_or_create_namespaced_logger(namespace).bind(**kwargs)
+
+        self._set_namespaced_logger(namespace, bound_logger)
+        return self
+
+    def unbind(self, *keys: str, namespace: str | None = None) -> "Dossier":
+        """Remove context keys from logger.
+
+        Example:
+            logger.bind(request_id="123", user_id="456")
+            logger.info("test")  # Has both
+
+            logger.unbind("request_id")
+            logger.info("test2")  # Only has user_id
+
+            # Unbind from specific namespace:
+            logger.unbind("worker_id", namespace="worker")
+        """
+        # Get or create the logger for this namespace (defaults to "events" if None)
+        unbound_logger = self._get_or_create_namespaced_logger(namespace).unbind(*keys)
+
+        self._set_namespaced_logger(namespace, unbound_logger)
+        return self
+
+    def get_session_path(self) -> Path:
+        """Get the path to the current session directory."""
+        return self.session_dir
+
+    def get_session_id(self) -> str:
+        """Get the current session ID."""
+        return self.session_id
+
+    def __enter__(self) -> "Dossier":
+        return self
+
+    def __exit__(
+        self, exc_type: object | None, exc_val: object | None, exc_tb: object | None
+    ) -> None:
+        pass  # Needed for context manager
+
+
+def _ensure_structlog_configured() -> None:
+    """Configure structlog once globally if not already configured."""
+    global _structlog_configured
+
+    if _structlog_configured:
+        return
+
+    processor_chain: list[Any] = [
+        unpack_dataclasses,
+        unpack_pydantic_models,
+        unpack_generic_objects,
+        structlog.stdlib.add_log_level,
+        structlog.processors.TimeStamper(fmt="iso"),
+        structlog.processors.format_exc_info,
+        make_json_safe,
+        structlog.processors.JSONRenderer(),
+    ]
+
+    structlog.configure(
+        processors=processor_chain,
+        wrapper_class=structlog.stdlib.BoundLogger,
+        logger_factory=structlog.stdlib.LoggerFactory(),
+        cache_logger_on_first_use=True,
+    )
+
+    _structlog_configured = True
+
+
+def _create_logger_infrastructure(
+    log_file: Path,
+    stdlib_logger_name: str,
+    processors: list[Any] | None = None,
+) -> Any:
+    """Create a logger for a specific namespace."""
+    _ensure_structlog_configured()
+
+    # Set up file handler
+    handler = logging.FileHandler(log_file)
+    handler.setFormatter(logging.Formatter("%(message)s"))
+
+    # Configure standard library logger
+    stdlib_logger = logging.getLogger(stdlib_logger_name)
+    stdlib_logger.handlers.clear()
+    stdlib_logger.addHandler(handler)
+    stdlib_logger.setLevel(logging.DEBUG)
+    stdlib_logger.propagate = False
+
+    # Get base structlog logger (uses global config)
+    base_logger = structlog.get_logger(stdlib_logger_name)
+
+    # If custom processors provided, wrap the logger with them
+    if processors:
+        return structlog.wrap_logger(
+            base_logger,
+            wrapper_class=structlog.stdlib.BoundLogger,
+            processors=processors,
+        )
+
+    return base_logger
+
+
+def get_session(
+    log_dir: str | Path = "logs",
+    session_id: str | None = None,
+    processors: list[Any] | None = None,
+    force_new: bool = False,
+) -> Dossier:
+    """
+    Get or create a dossier logging session. Returns existing session if session_id already exists.
+
+    Similar to logging.getLogger(name), this function caches session instances by session_id.
+    Subsequent calls with the same session_id return the cached instance.
+
+    The session_id is user-facing and simple (e.g., "main", "production"), while the actual
+    log directory is timestamped (e.g., "main_20251118_120000/"). This allows easy session
+    retrieval while maintaining chronological organization of log files.
+
+    **Namespaced Logging:**
+    Use the `namespace` kwarg on logging methods to route logs to separate files:
+    ```python
+    logger = get_session(session_id="main")
+    logger.info("event")  # logs to events.jsonl
+    logger.info("event", namespace="worker")  # logs to worker.jsonl
+    logger.info("event", namespace="api.requests")  # logs to api.requests.jsonl
+    ```
+
+    Args:
+        log_dir: Directory to store log files
+        session_id: Simple session identifier (e.g., "main", "worker"). If None, defaults
+                   to "session".
+        processors: Optional list of custom structlog processors
+        force_new: If True, creates new timestamped log directory even if session_id exists
+                  in cache. Useful for restarting sessions with same name.
+
+    Returns:
+        Started Dossier instance (either cached or newly created)
+
+    Example:
+        # Simple session ID, timestamped directory created automatically
+        logger = get_session(session_id="main")
+        # Logs to: logs/main_TIMESTAMP/events.jsonl
+
+        # Subsequent calls return the same instance
+        logger2 = get_session(session_id="main")
+        assert logger is logger2
+
+        # Namespaced logging - single logger, multiple files
+        logger.info("event", namespace="worker")  # logs to main_TIMESTAMP/worker.jsonl
+
+        # Force new session - creates new timestamped directory
+        logger3 = get_session(session_id="main", force_new=True)
+        # Logs to: logs/main_MEW_TIMESTAMP/events.jsonl
+        # Now logger3 is cached under "main"
+
+
+        # With context manager
+        with get_session(session_id="task1") as logger:
+            logger.info("log to temporary session")
+    """
+    # Convert to Path
+    log_dir_path = Path(log_dir)
+    log_dir_path.mkdir(parents=True, exist_ok=True)
+
+    # Default session ID if not provided
+    if session_id is None:
+        # If there's exactly one session in cache and not forcing new, return it (common use case)
+        if not force_new and len(_logger_cache) == 1:
+            return cast(Dossier, next(iter(_logger_cache.values())))
+        # Otherwise default to "session"
+        session_id = "session"
+
+    # Return cached logger if exists (unless force_new)
+    if not force_new and session_id in _logger_cache:
+        return cast(Dossier, _logger_cache[session_id])
+
+    # Create timestamped directory name (session_id + underscore + timestamp)
+    now = datetime.now()
+    timestamp_suffix = now.strftime("%Y%m%d_%H%M%S")
+    timestamped_dir_name = f"{session_id}_{timestamp_suffix}"
+    session_dir = log_dir_path / timestamped_dir_name
+    session_dir.mkdir(parents=True, exist_ok=True)
+
+    # Set up base stdlib logger name (namespaces will be added to this)
+    stdlib_logger_base_name = f"session.{timestamped_dir_name}"
+
+    # Create Dossier wrapper (loggers created lazily on first use)
+    dossier = Dossier(
+        session_id=session_id,
+        session_dir=session_dir,
+        stdlib_logger_base_name=stdlib_logger_base_name,
+        processors=processors,
+    )
+
+    # Cache before returning (using user-facing session_id as key)
+    _logger_cache[session_id] = dossier
+
+    return dossier
+
+
+def close_session(session_id: str) -> None:
+    """Close session and all the namespaced loggers."""
+    if session_id in _logger_cache:
+        dossier = _logger_cache.pop(session_id)
+
+        # Close all namespaced loggers (including "events")
+        for namespace in dossier._namespaced_loggers:
+            # Get the stdlib logger and close its handlers
+            stdlib_logger_name = f"{dossier._stdlib_logger_base_name}.{namespace}"
+            stdlib_logger = logging.getLogger(stdlib_logger_name)
+            for handler in stdlib_logger.handlers[:]:
+                handler.close()
+                stdlib_logger.removeHandler(handler)
+
+
+# Backward compatibility aliases
+get_logger = get_session
+close_logger = close_session

dossier-1.1.3/dossier/processors.py

@@ -0,0 +1,109 @@
+"""Custom structlog processors for session logging."""
+
+from collections.abc import Callable
+from dataclasses import asdict, is_dataclass
+from typing import Any
+
+
+def _recursive_transform(value: Any, transform_func: Callable[[Any], Any]) -> Any:
+    """Recursively apply transform_func to nested structures."""
+    transformed = transform_func(value)
+    if transformed is not value:
+        return transformed
+
+    if isinstance(value, list):
+        return [_recursive_transform(item, transform_func) for item in value]
+    if isinstance(value, tuple):
+        return tuple(_recursive_transform(item, transform_func) for item in value)
+    if isinstance(value, dict) and type(value) is dict:
+        return {k: _recursive_transform(v, transform_func) for k, v in value.items()}
+
+    return value
+
+
+def make_json_safe(
+    logger: Any, method_name: str, event_dict: dict[str, Any]
+) -> dict[str, Any]:
+    """Convert non-JSON-serializable values to strings."""
+
+    def transform(value: Any) -> Any:
+        if value is None or isinstance(value, (bool, int, float, str)):
+            return value
+        if isinstance(value, (list, dict, tuple)):
+            return value  # Let _recursive_transform handle recursion
+        return str(value)  # Convert everything else to string
+
+    for key, value in list(event_dict.items()):
+        event_dict[key] = _recursive_transform(value, transform)
+
+    return event_dict
+
+
+def _process_event_dict(
+    event_dict: dict[str, Any], transform_func: Callable[[Any], Any]
+) -> dict[str, Any]:
+    """Apply transform_func to event_dict values, handling _obj key and flattening."""
+    new_dict = {}
+
+    for key, value in event_dict.items():
+        if key == "_obj":
+            transformed_value = _recursive_transform(value, transform_func)
+            if isinstance(transformed_value, dict):
+                new_dict.update(transformed_value)
+            else:
+                new_dict[key] = transformed_value
+            continue
+
+        direct_transform = transform_func(value)
+        if direct_transform is not value and isinstance(direct_transform, dict):
+            for k, v in direct_transform.items():
+                new_dict[f"{key}_{k}"] = v
+        else:
+            new_dict[key] = _recursive_transform(value, transform_func)
+
+    return new_dict
+
+
+def unpack_dataclasses(
+    logger: Any, method_name: str, event_dict: dict[str, Any]
+) -> dict[str, Any]:
+    """Unpack dataclasses to dicts recursively."""
+
+    def transform(value: Any) -> Any:
+        if is_dataclass(value) and not isinstance(value, type):
+            return asdict(value)
+        return value
+
+    return _process_event_dict(event_dict, transform)
+
+
+def unpack_pydantic_models(
+    logger: Any, method_name: str, event_dict: dict[str, Any]
+) -> dict[str, Any]:
+    """Unpack Pydantic models to dicts recursively."""
+
+    def transform(value: Any) -> Any:
+        if callable(getattr(value, "model_dump", None)):
+            return value.model_dump()
+        return value
+
+    return _process_event_dict(event_dict, transform)
+
+
+def unpack_generic_objects(
+    logger: Any, method_name: str, event_dict: dict[str, Any]
+) -> dict[str, Any]:
+    """Unpack objects with __dict__ to dicts recursively."""
+
+    def transform(value: Any) -> Any:
+        if isinstance(value, (str, int, float, bool, type(None), list, dict, tuple)):
+            return value
+        if is_dataclass(value) and not isinstance(value, type):
+            return value
+        if callable(getattr(value, "model_dump", None)):
+            return value
+        if hasattr(value, "__dict__"):
+            return {k: v for k, v in value.__dict__.items() if not k.startswith("_")}
+        return value
+
+    return _process_event_dict(event_dict, transform)

dossier-1.1.3/pyproject.toml

@@ -0,0 +1,145 @@
+# Version is managed by uv. To bump:
+#   - Patch (0.1.2 -> 0.1.3): uv version --bump patch
+#   - Minor (0.1.2 -> 0.2.0): uv version --bump minor
+#   - Major (0.1.2 -> 1.0.0): uv version --bump major
+# Then create a git tag: git tag v<version> && git push origin v<version>
+# The tag will trigger the publish workflow to PyPI
+
+[project]
+name = "dossier"
+version = "1.1.3"
+description = "A structured logging library for AI agents with session management and object unpacking"
+readme = "README.md"
+requires-python = ">=3.13"
+license = "Apache-2.0"
+authors = [
+    { name = "Ricardo Decal", email = "dossier-project@ricardodecal.com" }
+]
+keywords = ["logging", "structlog", "ai", "agents", "session-management"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: System :: Logging",
+]
+# Do not edit manually. Use `uv add <dep>` and `uv remove <dep>`
+dependencies = [
+    "beartype>=0.22.5",
+    "better-exceptions>=0.3.3",
+    "rich>=14.2.0",
+    "structlog>=25.5.0",
+]
+
+[project.urls]
+Homepage = "https://dossier.ricardodecal.com/"
+Documentation = "https://dossier.ricardodecal.com/"
+Repository = "https://github.com/crypdick/dossier"
+Issues = "https://github.com/crypdick/dossier/issues"
+
+[dependency-groups]
+# Note: use `uvx pre-commit run --all-files` to run the pre-commit hooks
+dev = [
+    "langchain-core>=1.0.5",
+    "mkdocs>=1.6.1",
+    "mkdocs-autorefs>=1.4.3",
+    "mkdocs-gen-files>=0.5.0",
+    "mkdocs-literate-nav>=0.6.2",
+    "mkdocs-llmstxt>=0.4.0",
+    "mkdocs-material>=9.7.0",
+    "mkdocstrings[python]>=0.30.1",
+    "mypy>=1.18.2",
+    "openai>=2.8.1",
+    "openai-agents>=0.5.1",
+    "pydantic>=2.12.4",
+    "pytest>=9.0.1",
+    "pytest-asyncio>=1.3.0",
+    "pytest-cov>=7.0.0",
+    "pytest-xdist>=3.8.0",
+    "requests>=2.32.5",
+    "ruff>=0.14.5",
+    "types-requests>=2.32.0",
+]
+
+
+[tool.pytest.ini_options]
+# Run with `uv run pytest`
+testpaths = ["tests"]
+pythonpath = ["."]
+# Enable concurrent testing with pytest-xdist
+# Use -n auto to automatically detect number of CPUs
+# Or override with: uv run pytest -n <number>
+addopts = "-n auto"
+
+[tool.mypy]
+# Enforce comprehensive type hinting
+python_version = "3.13"
+strict = true
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+disallow_incomplete_defs = true
+disallow_untyped_calls = true
+disallow_untyped_decorators = true
+check_untyped_defs = true
+no_implicit_optional = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+warn_no_return = true
+warn_unreachable = true
+strict_equality = true
+strict_concatenate = true
+# Show error codes
+show_error_codes = true
+# Pretty output
+pretty = true
+
+# Less strict checking for test files
+[[tool.mypy.overrides]]
+module = [
+    "tests.*",
+    "test_.*",
+]
+disallow_untyped_defs = false
+disallow_untyped_calls = false
+check_untyped_defs = false
+ignore_errors = true
+
+
+[tool.ruff]
+# Enable pycodestyle (`E`), Pylint (`PL`), and others
+lint.select = [
+    "E",   # pycodestyle errors
+    "W",   # pycodestyle warnings
+    "F",   # pyflakes
+    "I",   # isort
+    "PLC", # Pylint convention
+]
+
+# Ignore line-too-long (E501) - many docstrings/messages are naturally longer
+lint.ignore = ["E501"]
+
+# PLC0415: Import outside top-level (import-outside-toplevel)
+# This catches imports inside functions/classes which should generally be at module level
+# Can be disabled per-line with # noqa: PLC0415
+lint.extend-select = ["PLC0415"]
+
+# Exclude test files from import-outside-toplevel check
+# Tests commonly use function-scoped imports for isolation
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*.py" = ["PLC0415"]
+"**/test_*.py" = ["PLC0415"]
+
+[build-system]
+requires = ["uv_build>=0.9.2,<0.10.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "dossier"
+module-root = ""
+
+# Include py.typed marker for PEP 561 type hint support
+[tool.uv.build-backend.package-data]
+dossier = ["py.typed"]