lionherd-core 1.0.0a3__py3-none-any.whl

lionherd_core/libs/schema_handlers/_typescript.py

@@ -0,0 +1,153 @@
+# Copyright (c) 2025, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+
+def _type_map(json_type: str) -> str:
+    """Map JSON Schema types to TypeScript-like types."""
+    mapping = {
+        "string": "string",
+        "integer": "int",
+        "number": "float",
+        "boolean": "bool",
+        "array": "array",  # Will be handled specially
+        "object": "object",
+        "null": "null",
+    }
+    return mapping.get(json_type, json_type)
+
+
+def _format_enum_union(enum_values: list) -> str:
+    """Format enum values as TypeScript union of literals."""
+    formatted = []
+    for val in enum_values:
+        if isinstance(val, str):
+            formatted.append(f'"{val}"')
+        elif val is None:
+            formatted.append("null")
+        else:
+            formatted.append(str(val))
+    return " | ".join(formatted)
+
+
+def _extract_type_signature(field_spec: dict, required: bool) -> tuple[str, bool]:
+    """Extract TypeScript-style type signature from JSON Schema field."""
+    # Handle enums first (most specific)
+    if "enum" in field_spec:
+        type_sig = _format_enum_union(field_spec["enum"])
+        # Check if enum includes null
+        has_null = None in field_spec["enum"]
+        is_optional = not required or has_null
+        return type_sig, is_optional
+
+    # Handle anyOf (unions)
+    if "anyOf" in field_spec:
+        options = field_spec["anyOf"]
+        type_parts = []
+        has_null = False
+
+        for opt in options:
+            if opt.get("type") == "null":
+                has_null = True
+                continue
+
+            if "type" in opt:
+                if opt["type"] == "array" and "items" in opt:
+                    item_type = _type_map(opt["items"].get("type", "any"))
+                    if "$ref" in opt["items"]:
+                        item_type = opt["items"]["$ref"].split("/")[-1]
+                    type_parts.append(f"{item_type}[]")
+                else:
+                    type_parts.append(_type_map(opt["type"]))
+            elif "$ref" in opt:
+                ref_name = opt["$ref"].split("/")[-1]
+                type_parts.append(ref_name)
+            elif "enum" in opt:
+                type_parts.append(_format_enum_union(opt["enum"]))
+
+        if has_null:
+            type_parts.append("null")
+
+        type_sig = " | ".join(type_parts) if type_parts else "any"
+        is_optional = not required or has_null
+        return type_sig, is_optional
+
+    # Handle arrays
+    if "type" in field_spec and field_spec["type"] == "array":
+        if "items" in field_spec:
+            items_spec = field_spec["items"]
+            if "type" in items_spec:
+                item_type = _type_map(items_spec["type"])
+            elif "$ref" in items_spec:
+                item_type = items_spec["$ref"].split("/")[-1]
+            elif "enum" in items_spec:
+                item_type = f"({_format_enum_union(items_spec['enum'])})"
+            else:
+                item_type = "any"
+        else:
+            item_type = "any"
+        type_sig = f"{item_type}[]"
+        is_optional = not required
+        return type_sig, is_optional
+
+    # Handle $ref
+    if "$ref" in field_spec:
+        ref_name = field_spec["$ref"].split("/")[-1]
+        is_optional = not required
+        return ref_name, is_optional
+
+    # Handle simple types
+    if "type" in field_spec:
+        base_type = field_spec["type"]
+        # Handle nullable simple types (type? suffix from simplification)
+        if isinstance(base_type, str) and base_type.endswith("?"):
+            type_sig = _type_map(base_type[:-1])
+            is_optional = True
+        else:
+            type_sig = _type_map(base_type)
+            is_optional = not required
+        return type_sig, is_optional
+
+    # Fallback
+    return "any", not required
+
+
+def typescript_schema(schema: dict, indent: int = 0) -> str:
+    """Convert JSON Schema to TypeScript-style notation for optimal LLM comprehension."""
+    lines = []
+    prefix = "  " * indent
+
+    if "properties" not in schema:
+        return ""
+
+    required_fields = set(schema.get("required", []))
+
+    for field_name, field_spec in schema["properties"].items():
+        is_required = field_name in required_fields
+
+        # Extract type signature
+        type_sig, is_optional = _extract_type_signature(field_spec, is_required)
+
+        # Add default value if present
+        default_str = ""
+        if "default" in field_spec:
+            default_val = field_spec["default"]
+            if isinstance(default_val, str):
+                default_str = f' = "{default_val}"'
+            elif default_val is None:
+                default_str = " = null"
+            elif isinstance(default_val, bool):
+                default_str = f" = {'true' if default_val else 'false'}"
+            else:
+                default_str = f" = {default_val}"
+
+        # Build field definition
+        optional_marker = "?" if is_optional else ""
+        field_def = f"{prefix}{field_name}{optional_marker}: {type_sig}{default_str}"
+
+        # Add description if present
+        if field_spec.get("description"):
+            field_def += f" - {field_spec['description']}"
+
+        lines.append(field_def)
+
+    return "\n".join(lines)

lionherd_core/libs/string_handlers/__init__.py

@@ -0,0 +1,15 @@
+# Copyright (c) 2025, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+from ._extract_json import extract_json
+from ._fuzzy_json import fuzzy_json
+from ._string_similarity import SimilarityAlgo, string_similarity
+from ._to_num import to_num
+
+__all__ = (
+    "SimilarityAlgo",
+    "extract_json",
+    "fuzzy_json",
+    "string_similarity",
+    "to_num",
+)

lionherd_core/libs/string_handlers/_extract_json.py

@@ -0,0 +1,65 @@
+# Copyright (c) 2025, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+import contextlib
+import re
+from typing import Any
+
+import orjson
+
+from ._fuzzy_json import fuzzy_json
+
+# Precompile the regex for extracting JSON code blocks
+_JSON_BLOCK_PATTERN = re.compile(r"```json\s*(.*?)\s*```", re.DOTALL)
+
+
+def extract_json(
+    input_data: str | list[str],
+    /,
+    *,
+    fuzzy_parse: bool = False,
+    return_one_if_single: bool = True,
+) -> Any | list[Any]:
+    """Extract and parse JSON content from a string or markdown code blocks.
+    Attempts direct JSON parsing first. If that fails, looks for JSON content
+    within markdown code blocks denoted by ```json.
+
+    Args:
+        input_data (str | list[str]): The input string or list of strings to parse.
+        fuzzy_parse (bool): If True, attempts fuzzy JSON parsing on failed attempts.
+        return_one_if_single (bool): If True and only one JSON object is found,
+            returns a dict instead of a list with one dict.
+    """
+
+    # If input_data is a list, join into a single string
+    input_str = "\n".join(input_data) if isinstance(input_data, list) else input_data
+
+    # 1. Try direct parsing
+
+    with contextlib.suppress(Exception):
+        if fuzzy_parse:
+            return fuzzy_json(input_str)
+        return orjson.loads(input_str)
+
+    # 2. Attempt extracting JSON blocks from markdown
+    matches = _JSON_BLOCK_PATTERN.findall(input_str)
+    if not matches:
+        return []
+
+    # If only one match, return single dict; if multiple, return list of dicts
+    if return_one_if_single and len(matches) == 1:
+        data_str = matches[0]
+        with contextlib.suppress(Exception):
+            if fuzzy_parse:
+                return fuzzy_json(data_str)
+            return orjson.loads(data_str)
+        return []
+
+    # Multiple matches
+    results: list[Any] = []
+    for m in matches:
+        with contextlib.suppress(Exception):
+            parsed = fuzzy_json(m) if fuzzy_parse else orjson.loads(m)
+            # Append valid JSON (dicts, lists, or primitives)
+            results.append(parsed)
+    return results

lionherd_core/libs/string_handlers/_fuzzy_json.py

@@ -0,0 +1,103 @@
+# Copyright (c) 2025, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+import contextlib
+import re
+from typing import Any
+
+import orjson
+
+
+def fuzzy_json(str_to_parse: str, /) -> dict[str, Any] | list[dict[str, Any]]:
+    """Parse JSON string with fuzzy error correction (quotes, spacing, brackets)."""
+    _check_valid_str(str_to_parse)
+
+    # 1. Direct attempt
+    with contextlib.suppress(orjson.JSONDecodeError):
+        return orjson.loads(str_to_parse)
+
+    # 2. Try cleaning: replace single quotes with double and normalize
+    cleaned = _clean_json_string(str_to_parse.replace("'", '"'))
+    with contextlib.suppress(orjson.JSONDecodeError):
+        return orjson.loads(cleaned)
+
+    # 3. Try fixing brackets
+    fixed = fix_json_string(cleaned)
+    with contextlib.suppress(orjson.JSONDecodeError):
+        return orjson.loads(fixed)
+
+    # If all attempts fail
+    raise ValueError("Invalid JSON string")
+
+
+def _check_valid_str(str_to_parse: str, /):
+    if not isinstance(str_to_parse, str):
+        raise TypeError("Input must be a string")
+    if not str_to_parse.strip():
+        raise ValueError("Input string is empty")
+
+
+def _clean_json_string(s: str) -> str:
+    """Basic normalization: replace unescaped single quotes, trim spaces, ensure keys are quoted."""
+    # Replace unescaped single quotes with double quotes
+    # '(?<!\\)'" means a single quote not preceded by a backslash
+    s = re.sub(r"(?<!\\)'", '"', s)
+    # Collapse multiple whitespaces
+    s = re.sub(r"\s+", " ", s)
+    # Remove trailing commas before closing brackets/braces
+    s = re.sub(r",\s*([}\]])", r"\1", s)
+    # Ensure keys are quoted
+    # This attempts to find patterns like { key: value } and turn them into {"key": value}
+    s = re.sub(r'([{,])\s*([^"\s]+)\s*:', r'\1"\2":', s)
+    return s.strip()
+
+
+def fix_json_string(str_to_parse: str, /) -> str:
+    """Fix JSON string by balancing unmatched brackets."""
+    if not str_to_parse:
+        raise ValueError("Input string is empty")
+
+    brackets = {"{": "}", "[": "]"}
+    open_brackets = []
+    pos = 0
+    length = len(str_to_parse)
+
+    while pos < length:
+        char = str_to_parse[pos]
+
+        if char == "\\":
+            pos += 2  # Skip escaped chars
+            continue
+
+        if char == '"':
+            pos += 1
+            # skip string content
+            while pos < length:
+                if str_to_parse[pos] == "\\":
+                    pos += 2
+                    continue
+                if str_to_parse[pos] == '"':
+                    pos += 1
+                    break
+                pos += 1
+            continue
+
+        if char in brackets:
+            open_brackets.append(brackets[char])
+        elif char in brackets.values():
+            if not open_brackets:
+                # Extra closing bracket
+                # Better to raise error than guess
+                raise ValueError("Extra closing bracket found.")
+            if open_brackets[-1] != char:
+                # Mismatched bracket
+                raise ValueError("Mismatched brackets.")
+            open_brackets.pop()
+
+        pos += 1
+
+    # Add missing closing brackets if any
+    if open_brackets:
+        str_to_parse += "".join(reversed(open_brackets))
+
+    return str_to_parse

lionherd_core/libs/string_handlers/_string_similarity.py

@@ -0,0 +1,347 @@
+# Copyright (c) 2025, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Literal
+
+from lionherd_core.types.base import Enum
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+
+__all__ = ("SimilarityAlgo", "string_similarity")
+
+
+class SimilarityAlgo(Enum):
+    """String similarity algorithm names.
+
+    Provides type-safe enum values while maintaining string compatibility.
+    Use .allowed() to get all valid algorithm names as a tuple.
+    """
+
+    JARO_WINKLER = "jaro_winkler"
+    LEVENSHTEIN = "levenshtein"
+    SEQUENCE_MATCHER = "sequence_matcher"
+    HAMMING = "hamming"
+    COSINE = "cosine"
+
+
+def cosine_similarity(s1: str, s2: str) -> float:
+    """Calculate the cosine similarity between two strings.
+
+    Args:
+        s1: First input string
+        s2: Second input string
+
+    Returns:
+        float: Cosine similarity score between 0 and 1
+    """
+    if not s1 or not s2:
+        return 0.0
+
+    set1, set2 = set(s1), set(s2)
+    intersection = set1.intersection(set2)
+
+    return len(intersection) / ((len(set1) * len(set2)) ** 0.5)
+
+
+def hamming_similarity(s1: str, s2: str) -> float:
+    """Calculate the Hamming similarity between two strings.
+
+    The strings must be of equal length. Returns the proportion of positions
+    at which corresponding symbols are the same.
+
+    Args:
+        s1: First input string
+        s2: Second input string
+
+    Returns:
+        float: Hamming similarity score between 0 and 1
+    """
+    if not s1 or not s2 or len(s1) != len(s2):
+        return 0.0
+
+    matches = sum(c1 == c2 for c1, c2 in zip(s1, s2, strict=False))
+    return matches / len(s1)
+
+
+def jaro_distance(s: str, t: str) -> float:
+    """Calculate the Jaro distance between two strings.
+
+    Args:
+        s: First input string
+        t: Second input string
+
+    Returns:
+        float: Jaro distance score between 0 and 1
+    """
+    s_len = len(s)
+    t_len = len(t)
+
+    if s_len == 0 and t_len == 0:
+        return 1.0
+    elif s_len == 0 or t_len == 0:
+        return 0.0
+
+    match_distance = (max(s_len, t_len) // 2) - 1
+    match_distance = max(0, match_distance)  # Ensure non-negative
+
+    s_matches = [False] * s_len
+    t_matches = [False] * t_len
+
+    matches = 0
+    transpositions = 0
+
+    # Identify matches
+    for i in range(s_len):
+        start = max(0, i - match_distance)
+        end = min(i + match_distance + 1, t_len)
+
+        for j in range(start, end):
+            if t_matches[j] or s[i] != t[j]:
+                continue
+            s_matches[i] = t_matches[j] = True
+            matches += 1
+            break
+
+    if matches == 0:
+        return 0.0
+
+    # Count transpositions
+    k = 0
+    for i in range(s_len):
+        if not s_matches[i]:
+            continue
+        while not t_matches[k]:
+            k += 1
+        if s[i] != t[k]:
+            transpositions += 1
+        k += 1
+
+    transpositions //= 2
+
+    return (matches / s_len + matches / t_len + (matches - transpositions) / matches) / 3.0
+
+
+def jaro_winkler_similarity(s: str, t: str, scaling: float = 0.1) -> float:
+    """Calculate the Jaro-Winkler similarity between two strings.
+
+    Args:
+        s: First input string
+        t: Second input string
+        scaling: Scaling factor for common prefix adjustment
+
+    Returns:
+        float: Jaro-Winkler similarity score between 0 and 1
+
+    Raises:
+        ValueError: If scaling factor is not between 0 and 0.25
+    """
+    if not 0 <= scaling <= 0.25:
+        raise ValueError("Scaling factor must be between 0 and 0.25")
+
+    jaro_sim = jaro_distance(s, t)
+
+    # Find length of common prefix (up to 4 chars)
+    prefix_len = 0
+    for s_char, t_char in zip(s, t, strict=False):
+        if s_char != t_char:
+            break
+        prefix_len += 1
+        if prefix_len == 4:
+            break
+
+    return jaro_sim + (prefix_len * scaling * (1 - jaro_sim))
+
+
+def levenshtein_distance(a: str, b: str) -> int:
+    """Calculate the Levenshtein (edit) distance between two strings.
+
+    Args:
+        a: First input string
+        b: Second input string
+
+    Returns:
+        int: Minimum number of single-character edits needed to change one
+             string into the other
+    """
+    from itertools import product
+
+    if not a:
+        return len(b)
+    if not b:
+        return len(a)
+
+    m, n = len(a), len(b)
+    d = [[0] * (n + 1) for _ in range(m + 1)]
+
+    for i in range(m + 1):
+        d[i][0] = i
+    for j in range(n + 1):
+        d[0][j] = j
+
+    for i, j in product(range(1, m + 1), range(1, n + 1)):
+        cost = 0 if a[i - 1] == b[j - 1] else 1
+        d[i][j] = min(
+            d[i - 1][j] + 1,  # deletion
+            d[i][j - 1] + 1,  # insertion
+            d[i - 1][j - 1] + cost,  # substitution
+        )
+
+    return d[m][n]
+
+
+def levenshtein_similarity(s1: str, s2: str) -> float:
+    """Calculate the Levenshtein similarity between two strings.
+
+    Converts Levenshtein distance to a similarity score between 0 and 1.
+
+    Args:
+        s1: First input string
+        s2: Second input string
+
+    Returns:
+        float: Levenshtein similarity score between 0 and 1
+    """
+    if not s1 and not s2:
+        return 1.0
+    if not s1 or not s2:
+        return 0.0
+
+    distance = levenshtein_distance(s1, s2)
+    max_len = max(len(s1), len(s2))
+    return 1 - (distance / max_len)
+
+
+def sequence_matcher_similarity(s1: str, s2: str) -> float:
+    """Calculate similarity using Python's SequenceMatcher.
+
+    Args:
+        s1: First input string
+        s2: Second input string
+
+    Returns:
+        float: Similarity score between 0 and 1
+    """
+    from difflib import SequenceMatcher
+
+    return SequenceMatcher(None, s1, s2).ratio()
+
+
+# Map of available similarity algorithms
+SIMILARITY_ALGO_MAP = {
+    "jaro_winkler": jaro_winkler_similarity,
+    "levenshtein": levenshtein_similarity,
+    "sequence_matcher": sequence_matcher_similarity,
+    "hamming": hamming_similarity,
+    "cosine": cosine_similarity,
+}
+
+
+SIMILARITY_TYPE = Literal[
+    "jaro_winkler",
+    "levenshtein",
+    "sequence_matcher",
+    "hamming",
+    "cosine",
+]
+
+# Type alias for similarity functions
+SimilarityFunc = Callable[[str, str], float]
+
+
+@dataclass(frozen=True)
+class MatchResult:
+    """Represents a string matching result."""
+
+    word: str
+    score: float
+    index: int
+
+
+def string_similarity(
+    word: str,
+    correct_words: "Sequence[str]",
+    algorithm: SIMILARITY_TYPE | SimilarityAlgo | Callable[[str, str], float] = "jaro_winkler",
+    threshold: float = 0.0,
+    case_sensitive: bool = False,
+    return_most_similar: bool = False,
+) -> str | list[str] | None:
+    """Find similar strings using specified similarity algorithm.
+
+    Args:
+        word: The input string to find matches for
+        correct_words: List of strings to compare against
+        algorithm: Similarity algorithm to use
+        threshold: Minimum similarity score (0.0 to 1.0)
+        case_sensitive: Whether to consider case when matching
+        return_most_similar: Return only the most similar match
+
+    Returns:
+        Matching string(s) or None if no matches found
+
+    Raises:
+        ValueError: If correct_words is empty or threshold is invalid
+    """
+    if not correct_words:
+        raise ValueError("correct_words must not be empty")
+
+    if not 0.0 <= threshold <= 1.0:
+        raise ValueError("threshold must be between 0.0 and 1.0")
+
+    # Convert inputs to strings
+    compare_word = str(word)
+    original_words = [str(w) for w in correct_words]
+
+    # Handle case sensitivity
+    if not case_sensitive:
+        compare_word = compare_word.lower()
+        compare_words = [w.lower() for w in original_words]
+    else:
+        compare_words = original_words.copy()
+
+    # Get scoring function
+    algo_name: str | None = None
+    if isinstance(algorithm, SimilarityAlgo):
+        algo_name = algorithm.value
+        score_func = SIMILARITY_ALGO_MAP[algo_name]
+    elif isinstance(algorithm, str):
+        algo_name = algorithm
+        score_func = SIMILARITY_ALGO_MAP.get(algo_name)
+        if score_func is None:
+            raise ValueError(f"Unsupported algorithm: {algo_name}")
+    elif callable(algorithm):
+        score_func = algorithm
+    else:
+        raise ValueError("algorithm must be a string specifying a built-in algorithm or a callable")
+
+    # Calculate similarities
+    results = []
+    for idx, (orig_word, comp_word) in enumerate(zip(original_words, compare_words, strict=False)):
+        # Skip different length strings for hamming similarity
+        if algo_name == "hamming" and len(comp_word) != len(compare_word):
+            continue
+
+        score = score_func(compare_word, comp_word)  # type: ignore[operator]
+        if score >= threshold:
+            results.append(MatchResult(orig_word, score, idx))
+
+    # Return None if no matches
+    if not results:
+        return None
+
+    # Sort by score (descending) and index (ascending) for stable ordering
+    results.sort(key=lambda x: (-x.score, x.index))
+
+    # Filter exact matches for case sensitive comparisons
+    if case_sensitive:
+        max_score = results[0].score
+        results = [r for r in results if r.score == max_score]
+
+    # Return results
+    if return_most_similar:
+        return results[0].word
+
+    return [r.word for r in results]