logreducer 3.5.1__tar.gz → 3.5.3__tar.gz

{logreducer-3.5.1 → logreducer-3.5.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: logreducer
-Version: 3.5.1
+Version: 3.5.3
 Summary: Reduce GB-scale logs to a representative sample - streaming Python library and CLI with pattern mining and anomaly detection
 Keywords: log,logging,reduction,analysis,pattern-extraction,memory-efficient,streaming,anomaly-detection
 Author: HyperI Team
@@ -17,17 +17,15 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Operating System :: OS Independent
-Requires-Dist: drain3>=0.9.0
-Requires-Dist: psutil>=7.2.0
-Requires-Dist: loguru>=0.7.3
-Requires-Dist: numpy>=2.0.0
-Requires-Dist: scikit-learn>=1.5.0
-Requires-Dist: typer>=0.25.0
-Requires-Dist: clickhouse-connect>=1.0 ; extra == 'clickhouse'
-Requires-Dist: xxhash>=3.0.0 ; extra == 'enhanced'
-Requires-Dist: datasketch>=1.5.0 ; extra == 'enhanced'
-Requires-Dist: confluent-kafka>=2.14.0 ; extra == 'kafka'
-Requires-Dist: sqlalchemy>=2.0.30 ; extra == 'sql'
+Requires-Dist: psutil>=7.2.2
+Requires-Dist: numpy>=2.5.3
+Requires-Dist: scikit-learn>=1.9.1
+Requires-Dist: typer>=0.27.3
+Requires-Dist: clickhouse-connect>=1.9.0 ; extra == 'clickhouse'
+Requires-Dist: xxhash>=4.0.1 ; extra == 'enhanced'
+Requires-Dist: datasketch>=2.0.0 ; extra == 'enhanced'
+Requires-Dist: confluent-kafka>=2.15.1 ; extra == 'kafka'
+Requires-Dist: sqlalchemy>=2.1.3 ; extra == 'sql'
 Maintainer: HyperI Team
 Maintainer-email: HyperI Team <dev@hyperi.io>
 Requires-Python: >=3.14
@@ -337,8 +335,9 @@ reducer = logreducer.LogReducer(mode="hybrid", config=cfg)
 # ...or let logreducer read your env cascade directly: prefixed beats bare.
 cfg = logreducer.BigDialConfig.from_env("MYAPP", "LOGREDUCER")   # MYAPP_MAX_MEMORY_GB wins
 
-# 2. Logging: your app owns the loguru sinks; logreducer registers nothing and
-#    its records flow through YOUR handlers, formatted by YOUR standard.
+# 2. Logging: your app owns the stdlib logging handlers; logreducer attaches
+#    nothing and its records flow through YOUR handlers, at YOUR level,
+#    formatted by YOUR standard.
 logreducer.setup_logging(enable=True, own_sinks=False)
 ```
 
@@ -368,7 +367,7 @@ Logging is off by default. Enable it and pick a format via env vars:
 LOG_LEVEL=DEBUG LOG_FORMAT=json logreducer app.log --log
 ```
 
-`LOG_FORMAT=json` emits one JSON object per line for log aggregators; the default is human-readable (coloured in a terminal, plain in CI/containers). Embedding? See `own_sinks=False` above.
+Logging is the standard library `logging` module, under the `logreducer` logger. `LOG_FORMAT=json` emits one JSON object per line for log aggregators (keys `timestamp`, `level`, `target`, `function`, `line_number`, `message`, `fields`); the default is human-readable (coloured in a terminal, plain in CI/containers). Embedding? See `own_sinks=False` above.
 
 ## Development
 
@@ -386,6 +385,8 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for the toolchain, test layout (including
 
 Copyright 2026 HYPERI PTY LIMITED.
 
+Credits: template mining (`src/logreducer/template_mining.py`) is derived from [Drain3](https://github.com/logpai/Drain3), Copyright (c) 2020-2022 International Business Machines and the Drain3 project contributors, MIT licence. Drain3 builds on the Drain parser in LogPAI's [logparser](https://github.com/logpai/logparser). The module header carries Drain3's licence text in full.
+
 ## Context
 
 Depth: [docs/architecture.md](docs/architecture.md).
@@ -406,6 +407,7 @@ it is given and drops the rest.
 | `src/logreducer/sources.py`, `sinks.py` | the two structural protocols that ARE the integration surface, plus `FileSource` and `FileSink` |
 | `src/logreducer/sql.py`, `clickhouse.py`, `kafka.py` | the optional adapters, one extra each |
 | `src/logreducer/patterns.py`, `anomaly.py`, `temporal.py` | Drain3 mining and fuzzy dedup, Isolation Forest, time-window grouping |
+| `src/logreducer/template_mining.py` | the Drain template miner, derived from Drain3 (credited under License) |
 | `src/logreducer/memory.py` | `MemoryMonitor`, `BoundedDeduplicator`, the file read strategies |
 | `src/logreducer/sampling.py`, `target.py` | dialect-aware SQL sampling, and the `reduce_to_target` batch loop |
 | `src/logreducer/config.py` | `BigDialConfig`, the level presets, the `from_env` cascade |
@@ -438,7 +440,7 @@ Individually: `uv run ruff format`, `uv run ruff check --fix`,
 | Assume a reused `LogReducer` starts clean | Nothing -- `_reset_components()` rebuilds them per run | The dedup seen-set, both Drain3 miners and the fuzzy LSH accumulate per line. Carried into the next run they drop every line as already-seen and return empty (`core.py`) |
 | Share one deduplicator across hybrid's two passes | Rebuild it before the anomaly pass | The pattern pass consumes the seen-set, so the anomaly pass sees everything as seen and no anomalies survive. Hybrid silently degrades to pattern-only (`core.py`) |
 | Assume an unknown config keyword is ignored | Read the `ValueError` and fix the name | A silently dropped override means a user's tuning quietly does nothing (`core.py`) |
-| Read `LogPattern.template` as the final Drain3 template | Treat it as a first-seen snapshot until #5 lands | `extract_patterns` captures `cluster.get_template()` when a cluster FIRST appears, before later lines widen slots to `<*>`, so a varying cluster stores its raw first line. The `<*>`-count priority boost then runs on that stale snapshot (#5, open) |
+| Assume every template is the final Drain3 one | Allow for a cluster the `max_clusters` cap evicted | `extract_patterns` re-reads each template from the live cluster once the feed ends, so a varying cluster carries its `<*>` slots and the priority boost counts them. A cluster LRU-evicted mid-feed is gone by then and keeps the template it had when first seen (`patterns.py`) |
 | Hand-edit the version | Land a conventional commit and let semantic-release do it | The old regime wrote `VERSION` by hand and took five commits to get tagging working. CONTRIBUTING makes it a standing rule |
 
 ### Where this sits
@@ -451,7 +453,7 @@ One declared edge in `dfe-infra/suite.yaml`, and it runs the surprising way.
 
 `dfe-stack suite --consumer logreducer` returns an empty edge list: no repo in
 that graph is something this library depends on. The runtime dependencies
-(drain3, psutil, loguru, numpy, scikit-learn, typer) are packages, declared in
+(psutil, numpy, scikit-learn, typer) are packages, declared in
 `pyproject.toml`, which is where they belong.
 
 The reason dfe-engine gives for not declaring the dependency -- pin it "once it

{logreducer-3.5.1 → logreducer-3.5.3}/README.md

@@ -293,8 +293,9 @@ reducer = logreducer.LogReducer(mode="hybrid", config=cfg)
 # ...or let logreducer read your env cascade directly: prefixed beats bare.
 cfg = logreducer.BigDialConfig.from_env("MYAPP", "LOGREDUCER")   # MYAPP_MAX_MEMORY_GB wins
 
-# 2. Logging: your app owns the loguru sinks; logreducer registers nothing and
-#    its records flow through YOUR handlers, formatted by YOUR standard.
+# 2. Logging: your app owns the stdlib logging handlers; logreducer attaches
+#    nothing and its records flow through YOUR handlers, at YOUR level,
+#    formatted by YOUR standard.
 logreducer.setup_logging(enable=True, own_sinks=False)
 ```
 
@@ -324,7 +325,7 @@ Logging is off by default. Enable it and pick a format via env vars:
 LOG_LEVEL=DEBUG LOG_FORMAT=json logreducer app.log --log
 ```
 
-`LOG_FORMAT=json` emits one JSON object per line for log aggregators; the default is human-readable (coloured in a terminal, plain in CI/containers). Embedding? See `own_sinks=False` above.
+Logging is the standard library `logging` module, under the `logreducer` logger. `LOG_FORMAT=json` emits one JSON object per line for log aggregators (keys `timestamp`, `level`, `target`, `function`, `line_number`, `message`, `fields`); the default is human-readable (coloured in a terminal, plain in CI/containers). Embedding? See `own_sinks=False` above.
 
 ## Development
 
@@ -342,6 +343,8 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for the toolchain, test layout (including
 
 Copyright 2026 HYPERI PTY LIMITED.
 
+Credits: template mining (`src/logreducer/template_mining.py`) is derived from [Drain3](https://github.com/logpai/Drain3), Copyright (c) 2020-2022 International Business Machines and the Drain3 project contributors, MIT licence. Drain3 builds on the Drain parser in LogPAI's [logparser](https://github.com/logpai/logparser). The module header carries Drain3's licence text in full.
+
 ## Context
 
 Depth: [docs/architecture.md](docs/architecture.md).
@@ -362,6 +365,7 @@ it is given and drops the rest.
 | `src/logreducer/sources.py`, `sinks.py` | the two structural protocols that ARE the integration surface, plus `FileSource` and `FileSink` |
 | `src/logreducer/sql.py`, `clickhouse.py`, `kafka.py` | the optional adapters, one extra each |
 | `src/logreducer/patterns.py`, `anomaly.py`, `temporal.py` | Drain3 mining and fuzzy dedup, Isolation Forest, time-window grouping |
+| `src/logreducer/template_mining.py` | the Drain template miner, derived from Drain3 (credited under License) |
 | `src/logreducer/memory.py` | `MemoryMonitor`, `BoundedDeduplicator`, the file read strategies |
 | `src/logreducer/sampling.py`, `target.py` | dialect-aware SQL sampling, and the `reduce_to_target` batch loop |
 | `src/logreducer/config.py` | `BigDialConfig`, the level presets, the `from_env` cascade |
@@ -394,7 +398,7 @@ Individually: `uv run ruff format`, `uv run ruff check --fix`,
 | Assume a reused `LogReducer` starts clean | Nothing -- `_reset_components()` rebuilds them per run | The dedup seen-set, both Drain3 miners and the fuzzy LSH accumulate per line. Carried into the next run they drop every line as already-seen and return empty (`core.py`) |
 | Share one deduplicator across hybrid's two passes | Rebuild it before the anomaly pass | The pattern pass consumes the seen-set, so the anomaly pass sees everything as seen and no anomalies survive. Hybrid silently degrades to pattern-only (`core.py`) |
 | Assume an unknown config keyword is ignored | Read the `ValueError` and fix the name | A silently dropped override means a user's tuning quietly does nothing (`core.py`) |
-| Read `LogPattern.template` as the final Drain3 template | Treat it as a first-seen snapshot until #5 lands | `extract_patterns` captures `cluster.get_template()` when a cluster FIRST appears, before later lines widen slots to `<*>`, so a varying cluster stores its raw first line. The `<*>`-count priority boost then runs on that stale snapshot (#5, open) |
+| Assume every template is the final Drain3 one | Allow for a cluster the `max_clusters` cap evicted | `extract_patterns` re-reads each template from the live cluster once the feed ends, so a varying cluster carries its `<*>` slots and the priority boost counts them. A cluster LRU-evicted mid-feed is gone by then and keeps the template it had when first seen (`patterns.py`) |
 | Hand-edit the version | Land a conventional commit and let semantic-release do it | The old regime wrote `VERSION` by hand and took five commits to get tagging working. CONTRIBUTING makes it a standing rule |
 
 ### Where this sits
@@ -407,7 +411,7 @@ One declared edge in `dfe-infra/suite.yaml`, and it runs the surprising way.
 
 `dfe-stack suite --consumer logreducer` returns an empty edge list: no repo in
 that graph is something this library depends on. The runtime dependencies
-(drain3, psutil, loguru, numpy, scikit-learn, typer) are packages, declared in
+(psutil, numpy, scikit-learn, typer) are packages, declared in
 `pyproject.toml`, which is where they belong.
 
 The reason dfe-engine gives for not declaring the dependency -- pin it "once it

{logreducer-3.5.1 → logreducer-3.5.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "logreducer"
-version = "3.5.1"
+version = "3.5.3"
 description = "Reduce GB-scale logs to a representative sample - streaming Python library and CLI with pattern mining and anomaly detection"
 readme = "README.md"
 license = "Apache-2.0"
@@ -35,12 +35,10 @@ keywords = [
     "anomaly-detection",
 ]
 dependencies = [
-    "drain3>=0.9.0",
-    "psutil>=7.2.0",
-    "loguru>=0.7.3",
-    "numpy>=2.0.0",
-    "scikit-learn>=1.5.0",
-    "typer>=0.25.0",
+    "psutil>=7.2.2",
+    "numpy>=2.5.3",
+    "scikit-learn>=1.9.1",
+    "typer>=0.27.3",
 ]
 
 [[project.authors]]
@@ -53,12 +51,12 @@ email = "dev@hyperi.io"
 
 [project.optional-dependencies]
 enhanced = [
-    "xxhash>=3.0.0",
-    "datasketch>=1.5.0",
+    "xxhash>=4.0.1",
+    "datasketch>=2.0.0",
 ]
-sql = ["sqlalchemy>=2.0.30"]
-clickhouse = ["clickhouse-connect>=1.0"]
-kafka = ["confluent-kafka>=2.14.0"]
+sql = ["sqlalchemy>=2.1.3"]
+clickhouse = ["clickhouse-connect>=1.9.0"]
+kafka = ["confluent-kafka>=2.15.1"]
 
 [project.urls]
 Homepage = "https://github.com/hyperi-io/logreducer"
@@ -72,6 +70,7 @@ logreducer = "logreducer.cli:main"
 
 [tool.uv]
 index-strategy = "unsafe-best-match"
+exclude-newer = "7 days"
 override-dependencies = []
 
 [[tool.uv.index]]
@@ -150,6 +149,7 @@ ignore = [
 fixable = ["ALL"]
 unfixable = []
 dummy-variable-rgx = "^(_+|(_+[a-zA-Z0-9_]*[a-zA-Z0-9]+?))$"
+external = ["V"]
 
 [tool.ruff.lint.per-file-ignores]
 "tests/**" = [
@@ -164,6 +164,15 @@ dummy-variable-rgx = "^(_+|(_+[a-zA-Z0-9_]*[a-zA-Z0-9]+?))$"
     "PT012",
     "RUF043",
 ]
+"src/**" = [
+    "D105",
+    "D107",
+]
+"src/logreducer/sampling.py" = ["S608"]
+"src/logreducer/clickhouse.py" = ["S608"]
+"src/logreducer/core.py" = ["S311"]
+"src/logreducer/memory.py" = ["S311"]
+"src/logreducer/target.py" = ["S311"]
 
 [tool.ruff.lint.pydocstyle]
 convention = "google"
@@ -260,40 +269,43 @@ exclude = [
     "scripts/",
 ]
 
+[tool.vulture]
+min_confidence = 80
+
 [tool.vermin]
 targets = ["3.12"]
 no_tips = true
 
 [tool.hatch.build.targets.sdist]
 exclude = [
-    "/ci",
+    "/CURSOR.md",
     "/GEMINI.md",
-    "/hyperi-ai",
+    "/.cursor",
     "/.windsurf",
-    "/CURSOR.md",
-    "/CLAUDE.md",
-    "/.claude",
     "/.gemini",
+    "/CLAUDE.md",
     "/.github/copilot-instructions.md",
+    "/.claude",
+    "/ci",
+    "/hyperi-ai",
     "/STATE.md",
-    "/.cursor",
 ]
 
 [dependency-groups]
 dev = [
     "pytest>=9.0.0",
     "pytest-cov>=7.0.0",
-    "ruff>=0.15.0",
+    "ruff>=0.16.10",
     "ty>=0.0.34",
     "mypy>=2.0",
     "bandit[toml]>=1.7.0",
     "pip-audit>=2.6.0",
     "vulture>=2.16",
     "vermin>=1.6.0",
-    "sqlalchemy>=2.0.30",
-    "clickhouse-connect>=1.0",
-    "confluent-kafka>=2.14.0",
-    "testcontainers[clickhouse,kafka,postgres,mysql]>=4.14.0",
+    "sqlalchemy>=2.1.3",
+    "clickhouse-connect>=1.9.0",
+    "confluent-kafka>=2.15.1",
+    "testcontainers[clickhouse,kafka,postgres,mysql]>=4.15.0",
     "psycopg[binary]>=3.2",
     "pymysql>=1.1.0",
     "python-dotenv>=1.0.0",

{logreducer-3.5.1 → logreducer-3.5.3}/pyproject.toml.orig

@@ -6,7 +6,7 @@ build-backend = "uv_build"
 
 [project]
 name = "logreducer"
-version = "3.5.1"
+version = "3.5.3"
 authors = [
     { name = "HyperI Team", email = "dev@hyperi.io" },
 ]
@@ -43,27 +43,25 @@ keywords = [
     "anomaly-detection",
 ]
 dependencies = [
-    "drain3>=0.9.0",
-    "psutil>=7.2.0",
-    "loguru>=0.7.3",
-    "numpy>=2.0.0",
-    "scikit-learn>=1.5.0",
-    "typer>=0.25.0",
+    "psutil>=7.2.2",
+    "numpy>=2.5.3",
+    "scikit-learn>=1.9.1",
+    "typer>=0.27.3",
 ]
 
 [project.optional-dependencies]
 enhanced = [
-    "xxhash>=3.0.0",
-    "datasketch>=1.5.0",
+    "xxhash>=4.0.1",
+    "datasketch>=2.0.0",
 ]
 sql = [
-    "sqlalchemy>=2.0.30",
+    "sqlalchemy>=2.1.3",
 ]
 clickhouse = [
-    "clickhouse-connect>=1.0",
+    "clickhouse-connect>=1.9.0",
 ]
 kafka = [
-    "confluent-kafka>=2.14.0",
+    "confluent-kafka>=2.15.1",
 ]
 
 [project.urls]
@@ -78,6 +76,7 @@ logreducer = "logreducer.cli:main"
 
 [tool.uv]
 index-strategy = "unsafe-best-match"
+exclude-newer = "7 days"
 override-dependencies = []
 index = [
     { name = "pypi", url = "https://pypi.org/simple", default = true },
@@ -160,6 +159,9 @@ fixable = [
 ]
 unfixable = []
 dummy-variable-rgx = "^(_+|(_+[a-zA-Z0-9_]*[a-zA-Z0-9]+?))$"
+external = [
+    "V",
+]
 
 [tool.ruff.lint.per-file-ignores]
 "tests/**" = [
@@ -174,6 +176,25 @@ dummy-variable-rgx = "^(_+|(_+[a-zA-Z0-9_]*[a-zA-Z0-9]+?))$"
     "PT012",
     "RUF043",
 ]
+"src/**" = [
+    "D105",
+    "D107",
+]
+"src/logreducer/sampling.py" = [
+    "S608",
+]
+"src/logreducer/clickhouse.py" = [
+    "S608",
+]
+"src/logreducer/core.py" = [
+    "S311",
+]
+"src/logreducer/memory.py" = [
+    "S311",
+]
+"src/logreducer/target.py" = [
+    "S311",
+]
 
 [tool.ruff.lint.pydocstyle]
 convention = "google"
@@ -278,6 +299,9 @@ exclude = [
     "scripts/",
 ]
 
+[tool.vulture]
+min_confidence = 80
+
 [tool.vermin]
 targets = [
     "3.12",
@@ -286,34 +310,34 @@ no_tips = true
 
 [tool.hatch.build.targets.sdist]
 exclude = [
-    "/ci",
+    "/CURSOR.md",
     "/GEMINI.md",
-    "/hyperi-ai",
+    "/.cursor",
     "/.windsurf",
-    "/CURSOR.md",
-    "/CLAUDE.md",
-    "/.claude",
     "/.gemini",
+    "/CLAUDE.md",
     "/.github/copilot-instructions.md",
+    "/.claude",
+    "/ci",
+    "/hyperi-ai",
     "/STATE.md",
-    "/.cursor",
 ]
 
 [dependency-groups]
 dev = [
     "pytest>=9.0.0",
     "pytest-cov>=7.0.0",
-    "ruff>=0.15.0",
+    "ruff>=0.16.10",
     "ty>=0.0.34",
     "mypy>=2.0",
     "bandit[toml]>=1.7.0",
     "pip-audit>=2.6.0",
     "vulture>=2.16",
     "vermin>=1.6.0",
-    "sqlalchemy>=2.0.30",
-    "clickhouse-connect>=1.0",
-    "confluent-kafka>=2.14.0",
-    "testcontainers[clickhouse,kafka,postgres,mysql]>=4.14.0",
+    "sqlalchemy>=2.1.3",
+    "clickhouse-connect>=1.9.0",
+    "confluent-kafka>=2.15.1",
+    "testcontainers[clickhouse,kafka,postgres,mysql]>=4.15.0",
     "psycopg[binary]>=3.2",
     "pymysql>=1.1.0",
     "python-dotenv>=1.0.0",

{logreducer-3.5.1 → logreducer-3.5.3}/src/logreducer/anomaly.py

@@ -1,8 +1,8 @@
-"""
-Anomaly detection utilities
-"""
+"""Anomaly detection utilities."""
 
-from loguru import logger
+import logging
+
+logger = logging.getLogger(__name__)
 
 # Try optional imports
 try:
@@ -15,7 +15,7 @@ except ImportError:
 
 
 class AnomalyDetector:
-    """Detect anomalous log lines"""
+    """Detect anomalous log lines."""
 
     def __init__(self, contamination: float = 0.1):
         self.contamination = contamination
@@ -25,8 +25,7 @@ class AnomalyDetector:
             logger.warning("scikit-learn not available, anomaly detection disabled")
 
     def detect_anomalies(self, lines: list[str]) -> tuple[list[str], list[str]]:
-        """
-        Separate anomalous and normal lines
+        """Separate anomalous and normal lines.
 
         Returns:
             (anomalous_lines, normal_lines)

{logreducer-3.5.1 → logreducer-3.5.3}/src/logreducer/config.py

@@ -1,5 +1,6 @@
 """Configuration and tuning parameters for LogReducer."""
 
+import logging
 import os
 import types
 import typing
@@ -7,7 +8,8 @@ from dataclasses import dataclass, fields
 from enum import Enum
 
 import psutil
-from loguru import logger
+
+logger = logging.getLogger(__name__)
 
 
 class ProcessingLevel(Enum):

{logreducer-3.5.1 → logreducer-3.5.3}/src/logreducer/core.py

@@ -1,6 +1,4 @@
-"""
-Core LogReducer implementation
-"""
+"""Core LogReducer implementation."""
 
 import json
 import os
@@ -10,7 +8,7 @@ from dataclasses import replace
 from datetime import datetime
 from enum import Enum
 from pathlib import Path
-from typing import Any
+from typing import Any, Literal, overload
 
 from .anomaly import AnomalyDetector
 from .config import BigDialConfig, OutputFormat, ProcessingLevel, ProcessingMode, get_preset_config
@@ -24,8 +22,7 @@ from .temporal import TemporalProcessor
 
 
 class LogReducer:
-    """
-    Main log reduction class
+    """Main log reduction class.
 
     Example:
         reducer = LogReducer(level="enhanced")
@@ -41,8 +38,7 @@ class LogReducer:
         config: BigDialConfig | None = None,
         **kwargs: Any,
     ) -> None:
-        """
-        Initialize LogReducer
+        """Initialize LogReducer.
 
         Args:
             level: Processing level (standard/enhanced/maximum)
@@ -134,13 +130,41 @@ class LogReducer:
         else:
             self.temporal_processor = None
 
+    @overload
+    def reduce(
+        self,
+        source: Source,
+        output_file: str | None = None,
+        return_metadata: Literal[False] = False,
+        sink: Sink | None = None,
+    ) -> list[str]: ...
+
+    @overload
+    def reduce(
+        self,
+        source: Source,
+        output_file: str | None = None,
+        *,
+        return_metadata: Literal[True],
+        sink: Sink | None = None,
+    ) -> dict[str, Any]: ...
+
+    @overload
     def reduce(
         self,
         source: Source,
         output_file: str | None = None,
         return_metadata: bool = False,
         sink: Sink | None = None,
-    ) -> list[str] | dict:
+    ) -> list[str] | dict[str, Any]: ...
+
+    def reduce(
+        self,
+        source: Source,
+        output_file: str | None = None,
+        return_metadata: bool = False,
+        sink: Sink | None = None,
+    ) -> list[str] | dict[str, Any]:
         """Reduce a source of log lines to a representative sample.
 
         This is the core entry point: it operates on an abstraction, not on IO.
@@ -241,12 +265,37 @@ class LogReducer:
             }
         return result_lines
 
+    @overload
+    def process_file(
+        self,
+        input_file: str,
+        output_file: str | None = None,
+        return_metadata: Literal[False] = False,
+    ) -> list[str]: ...
+
+    @overload
+    def process_file(
+        self,
+        input_file: str,
+        output_file: str | None = None,
+        *,
+        return_metadata: Literal[True],
+    ) -> dict[str, Any]: ...
+
+    @overload
+    def process_file(
+        self,
+        input_file: str,
+        output_file: str | None = None,
+        return_metadata: bool = False,
+    ) -> list[str] | dict[str, Any]: ...
+
     def process_file(
         self,
         input_file: str,
         output_file: str | None = None,
         return_metadata: bool = False,
-    ) -> list[str] | dict:
+    ) -> list[str] | dict[str, Any]:
         """Reduce a log file - convenience wrapper over reduce() + FileSource.
 
         Args:
@@ -302,7 +351,7 @@ class LogReducer:
         return unique_lines
 
     def _process_anomaly_mode(self, source: Source) -> list[str]:
-        """Process using anomaly detection"""
+        """Process using anomaly detection."""
         if not self.anomaly_detector:
             if self.config.enable_logging:
                 self.logger.warning("Anomaly detector not available, falling back to pattern mode")
@@ -329,7 +378,7 @@ class LogReducer:
         return result
 
     def _process_temporal_mode(self, source: Source) -> list[str]:
-        """Process using temporal analysis"""
+        """Process using temporal analysis."""
         if not self.temporal_processor:
             if self.config.enable_logging:
                 self.logger.warning("Temporal processor not available, falling back to pattern mode")
@@ -356,7 +405,7 @@ class LogReducer:
         return result
 
     def _process_hybrid_mode(self, source: Source) -> list[str]:
-        """Process using combined approach"""
+        """Process using combined approach."""
         if self.config.enable_logging:
             self.logger.info("Hybrid mode: combining pattern and anomaly detection")
 
@@ -400,7 +449,7 @@ class LogReducer:
         }
 
     def _save_output(self, lines: list[str], output_file: str) -> None:
-        """Save output to file in specified format"""
+        """Save output to file in specified format."""
         output_path = Path(output_file)
         output_path.parent.mkdir(parents=True, exist_ok=True)
 
@@ -453,7 +502,7 @@ class LogReducer:
                 self.logger.info(f"Metadata saved to {meta_file}")
 
     def _print_summary(self) -> None:
-        """Log processing summary"""
+        """Log processing summary."""
         self.logger.info("\n" + "=" * 60)
         self.logger.info("LOG REDUCTION SUMMARY")
         self.logger.info("=" * 60)
@@ -474,7 +523,7 @@ class LogReducer:
         self.logger.info("=" * 60)
 
     def estimate_processing(self, file_path: str) -> dict:
-        """Estimate processing requirements before running"""
+        """Estimate processing requirements before running."""
         file_size = os.path.getsize(file_path)
         file_size_gb = file_size / (1024**3)