pfc-jsonl 0.1.0__tar.gz

pfc_jsonl-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ImpossibleForge
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pfc_jsonl-0.1.0/PKG-INFO

@@ -0,0 +1,236 @@
+Metadata-Version: 2.4
+Name: pfc-jsonl
+Version: 0.1.0
+Summary: Python interface for PFC-JSONL — high-performance log compression with block-level timestamp filtering
+Project-URL: Homepage, https://github.com/ImpossibleForge/pfc-jsonl
+Project-URL: Repository, https://github.com/ImpossibleForge/pfc-jsonl
+Project-URL: Bug Tracker, https://github.com/ImpossibleForge/pfc-jsonl/issues
+Project-URL: Changelog, https://github.com/ImpossibleForge/pfc-jsonl/releases
+Author-email: ImpossibleForge <impossibleforge@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: compression,duckdb,fluent-bit,jsonl,log-compression,logs,structured-logs
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Archiving :: Compression
+Classifier: Topic :: System :: Logging
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# pfc-jsonl · Python Package
+
+Python interface for **PFC-JSONL** — high-performance compression for structured log files (JSONL), with block-level timestamp filtering.
+
+```
+pip install pfc-jsonl
+```
+
+> **Requires the `pfc_jsonl` binary.** Install it separately — see [below](#install-the-binary).
+
+---
+
+## What is PFC-JSONL?
+
+PFC-JSONL compresses JSONL log files **26–34% smaller than gzip/zstd** on typical log data. It stores a timestamp index alongside each file, enabling fast time-range queries without full decompression.
+
+| Operation | Description |
+|-----------|-------------|
+| `compress` | JSONL → `.pfc` (with timestamp index) |
+| `decompress` | `.pfc` → JSONL |
+| `query` | Decompress only blocks matching a time range |
+| `seek_blocks` | Decompress specific blocks by index (DuckDB primitive) |
+
+---
+
+## Quick Start
+
+```python
+import pfc
+
+# Compress
+pfc.compress("logs/app.jsonl", "logs/app.pfc")
+
+# Decompress
+pfc.decompress("logs/app.pfc", "logs/app_restored.jsonl")
+
+# Query by time range — only decompresses matching blocks
+pfc.query("logs/app.pfc",
+          from_ts="2026-01-15T08:00:00",
+          to_ts="2026-01-15T09:00:00",
+          output_path="logs/morning.jsonl")
+
+# Check Community Mode usage
+usage = pfc.community_usage()
+print(f"Used {usage['used_gb']:.2f} GB of {usage['limit_gb']} GB today")
+```
+
+---
+
+## Install the Binary
+
+The Python package is a thin wrapper — the compression engine is the `pfc_jsonl` binary.
+
+**Linux (x64):**
+```bash
+curl -L https://github.com/ImpossibleForge/pfc-jsonl/releases/latest/download/pfc_jsonl-linux-x64 \
+     -o pfc_jsonl && chmod +x pfc_jsonl && sudo mv pfc_jsonl /usr/local/bin/
+```
+
+**macOS:** Coming soon.
+
+**Windows:** Download `pfc_jsonl-windows-x64.exe` from the [releases page](https://github.com/ImpossibleForge/pfc-jsonl/releases), rename to `pfc_jsonl.exe`, add to PATH.
+
+**Custom location:** Set the `PFC_BINARY` environment variable:
+```bash
+export PFC_BINARY=/opt/tools/pfc_jsonl
+```
+
+Verify:
+```bash
+pfc_jsonl --help
+```
+
+---
+
+## API Reference
+
+### `pfc.compress(input_path, output_path, *, level="balanced", block_size_mb=None, workers=None, verbose=False)`
+
+Compress a JSONL file to PFC format.
+
+```python
+pfc.compress("logs/app.jsonl", "logs/app.pfc")
+pfc.compress("big.jsonl", "big.pfc", level="max", workers=4)
+```
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `level` | `"balanced"` | `"fast"`, `"balanced"`, or `"max"` |
+| `block_size_mb` | auto | Block size in MiB (power of 2, e.g. 16, 32) |
+| `workers` | auto | Parallel compression workers |
+| `verbose` | `False` | Print progress from binary |
+
+---
+
+### `pfc.decompress(input_path, output_path="-", *, verbose=False)`
+
+Decompress a PFC file back to JSONL.
+
+```python
+pfc.decompress("logs/app.pfc", "logs/app_restored.jsonl")
+```
+
+---
+
+### `pfc.query(pfc_path, from_ts, to_ts, output_path="-", *, verbose=False)`
+
+Decompress only the blocks matching a timestamp range.
+
+```python
+pfc.query("logs/app.pfc",
+          from_ts="2026-01-15T08:00:00",
+          to_ts="2026-01-15T09:00:00",
+          output_path="logs/morning.jsonl")
+```
+
+Timestamps can be ISO 8601 strings or Unix epoch integers (as strings).
+
+---
+
+### `pfc.seek_blocks(pfc_path, blocks, output_path="-", *, verbose=False)`
+
+Decompress specific blocks by index. Used internally by the DuckDB extension.
+
+```python
+pfc.seek_blocks("logs/app.pfc", [0, 3, 7], "logs/selected.jsonl")
+```
+
+---
+
+### `pfc.community_usage() -> dict`
+
+Return today's Community Mode usage without invoking the binary.
+
+```python
+usage = pfc.community_usage()
+# {
+#   "date": "2026-04-04",
+#   "bytes_today": 1073741824,
+#   "bytes_remaining": 4294967296,
+#   "limit_gb": 5.0,
+#   "used_gb": 1.0
+# }
+```
+
+---
+
+### `pfc.get_binary() -> str`
+
+Return the path to the `pfc_jsonl` binary being used.
+
+```python
+print(pfc.get_binary())  # /usr/local/bin/pfc_jsonl
+```
+
+---
+
+## Community Mode
+
+Without a license key, PFC-JSONL runs in **Community Mode**:
+
+- All operations (compress, decompress, query, seek-blocks) are **free up to 5 GB/day**
+- Usage is tracked locally in `~/.pfc/usage.json` — **no network calls**
+- Resets every calendar day
+
+For production use exceeding 5 GB/day, contact: **impossibleforge@gmail.com**
+
+---
+
+## Error Handling
+
+```python
+import pfc
+from pfc import PFCError
+
+try:
+    pfc.compress("missing.jsonl", "out.pfc")
+except FileNotFoundError as e:
+    print(f"Binary not found: {e}")
+except PFCError as e:
+    print(f"Compression failed (exit {e.returncode}): {e.stderr}")
+```
+
+---
+
+## Integration with Fluent Bit
+
+Use [pfc-fluentbit](https://github.com/ImpossibleForge/pfc-fluentbit) to receive logs from Fluent Bit and compress them automatically.
+
+## Integration with DuckDB
+
+Use the [pfc DuckDB extension](https://github.com/ImpossibleForge/pfc-duckdb) to query `.pfc` files directly with SQL:
+
+```sql
+INSTALL pfc FROM community;
+LOAD pfc;
+SELECT * FROM read_pfc_jsonl('logs/app.pfc') WHERE level = 'ERROR';
+```
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE)
+
+Binary releases are proprietary. See [pfc-jsonl releases](https://github.com/ImpossibleForge/pfc-jsonl/releases) for terms.

pfc_jsonl-0.1.0/README.md

@@ -0,0 +1,206 @@
+# pfc-jsonl · Python Package
+
+Python interface for **PFC-JSONL** — high-performance compression for structured log files (JSONL), with block-level timestamp filtering.
+
+```
+pip install pfc-jsonl
+```
+
+> **Requires the `pfc_jsonl` binary.** Install it separately — see [below](#install-the-binary).
+
+---
+
+## What is PFC-JSONL?
+
+PFC-JSONL compresses JSONL log files **26–34% smaller than gzip/zstd** on typical log data. It stores a timestamp index alongside each file, enabling fast time-range queries without full decompression.
+
+| Operation | Description |
+|-----------|-------------|
+| `compress` | JSONL → `.pfc` (with timestamp index) |
+| `decompress` | `.pfc` → JSONL |
+| `query` | Decompress only blocks matching a time range |
+| `seek_blocks` | Decompress specific blocks by index (DuckDB primitive) |
+
+---
+
+## Quick Start
+
+```python
+import pfc
+
+# Compress
+pfc.compress("logs/app.jsonl", "logs/app.pfc")
+
+# Decompress
+pfc.decompress("logs/app.pfc", "logs/app_restored.jsonl")
+
+# Query by time range — only decompresses matching blocks
+pfc.query("logs/app.pfc",
+          from_ts="2026-01-15T08:00:00",
+          to_ts="2026-01-15T09:00:00",
+          output_path="logs/morning.jsonl")
+
+# Check Community Mode usage
+usage = pfc.community_usage()
+print(f"Used {usage['used_gb']:.2f} GB of {usage['limit_gb']} GB today")
+```
+
+---
+
+## Install the Binary
+
+The Python package is a thin wrapper — the compression engine is the `pfc_jsonl` binary.
+
+**Linux (x64):**
+```bash
+curl -L https://github.com/ImpossibleForge/pfc-jsonl/releases/latest/download/pfc_jsonl-linux-x64 \
+     -o pfc_jsonl && chmod +x pfc_jsonl && sudo mv pfc_jsonl /usr/local/bin/
+```
+
+**macOS:** Coming soon.
+
+**Windows:** Download `pfc_jsonl-windows-x64.exe` from the [releases page](https://github.com/ImpossibleForge/pfc-jsonl/releases), rename to `pfc_jsonl.exe`, add to PATH.
+
+**Custom location:** Set the `PFC_BINARY` environment variable:
+```bash
+export PFC_BINARY=/opt/tools/pfc_jsonl
+```
+
+Verify:
+```bash
+pfc_jsonl --help
+```
+
+---
+
+## API Reference
+
+### `pfc.compress(input_path, output_path, *, level="balanced", block_size_mb=None, workers=None, verbose=False)`
+
+Compress a JSONL file to PFC format.
+
+```python
+pfc.compress("logs/app.jsonl", "logs/app.pfc")
+pfc.compress("big.jsonl", "big.pfc", level="max", workers=4)
+```
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `level` | `"balanced"` | `"fast"`, `"balanced"`, or `"max"` |
+| `block_size_mb` | auto | Block size in MiB (power of 2, e.g. 16, 32) |
+| `workers` | auto | Parallel compression workers |
+| `verbose` | `False` | Print progress from binary |
+
+---
+
+### `pfc.decompress(input_path, output_path="-", *, verbose=False)`
+
+Decompress a PFC file back to JSONL.
+
+```python
+pfc.decompress("logs/app.pfc", "logs/app_restored.jsonl")
+```
+
+---
+
+### `pfc.query(pfc_path, from_ts, to_ts, output_path="-", *, verbose=False)`
+
+Decompress only the blocks matching a timestamp range.
+
+```python
+pfc.query("logs/app.pfc",
+          from_ts="2026-01-15T08:00:00",
+          to_ts="2026-01-15T09:00:00",
+          output_path="logs/morning.jsonl")
+```
+
+Timestamps can be ISO 8601 strings or Unix epoch integers (as strings).
+
+---
+
+### `pfc.seek_blocks(pfc_path, blocks, output_path="-", *, verbose=False)`
+
+Decompress specific blocks by index. Used internally by the DuckDB extension.
+
+```python
+pfc.seek_blocks("logs/app.pfc", [0, 3, 7], "logs/selected.jsonl")
+```
+
+---
+
+### `pfc.community_usage() -> dict`
+
+Return today's Community Mode usage without invoking the binary.
+
+```python
+usage = pfc.community_usage()
+# {
+#   "date": "2026-04-04",
+#   "bytes_today": 1073741824,
+#   "bytes_remaining": 4294967296,
+#   "limit_gb": 5.0,
+#   "used_gb": 1.0
+# }
+```
+
+---
+
+### `pfc.get_binary() -> str`
+
+Return the path to the `pfc_jsonl` binary being used.
+
+```python
+print(pfc.get_binary())  # /usr/local/bin/pfc_jsonl
+```
+
+---
+
+## Community Mode
+
+Without a license key, PFC-JSONL runs in **Community Mode**:
+
+- All operations (compress, decompress, query, seek-blocks) are **free up to 5 GB/day**
+- Usage is tracked locally in `~/.pfc/usage.json` — **no network calls**
+- Resets every calendar day
+
+For production use exceeding 5 GB/day, contact: **impossibleforge@gmail.com**
+
+---
+
+## Error Handling
+
+```python
+import pfc
+from pfc import PFCError
+
+try:
+    pfc.compress("missing.jsonl", "out.pfc")
+except FileNotFoundError as e:
+    print(f"Binary not found: {e}")
+except PFCError as e:
+    print(f"Compression failed (exit {e.returncode}): {e.stderr}")
+```
+
+---
+
+## Integration with Fluent Bit
+
+Use [pfc-fluentbit](https://github.com/ImpossibleForge/pfc-fluentbit) to receive logs from Fluent Bit and compress them automatically.
+
+## Integration with DuckDB
+
+Use the [pfc DuckDB extension](https://github.com/ImpossibleForge/pfc-duckdb) to query `.pfc` files directly with SQL:
+
+```sql
+INSTALL pfc FROM community;
+LOAD pfc;
+SELECT * FROM read_pfc_jsonl('logs/app.pfc') WHERE level = 'ERROR';
+```
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE)
+
+Binary releases are proprietary. See [pfc-jsonl releases](https://github.com/ImpossibleForge/pfc-jsonl/releases) for terms.

pfc_jsonl-0.1.0/pfc/__init__.py

@@ -0,0 +1,237 @@
+"""
+pfc — Python interface for PFC-JSONL compression.
+
+PFC-JSONL is a high-performance compressor for structured log files (JSONL).
+This package provides a thin Python wrapper around the pfc_jsonl binary.
+
+Community Mode (no license key):
+    All operations are free up to 5 GB per calendar day.
+    Usage is tracked locally in ~/.pfc/usage.json — no network calls.
+
+License keys for production use (>5 GB/day):
+    https://github.com/ImpossibleForge/pfc-jsonl
+
+Quick start:
+    >>> import pfc
+    >>> pfc.compress("app.jsonl", "app.pfc")
+    >>> pfc.decompress("app.pfc", "app_restored.jsonl")
+    >>> results = pfc.query("app.pfc", "2026-01-01T00:00:00", "2026-01-02T00:00:00")
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Optional
+
+from ._core import PFCError, _find_binary, run
+
+__version__ = "0.1.0"
+__all__ = [
+    "compress",
+    "decompress",
+    "query",
+    "seek_blocks",
+    "community_usage",
+    "get_binary",
+    "PFCError",
+]
+
+
+def get_binary() -> str:
+    """Return the path to the pfc_jsonl binary being used.
+
+    Useful for debugging which binary is picked up.
+
+    Returns:
+        Absolute path string.
+
+    Raises:
+        FileNotFoundError: if no binary is found.
+    """
+    return _find_binary()
+
+
+def compress(
+    input_path: str,
+    output_path: str,
+    *,
+    level: str = "balanced",
+    block_size_mb: Optional[int] = None,
+    workers: Optional[int] = None,
+    verbose: bool = False,
+) -> None:
+    """Compress a JSONL file to PFC format.
+
+    Community Mode: counts input bytes toward the 5 GB/day limit.
+
+    Args:
+        input_path:    Path to the input .jsonl file (or "-" for stdin).
+        output_path:   Path to write the compressed .pfc file.
+        level:         Compression level: "fast", "balanced" (default), or "max".
+        block_size_mb: Block size in MiB (must be a power of 2, e.g. 16, 32).
+                       Defaults to the binary's built-in default.
+        workers:       Number of parallel compression workers.
+                       Defaults to the binary's auto-detection.
+        verbose:       Print progress info from the binary.
+
+    Raises:
+        FileNotFoundError: if pfc_jsonl binary is not found.
+        PFCError:          if compression fails.
+
+    Example:
+        >>> pfc.compress("logs/app.jsonl", "logs/app.pfc")
+        >>> pfc.compress("big.jsonl", "big.pfc", level="max", workers=4)
+    """
+    args = ["compress", input_path, output_path, "--level", level]
+    if block_size_mb is not None:
+        args += ["--block-size", str(block_size_mb)]
+    if workers is not None:
+        args += ["--workers", str(workers)]
+    if not verbose:
+        args += ["--quiet"]
+    run(args)
+
+
+def decompress(
+    input_path: str,
+    output_path: str = "-",
+    *,
+    verbose: bool = False,
+) -> None:
+    """Decompress a PFC file back to JSONL.
+
+    Community Mode: counts decompressed output bytes toward the 5 GB/day limit.
+
+    Args:
+        input_path:  Path to the .pfc file (or "-" for stdin).
+        output_path: Path to write the restored .jsonl file.
+                     Use "-" to write to stdout (default).
+        verbose:     Print progress info from the binary.
+
+    Raises:
+        FileNotFoundError: if pfc_jsonl binary is not found.
+        PFCError:          if decompression fails.
+
+    Example:
+        >>> pfc.decompress("logs/app.pfc", "logs/app_restored.jsonl")
+    """
+    args = ["decompress", input_path, output_path]
+    if not verbose:
+        args += ["--quiet"]
+    run(args)
+
+
+def query(
+    pfc_path: str,
+    from_ts: str,
+    to_ts: str,
+    output_path: str = "-",
+    *,
+    verbose: bool = False,
+) -> None:
+    """Decompress only the blocks matching a timestamp range.
+
+    Block-level filtering: only blocks that overlap the given time range
+    are decompressed. Much faster than full decompression for recent logs.
+
+    Community Mode: counts decompressed output bytes toward the 5 GB/day limit.
+
+    Args:
+        pfc_path:    Path to the .pfc file.
+        from_ts:     Start of the time range (ISO 8601 or Unix timestamp).
+                     Example: "2026-01-01T00:00:00" or "1735689600"
+        to_ts:       End of the time range (inclusive).
+        output_path: Path to write the results. Use "-" for stdout (default).
+        verbose:     Print block selection info from the binary.
+
+    Raises:
+        FileNotFoundError: if pfc_jsonl binary is not found.
+        PFCError:          if the query fails.
+
+    Example:
+        >>> pfc.query("logs/app.pfc", "2026-01-15T08:00:00", "2026-01-15T09:00:00",
+        ...           "logs/morning.jsonl")
+    """
+    args = ["query", pfc_path, "--from", from_ts, "--to", to_ts, "--out", output_path]
+    if not verbose:
+        args += ["--quiet"]
+    run(args)
+
+
+def seek_blocks(
+    pfc_path: str,
+    blocks: list[int],
+    output_path: str = "-",
+    *,
+    verbose: bool = False,
+) -> None:
+    """Decompress specific blocks by index without reading the full file.
+
+    This is the low-level primitive used by the DuckDB extension internally.
+    Useful for building custom query layers on top of PFC files.
+
+    Community Mode: counts decompressed output bytes toward the 5 GB/day limit.
+
+    Args:
+        pfc_path:    Path to the .pfc file.
+        blocks:      List of 0-based block indices to decompress.
+        output_path: Path to write the result. Use "-" for stdout (default).
+        verbose:     Print seek info from the binary.
+
+    Raises:
+        FileNotFoundError: if pfc_jsonl binary is not found.
+        PFCError:          if decompression fails.
+        ValueError:        if blocks list is empty.
+
+    Example:
+        >>> pfc.seek_blocks("logs/app.pfc", [0, 3, 7], "logs/selected.jsonl")
+    """
+    if not blocks:
+        raise ValueError("blocks list must not be empty")
+    args = ["seek-blocks", pfc_path, "--blocks"] + [str(b) for b in blocks]
+    args += ["--out", output_path]
+    if not verbose:
+        args += ["--quiet"]
+    run(args)
+
+
+def community_usage() -> dict:
+    """Return today's Community Mode usage.
+
+    Reads ~/.pfc/usage.json without invoking the binary.
+
+    Returns:
+        dict with keys:
+            "date"            (str)  — today's date, e.g. "2026-04-04"
+            "bytes_today"     (int)  — bytes processed today
+            "bytes_remaining" (int)  — bytes remaining before the 5 GB limit
+            "limit_gb"        (float) — daily limit in GB (always 5.0)
+            "used_gb"         (float) — bytes_today converted to GB
+
+    Example:
+        >>> usage = pfc.community_usage()
+        >>> print(f"Used {usage['used_gb']:.2f} GB of {usage['limit_gb']} GB today")
+    """
+    import time
+
+    limit = 5 * 1024 ** 3
+    usage_path = Path.home() / ".pfc" / "usage.json"
+    today = time.strftime("%Y-%m-%d")
+
+    bytes_today = 0
+    try:
+        if usage_path.exists():
+            data = json.loads(usage_path.read_text(encoding="utf-8"))
+            if data.get("date") == today:
+                bytes_today = int(data.get("bytes_today", 0))
+    except Exception:
+        pass
+
+    return {
+        "date": today,
+        "bytes_today": bytes_today,
+        "bytes_remaining": max(0, limit - bytes_today),
+        "limit_gb": 5.0,
+        "used_gb": round(bytes_today / 1024 ** 3, 3),
+    }

pfc_jsonl-0.1.0/pfc/_core.py

@@ -0,0 +1,111 @@
+"""
+pfc._core — Binary finder and subprocess runner.
+
+Locates the pfc_jsonl binary and provides a thin wrapper
+for calling it as a subprocess. No algorithm logic here.
+"""
+
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+
+def _find_binary() -> str:
+    """Locate the pfc_jsonl binary.
+
+    Search order:
+    1. PFC_BINARY environment variable
+    2. PATH (shutil.which)
+    3. Common install locations
+    4. Same directory as this package
+
+    Raises:
+        FileNotFoundError: if the binary cannot be found.
+    """
+    # 1. Explicit override
+    env_path = os.environ.get("PFC_BINARY")
+    if env_path and Path(env_path).is_file():
+        return env_path
+
+    # 2. PATH
+    binary_name = "pfc_jsonl.exe" if sys.platform == "win32" else "pfc_jsonl"
+    found = shutil.which(binary_name)
+    if found:
+        return found
+
+    # 3. Common locations
+    candidates = [
+        Path("/usr/local/bin/pfc_jsonl"),
+        Path("/usr/bin/pfc_jsonl"),
+        Path.home() / ".local" / "bin" / "pfc_jsonl",
+        Path.home() / "bin" / "pfc_jsonl",
+    ]
+    for p in candidates:
+        if p.is_file():
+            return str(p)
+
+    # 4. Package directory (for bundled installs)
+    pkg_dir = Path(__file__).parent
+    local = pkg_dir / binary_name
+    if local.is_file():
+        return str(local)
+
+    raise FileNotFoundError(
+        "pfc_jsonl binary not found.\n\n"
+        "Install it first:\n"
+        "  Linux:   curl -L https://github.com/ImpossibleForge/pfc-jsonl/releases/"
+        "latest/download/pfc_jsonl-linux-x64 -o pfc_jsonl && chmod +x pfc_jsonl && "
+        "sudo mv pfc_jsonl /usr/local/bin/\n"
+        "  macOS:   coming soon\n"
+        "  Windows: download pfc_jsonl-windows-x64.exe from the releases page\n\n"
+        "Or set the PFC_BINARY environment variable to the binary path."
+    )
+
+
+def run(args: list, capture_stdout: bool = False) -> subprocess.CompletedProcess:
+    """Run pfc_jsonl with the given argument list.
+
+    Args:
+        args:           Argument list, e.g. ["compress", "in.jsonl", "out.pfc"]
+        capture_stdout: If True, capture stdout instead of letting it through.
+
+    Returns:
+        CompletedProcess instance.
+
+    Raises:
+        FileNotFoundError: if binary is missing.
+        PFCError:          if the binary exits with a non-zero status.
+    """
+    binary = _find_binary()
+    cmd = [binary] + args
+    result = subprocess.run(
+        cmd,
+        stdout=subprocess.PIPE if capture_stdout else None,
+        stderr=subprocess.PIPE,
+        text=False,
+    )
+    if result.returncode != 0:
+        stderr_msg = result.stderr.decode(errors="replace").strip() if result.stderr else ""
+        raise PFCError(
+            f"pfc_jsonl exited with code {result.returncode}",
+            returncode=result.returncode,
+            stderr=stderr_msg,
+        )
+    return result
+
+
+class PFCError(RuntimeError):
+    """Raised when pfc_jsonl exits with a non-zero status."""
+
+    def __init__(self, message: str, returncode: int = -1, stderr: str = ""):
+        super().__init__(message)
+        self.returncode = returncode
+        self.stderr = stderr
+
+    def __str__(self):
+        base = super().__str__()
+        if self.stderr:
+            return f"{base}\n  stderr: {self.stderr}"
+        return base

pfc_jsonl-0.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pfc-jsonl"
+version = "0.1.0"
+description = "Python interface for PFC-JSONL — high-performance log compression with block-level timestamp filtering"
+readme = "README.md"
+license = { text = "MIT" }
+authors = [
+    { name = "ImpossibleForge", email = "impossibleforge@gmail.com" }
+]
+keywords = [
+    "compression", "jsonl", "logs", "log-compression",
+    "structured-logs", "fluent-bit", "duckdb"
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: System Administrators",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: POSIX :: Linux",
+    "Operating System :: MacOS",
+    "Operating System :: Microsoft :: Windows",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: System :: Logging",
+    "Topic :: System :: Archiving :: Compression",
+]
+requires-python = ">=3.9"
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/ImpossibleForge/pfc-jsonl"
+Repository = "https://github.com/ImpossibleForge/pfc-jsonl"
+"Bug Tracker" = "https://github.com/ImpossibleForge/pfc-jsonl/issues"
+Changelog = "https://github.com/ImpossibleForge/pfc-jsonl/releases"
+
+[tool.hatch.build.targets.wheel]
+packages = ["pfc"]