software-dlc-tile 0.2.2__tar.gz

software_dlc_tile-0.2.2/.gitignore

@@ -0,0 +1,14 @@
+node_modules/
+.pnpm-store/
+.npm-cache/
+dist/
+coverage/
+.turbo/
+artifacts/
+.env.local
+.DS_Store
+*.log
+__pycache__/
+*.egg-info/
+.venv/
+.pytest_cache/

software_dlc_tile-0.2.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SoftwareDLC
+
+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.

software_dlc_tile-0.2.2/PKG-INFO

@@ -0,0 +1,51 @@
+Metadata-Version: 2.4
+Name: software-dlc-tile
+Version: 0.2.2
+Summary: Python helpers for first-class TILE prompt tables.
+Project-URL: Homepage, https://github.com/SoftwareDLC/tile#readme
+Project-URL: Repository, https://github.com/SoftwareDLC/tile
+Project-URL: Issues, https://github.com/SoftwareDLC/tile/issues
+Author: SoftwareDLC
+License-Expression: MIT
+License-File: LICENSE
+Keywords: json,llm,prompt-engineering,prompt-optimization,structured-data,tile
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Text Processing
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# software-dlc-tile
+
+Python helpers for first-class TILE prompt tables.
+
+This package is an incubating Python surface for `@software-dlc/tile`. It starts
+with first-class TILE because that is the smallest useful API for Python, data,
+and LLM users who already have structured rows and want compact prompt context.
+
+```python
+from software_dlc_tile import encode_first_class_tables_to_tile
+
+tile = encode_first_class_tables_to_tile({
+    "delimiter": "pipe",
+    "tables": [
+        {
+            "id": "packages",
+            "columns": ["name", {"embedded_columns": ["dependency"]}],
+            "rows": [
+                ["fastapi", "pydantic"],
+                ["", "starlette"],
+            ],
+        }
+    ],
+})
+```
+
+This first Python package does not yet implement lossless JSON-to-TILE encoding
+or TILE-to-JSON decoding. Those should come after shared conformance coverage is
+expanded for the full wire format.

software_dlc_tile-0.2.2/README.md

@@ -0,0 +1,29 @@
+# software-dlc-tile
+
+Python helpers for first-class TILE prompt tables.
+
+This package is an incubating Python surface for `@software-dlc/tile`. It starts
+with first-class TILE because that is the smallest useful API for Python, data,
+and LLM users who already have structured rows and want compact prompt context.
+
+```python
+from software_dlc_tile import encode_first_class_tables_to_tile
+
+tile = encode_first_class_tables_to_tile({
+    "delimiter": "pipe",
+    "tables": [
+        {
+            "id": "packages",
+            "columns": ["name", {"embedded_columns": ["dependency"]}],
+            "rows": [
+                ["fastapi", "pydantic"],
+                ["", "starlette"],
+            ],
+        }
+    ],
+})
+```
+
+This first Python package does not yet implement lossless JSON-to-TILE encoding
+or TILE-to-JSON decoding. Those should come after shared conformance coverage is
+expanded for the full wire format.

software_dlc_tile-0.2.2/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["hatchling >= 1.26"]
+build-backend = "hatchling.build"
+
+[project]
+name = "software-dlc-tile"
+version = "0.2.2"
+description = "Python helpers for first-class TILE prompt tables."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+  { name = "SoftwareDLC" }
+]
+keywords = [
+  "json",
+  "llm",
+  "prompt-engineering",
+  "prompt-optimization",
+  "structured-data",
+  "tile"
+]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Topic :: Text Processing"
+]
+
+[project.urls]
+Homepage = "https://github.com/SoftwareDLC/tile#readme"
+Repository = "https://github.com/SoftwareDLC/tile"
+Issues = "https://github.com/SoftwareDLC/tile/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/software_dlc_tile"]

software_dlc_tile-0.2.2/src/software_dlc_tile/__init__.py

@@ -0,0 +1,10 @@
+from .first_class import encode_first_class_tables_to_tile
+from .text import escape_tile_text, resolve_tile_delimiter, unescape_tile_text
+
+__all__ = [
+    "encode_first_class_tables_to_tile",
+    "escape_tile_text",
+    "resolve_tile_delimiter",
+    "unescape_tile_text",
+]
+

software_dlc_tile-0.2.2/src/software_dlc_tile/first_class.py

@@ -0,0 +1,176 @@
+from __future__ import annotations
+
+import math
+from collections.abc import Mapping, Sequence
+from typing import Any
+
+from .text import escape_tile_text, resolve_tile_delimiter
+
+
+JsonTileFirstClassCell = str | int | float | bool | None
+
+
+def encode_first_class_tables_to_tile(document: Mapping[str, Any]) -> str:
+    delimiter = resolve_tile_delimiter(str(document.get("delimiter", "tab")))
+    tables = document.get("tables")
+    if not isinstance(tables, Sequence) or isinstance(tables, (str, bytes)):
+        raise TypeError("First-class TILE document requires a tables sequence")
+
+    return "\n\n".join(_encode_first_class_table(table, delimiter) for table in tables)
+
+
+def _encode_first_class_table(table: Any, delimiter: str) -> str:
+    if not isinstance(table, Mapping):
+        raise TypeError("First-class TILE tables must be mappings")
+
+    columns = table.get("columns")
+    rows = table.get("rows")
+    if not isinstance(columns, Sequence) or isinstance(columns, (str, bytes)):
+        raise TypeError("First-class TILE table columns must be a sequence")
+
+    if not isinstance(rows, Sequence) or isinstance(rows, (str, bytes)):
+        raise TypeError("First-class TILE table rows must be a sequence")
+
+    lines = [
+        _encode_first_class_table_definition(table, delimiter),
+        delimiter.join(_format_first_class_table_column(column, delimiter) for column in columns),
+    ]
+
+    for row in rows:
+        if not isinstance(row, Sequence) or isinstance(row, (str, bytes)):
+            raise TypeError("First-class TILE table rows must contain cell sequences")
+        lines.append(delimiter.join(_format_first_class_table_cell(cell, delimiter) for cell in row))
+
+    return "\n".join(lines)
+
+
+def _format_first_class_table_column(column: Any, delimiter: str) -> str:
+    if isinstance(column, str):
+        return escape_tile_text(column, delimiter)
+
+    if not isinstance(column, Mapping):
+        raise TypeError("First-class TILE columns must be strings or embedded column mappings")
+
+    embedded_columns = column.get("embedded_columns")
+    if (
+        not isinstance(embedded_columns, Sequence)
+        or isinstance(embedded_columns, (str, bytes))
+        or len(embedded_columns) == 0
+    ):
+        raise ValueError("First-class TILE embedded column groups cannot be empty")
+
+    join_delimiter = ";" if delimiter == "," else ","
+    return (
+        "["
+        + join_delimiter.join(
+            _format_first_class_embedded_column_name(embedded_column, delimiter)
+            for embedded_column in embedded_columns
+        )
+        + "]"
+    )
+
+
+def _format_first_class_embedded_column_name(column: Any, delimiter: str) -> str:
+    if not isinstance(column, str):
+        raise TypeError("First-class TILE embedded column names must be strings")
+
+    if "[" in column or "]" in column or (delimiter != "," and "," in column):
+        raise ValueError(
+            "First-class TILE embedded column names cannot contain comma or brackets"
+        )
+
+    return escape_tile_text(column, delimiter)
+
+
+def _encode_first_class_table_definition(table: Mapping[str, Any], delimiter: str) -> str:
+    table_id = table.get("id")
+    if not isinstance(table_id, str):
+        raise TypeError("First-class TILE table id must be a string")
+
+    definition_parts = [table_id]
+    kind = table.get("kind")
+    path = table.get("path")
+
+    if kind is not None and not isinstance(kind, str):
+        raise TypeError("First-class TILE table kind must be a string")
+
+    if path is not None and not isinstance(path, str):
+        raise TypeError("First-class TILE table path must be a string")
+
+    if kind or path:
+        definition_parts.append(kind or "")
+
+    if path:
+        definition_parts.append(path)
+
+    return delimiter.join(escape_tile_text(part, delimiter) for part in definition_parts)
+
+
+def _format_first_class_table_cell(cell: Any, delimiter: str) -> str:
+    if cell is None:
+        return ""
+
+    return escape_tile_text(_format_cell_value(cell), delimiter)
+
+
+def _format_cell_value(cell: JsonTileFirstClassCell) -> str:
+    if isinstance(cell, bool):
+        return "true" if cell else "false"
+
+    if isinstance(cell, str):
+        return cell
+
+    if isinstance(cell, int):
+        return str(cell)
+
+    if isinstance(cell, float):
+        if not math.isfinite(cell):
+            raise ValueError("First-class TILE only supports finite numbers")
+        return _format_javascript_number(cell)
+
+    raise TypeError("First-class TILE cells must be strings, numbers, booleans, or None")
+
+
+def _format_javascript_number(value: float) -> str:
+    if value == 0:
+        return "0"
+
+    sign = "-" if value < 0 else ""
+    digits, decimal_exponent = _decimal_parts(abs(value))
+    digit_count = len(digits)
+
+    if digit_count <= decimal_exponent <= 21:
+        return f"{sign}{digits}{'0' * (decimal_exponent - digit_count)}"
+
+    if 0 < decimal_exponent <= 21:
+        return f"{sign}{digits[:decimal_exponent]}.{digits[decimal_exponent:]}"
+
+    if -6 < decimal_exponent <= 0:
+        return f"{sign}0.{'0' * (-decimal_exponent)}{digits}"
+
+    mantissa = digits if digit_count == 1 else f"{digits[0]}.{digits[1:]}"
+    exponent = decimal_exponent - 1
+    exponent_sign = "+" if exponent >= 0 else ""
+    return f"{sign}{mantissa}e{exponent_sign}{exponent}"
+
+
+def _decimal_parts(value: float) -> tuple[str, int]:
+    text = repr(value)
+    if "e" in text or "E" in text:
+        mantissa_text, exponent_text = text.lower().split("e", 1)
+        exponent = int(exponent_text)
+        integer_part, _, fractional_part = mantissa_text.partition(".")
+        digits = f"{integer_part}{fractional_part}".lstrip("0")
+        return digits, exponent + len(integer_part)
+
+    integer_part, _, fractional_part = text.partition(".")
+    if integer_part == "0":
+        trimmed_fractional_part = fractional_part.rstrip("0")
+        leading_zero_count = len(trimmed_fractional_part) - len(
+            trimmed_fractional_part.lstrip("0")
+        )
+        digits = trimmed_fractional_part.lstrip("0")
+        return digits or "0", -leading_zero_count
+
+    digits = f"{integer_part}{fractional_part}".rstrip("0")
+    return digits, len(integer_part)

software_dlc_tile-0.2.2/src/software_dlc_tile/text.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+
+def escape_tile_text(value: str, delimiter: str = "\t") -> str:
+    result: list[str] = []
+
+    for char in value:
+        if char == "\\":
+            result.append("\\\\")
+        elif char == "\t":
+            result.append("\\t")
+        elif char == "\n":
+            result.append("\\n")
+        elif char == "\r":
+            result.append("\\r")
+        elif char == " " and delimiter == " ":
+            result.append("\\s")
+        elif char == delimiter and delimiter != "\t":
+            result.append(f"\\{char}")
+        else:
+            result.append(char)
+
+    return "".join(result)
+
+
+def unescape_tile_text(value: str) -> str:
+    result: list[str] = []
+    index = 0
+
+    while index < len(value):
+        char = value[index]
+        if char != "\\":
+            result.append(char)
+            index += 1
+            continue
+
+        if index + 1 >= len(value):
+            raise ValueError("Invalid TILE escape: trailing backslash")
+
+        escaped_char = value[index + 1]
+        if escaped_char == "t":
+            result.append("\t")
+        elif escaped_char == "n":
+            result.append("\n")
+        elif escaped_char == "r":
+            result.append("\r")
+        elif escaped_char == "\\":
+            result.append("\\")
+        elif escaped_char == "s":
+            result.append(" ")
+        elif escaped_char == ",":
+            result.append(",")
+        elif escaped_char == "|":
+            result.append("|")
+        elif escaped_char == "@":
+            result.append("@")
+        elif escaped_char == ":":
+            result.append(":")
+        else:
+            raise ValueError(f"Invalid TILE escape: \\{escaped_char}")
+
+        index += 2
+
+    return "".join(result)
+
+
+def resolve_tile_delimiter(delimiter: str) -> str:
+    if delimiter == "comma":
+        return ","
+
+    if delimiter == "pipe":
+        return "|"
+
+    if delimiter == "space":
+        return " "
+
+    return "\t"

software_dlc_tile-0.2.2/tests/test_first_class.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+import json
+import math
+import pathlib
+import sys
+import unittest
+
+ROOT_DIR = pathlib.Path(__file__).resolve().parents[3]
+sys.path.insert(0, str(ROOT_DIR / "packages/python/src"))
+
+from software_dlc_tile import (  # noqa: E402
+    encode_first_class_tables_to_tile,
+    escape_tile_text,
+    unescape_tile_text,
+)
+
+
+class FirstClassTileTests(unittest.TestCase):
+    def test_first_class_conformance_cases(self) -> None:
+        cases_path = ROOT_DIR / "conformance/first-class-cases.json"
+        cases = json.loads(cases_path.read_text(encoding="utf8"))
+
+        for case in cases:
+            with self.subTest(case["id"]):
+                self.assertEqual(
+                    encode_first_class_tables_to_tile(case["document"]),
+                    case["expected"],
+                )
+
+    def test_rejects_ambiguous_embedded_column_names(self) -> None:
+        with self.assertRaisesRegex(ValueError, "comma or brackets"):
+            encode_first_class_tables_to_tile(
+                {
+                    "tables": [
+                        {
+                            "id": "nodes",
+                            "columns": [{"embedded_columns": ["edge,id"]}],
+                            "rows": [],
+                        }
+                    ]
+                }
+            )
+
+    def test_rejects_non_finite_numbers(self) -> None:
+        with self.assertRaisesRegex(ValueError, "finite numbers"):
+            encode_first_class_tables_to_tile(
+                {
+                    "tables": [
+                        {
+                            "id": "metrics",
+                            "columns": ["value"],
+                            "rows": [[math.inf]],
+                        }
+                    ]
+                }
+            )
+
+    def test_tile_text_escaping_round_trip(self) -> None:
+        escaped = escape_tile_text("a\tb\nc\\d")
+        self.assertEqual(escaped, "a\\tb\\nc\\\\d")
+        self.assertEqual(unescape_tile_text(escaped), "a\tb\nc\\d")
+
+        with self.assertRaisesRegex(ValueError, "Invalid TILE escape"):
+            unescape_tile_text("bad\\x")
+
+
+if __name__ == "__main__":
+    unittest.main()