gcf-python 0.1.0__py3-none-any.whl → 0.1.2__py3-none-any.whl

gcf/__init__.py

@@ -38,6 +38,7 @@ from .constants import KIND_ABBREV, KIND_EXPAND
 from .decode import DecodeError, decode
 from .delta import encode_delta
 from .encode import encode
+from .generic import encode_generic
 from .session import Session, encode_with_session
 from .types import Components, DeltaPayload, Edge, Payload, Symbol
 
@@ -54,7 +55,8 @@ __all__ = [
     "decode",
     "encode",
     "encode_delta",
+    "encode_generic",
     "encode_with_session",
 ]
 
-__version__ = "0.1.0"
+__version__ = "0.1.2"

gcf/decode.py

@@ -1,5 +1,7 @@
 """GCF decoder: parses GCF text back into a Payload."""
 
+from __future__ import annotations
+
 from .constants import KIND_EXPAND
 from .types import Edge, Payload, Symbol
 

gcf/encode.py

@@ -1,5 +1,7 @@
 """GCF encoder: serializes Payload into GCF text format."""
 
+from __future__ import annotations
+
 from .constants import KIND_ABBREV
 from .types import Payload, Symbol
 

gcf/generic.py

@@ -0,0 +1,151 @@
+"""GCF generic encoder: serializes arbitrary Python values into GCF tabular format."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def encode_generic(data: Any) -> str:
+    """Encode any Python value into GCF tabular format.
+
+    Unlike encode() which handles the graph Payload type, encode_generic()
+    works on arbitrary dicts, lists, and primitives using GCF's tabular
+    encoding grammar.
+
+    Args:
+        data: Any Python value (dict, list, primitive, or None).
+
+    Returns:
+        GCF-formatted text string.
+    """
+    lines: list[str] = []
+    _encode_value(data, lines, depth=0)
+    return "\n".join(lines) + "\n" if lines else "\n"
+
+
+def _encode_value(value: Any, lines: list[str], depth: int) -> None:
+    """Dispatch encoding based on value type."""
+    if isinstance(value, dict):
+        _encode_dict(value, lines, depth)
+    elif isinstance(value, list):
+        _encode_array(value, "items", lines, depth)
+    else:
+        lines.append(_indent(depth) + _format_value(value))
+
+
+def _encode_dict(d: dict, lines: list[str], depth: int) -> None:
+    """Encode a dict into key=value pairs with section headers for nested values."""
+    prefix = _indent(depth)
+    for key, value in d.items():
+        if isinstance(value, list):
+            _encode_array(value, key, lines, depth)
+        elif isinstance(value, dict):
+            lines.append(f"{prefix}## {key}")
+            _encode_dict(value, lines, depth + 1)
+        else:
+            lines.append(f"{prefix}{key}={_format_value(value)}")
+
+
+def _encode_array(items: list, name: str, lines: list[str], depth: int) -> None:
+    """Encode a list, using tabular format for uniform dict lists."""
+    prefix = _indent(depth)
+
+    if not items:
+        lines.append(f"{prefix}## {name} [0]")
+        return
+
+    if _is_uniform_dict_list(items):
+        _encode_tabular(items, name, lines, depth)
+    else:
+        lines.append(f"{prefix}## {name} [{len(items)}]")
+        for i, item in enumerate(items):
+            if isinstance(item, dict):
+                lines.append(f"{prefix}@{i}")
+                _encode_dict(item, lines, depth + 1)
+            else:
+                lines.append(f"{prefix}@{i} {_format_value(item)}")
+
+
+def _encode_tabular(items: list[dict], name: str, lines: list[str], depth: int) -> None:
+    """Encode a uniform list of dicts as a tabular section."""
+    prefix = _indent(depth)
+
+    # Collect all keys from the first item to determine field order.
+    all_keys = list(items[0].keys())
+    primitive_fields = [k for k in all_keys if not isinstance(items[0][k], (dict, list))]
+    nested_fields = [k for k in all_keys if isinstance(items[0][k], (dict, list))]
+
+    # Header with field names (primitive fields only in the column spec).
+    header = f"{prefix}## {name} [{len(items)}]{{{','.join(primitive_fields)}}}"
+    lines.append(header)
+
+    for i, item in enumerate(items):
+        row_values = [_format_value(item.get(f)) for f in primitive_fields]
+        row_str = "|".join(row_values)
+
+        if nested_fields:
+            lines.append(f"{prefix}@{i} {row_str}")
+            inner_prefix = _indent(depth + 1)
+            for nk in nested_fields:
+                nv = item.get(nk)
+                if isinstance(nv, list):
+                    _encode_array(nv, nk, lines, depth + 1)
+                elif isinstance(nv, dict):
+                    lines.append(f"{inner_prefix}## {nk}")
+                    _encode_dict(nv, lines, depth + 2)
+        else:
+            lines.append(f"{prefix}{row_str}")
+
+
+def _is_uniform_dict_list(items: list) -> bool:
+    """Check whether a list contains uniform dicts (same keys across items).
+
+    Samples up to the first 5 items. Considers the list uniform if key
+    overlap is at least 70% between consecutive items and the first item.
+    """
+    if not items or not isinstance(items[0], dict):
+        return False
+
+    sample = items[:5]
+    if not all(isinstance(item, dict) for item in sample):
+        return False
+
+    if not sample:
+        return False
+
+    reference_keys = set(sample[0].keys())
+    if not reference_keys:
+        return False
+
+    for item in sample[1:]:
+        item_keys = set(item.keys())
+        union = reference_keys | item_keys
+        intersection = reference_keys & item_keys
+        if not union or len(intersection) / len(union) < 0.7:
+            return False
+
+    return True
+
+
+def _format_value(value: Any) -> str:
+    """Format a single value for GCF output.
+
+    None becomes "-". Booleans are lowercased. Numbers are unquoted.
+    Strings containing "|" or newlines are quoted. Everything else is direct.
+    """
+    if value is None:
+        return "-"
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, (int, float)):
+        return str(value)
+    s = str(value)
+    if "|" in s or "\n" in s or s == "":
+        escaped = s.replace("\\", "\\\\").replace('"', '\\"')
+        return f'"{escaped}"'
+    return s
+
+
+def _indent(depth: int) -> str:
+    """Return indentation string for the given depth (2 spaces per level)."""
+    return "  " * depth

gcf/session.py

@@ -1,5 +1,7 @@
 """Session-based deduplication for GCF encoding."""
 
+from __future__ import annotations
+
 import threading
 
 from .constants import KIND_ABBREV

gcf/types.py

@@ -1,5 +1,7 @@
 """Data types for GCF payloads."""
 
+from __future__ import annotations
+
 from dataclasses import dataclass, field
 
 

{gcf_python-0.1.0.dist-info → gcf_python-0.1.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gcf-python
-Version: 0.1.0
+Version: 0.1.2
 Summary: Python implementation of GCF (Graph Compact Format): token-optimized wire format for LLM tool responses
 Project-URL: Homepage, https://github.com/blackwell-systems/gcf-python
 Project-URL: Documentation, https://blackwell-systems.github.io/gcf/
@@ -37,7 +37,7 @@ Python implementation of [GCF (Graph Compact Format)](https://github.com/blackwe
 ## Install
 
 ```
-pip install gcf-py
+pip install gcf-python
 ```
 
 Zero dependencies. Pure Python. Python 3.9+. Includes CLI.
@@ -139,11 +139,36 @@ output = encode_delta(delta)
 
 81.2% savings on re-queries where the pack changed slightly.
 
+## Generic Encoding
+
+Encode any Python value (not just graph payloads) into GCF tabular format:
+
+```python
+from gcf import encode_generic
+
+output = encode_generic({
+    "employees": [
+        {"id": 1, "name": "Alice", "department": "Engineering", "salary": 95000},
+        {"id": 2, "name": "Bob", "department": "Sales", "salary": 72000},
+    ],
+})
+```
+
+Output:
+```
+## employees [2]{id,name,department,salary}
+1|Alice|Engineering|95000
+2|Bob|Sales|72000
+```
+
+Works on dicts, lists, and primitives. Lists of uniform dicts get tabular rows. Nested dicts use `## key` section headers.
+
 ## API
 
 | Function | Description |
 |----------|-------------|
-| `encode(p: Payload) -> str` | Encode a payload to GCF text |
+| `encode(p: Payload) -> str` | Encode a graph payload to GCF text |
+| `encode_generic(data: Any) -> str` | Encode any value to GCF tabular format |
 | `decode(input_text: str) -> Payload` | Parse GCF text back to a Payload |
 | `encode_with_session(p: Payload, s: Session) -> str` | Encode with session deduplication |
 | `encode_delta(d: DeltaPayload) -> str` | Encode a delta (added/removed only) |

gcf_python-0.1.2.dist-info/RECORD

@@ -0,0 +1,14 @@
+gcf/__init__.py,sha256=bhnoIK9Qk7tMgWX_3q6HFvE3w55yw5rw2jyFHx7Bqx8,1541
+gcf/cli.py,sha256=2hSTBqiYcn1_EgGXuO65MHiEGh0C4DRMvspTd2zUaso,4258
+gcf/constants.py,sha256=cmZ8YJSOB0im_eyfN8v4UvrLpBC6Fuf4cfcKZGbutxY,638
+gcf/decode.py,sha256=gkBW9fmcurQ9bfcDXbaCOWemMmljo_MiZMj3-1rYvsw,5198
+gcf/delta.py,sha256=xU0ujtSq1iF7yU8yk_WNQKh8iove-WUV_nKSuvW1XVk,1656
+gcf/encode.py,sha256=WZCRv1Vj2PDTYvBgv__2P8GHh8FapxfAZmt5zo0k9Jc,2700
+gcf/generic.py,sha256=N4rhf3JAdQHcWA9HEbTPxWnMfvdac6oZzQHQSnZdXdE,5105
+gcf/session.py,sha256=F8OTJCMRMCY7Yzcvd7aU8wlbER0LZAMUcB4W9kHeSq4,4508
+gcf/types.py,sha256=AWm-LQoSqLHAYtEjcAxWQZqJ4JXqNreLUKO2mJFgNMA,1465
+gcf_python-0.1.2.dist-info/METADATA,sha256=FumNV9D2FUZfkUor89SPotIgLTo2QXmUhT9RHZc4DYk,7320
+gcf_python-0.1.2.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+gcf_python-0.1.2.dist-info/entry_points.txt,sha256=aFT6gqlkh8iGfM8cblE-LUMxHH08_v71IIoZtDdRIVA,37
+gcf_python-0.1.2.dist-info/licenses/LICENSE,sha256=txSvg3E4LugiB7MOOTci6WKd6wMOrOJTvaITeFJ2SgU,1074
+gcf_python-0.1.2.dist-info/RECORD,,

gcf_python-0.1.0.dist-info/RECORD

@@ -1,13 +0,0 @@
-gcf/__init__.py,sha256=XzxWfa__EBT3GqV6nAC74WX6EpNFO1Qg-YsnCg1ROQQ,1483
-gcf/cli.py,sha256=2hSTBqiYcn1_EgGXuO65MHiEGh0C4DRMvspTd2zUaso,4258
-gcf/constants.py,sha256=cmZ8YJSOB0im_eyfN8v4UvrLpBC6Fuf4cfcKZGbutxY,638
-gcf/decode.py,sha256=kdbYrx0WzozDw-PhPieBv6h_a0B995crCEK-CJoK59c,5162
-gcf/delta.py,sha256=xU0ujtSq1iF7yU8yk_WNQKh8iove-WUV_nKSuvW1XVk,1656
-gcf/encode.py,sha256=KYGxFHy5LJoOF0IQblAm78bLL5uFf5iQMtrnyuuQXCA,2664
-gcf/session.py,sha256=jVfpEK4euCn7apVm-sb0OyycUJrFUPaAUEWCT0d2c14,4472
-gcf/types.py,sha256=yZL2knyFYguh2ex1ZXO1VwD4NEY4jvC-DL6-R-i-x0U,1429
-gcf_python-0.1.0.dist-info/METADATA,sha256=hfE2L2HB1wxrBi8mRYHTD-KiViqVZ-4omjQNdT-ZtNA,6646
-gcf_python-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
-gcf_python-0.1.0.dist-info/entry_points.txt,sha256=aFT6gqlkh8iGfM8cblE-LUMxHH08_v71IIoZtDdRIVA,37
-gcf_python-0.1.0.dist-info/licenses/LICENSE,sha256=txSvg3E4LugiB7MOOTci6WKd6wMOrOJTvaITeFJ2SgU,1074
-gcf_python-0.1.0.dist-info/RECORD,,