taghound 0.2.0__tar.gz

taghound-0.2.0/LICENSE

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

taghound-0.2.0/PKG-INFO

@@ -0,0 +1,184 @@
+Metadata-Version: 2.4
+Name: taghound
+Version: 0.2.0
+Summary: TagHound: A Python library for managing and evaluating tag rules using scalar and vector operations. Supports YAML and JSON rule loading.
+Keywords: tags,rules,YAML,JSON,Python
+Author: Roman Zagrebnev
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: OS Independent
+Classifier: Typing :: Typed
+Requires-Dist: pyyaml>=6.0.2
+Requires-Dist: pandas>=2.2.3,<3
+Requires-Python: >=3.11
+Project-URL: Homepage, https://github.com/rzagreb/TagHound
+Project-URL: Repository, https://github.com/rzagreb/TagHound
+Project-URL: Documentation, https://github.com/rzagreb/TagHound#readme
+Project-URL: Changelog, https://github.com/rzagreb/TagHound/blob/main/CHANGELOG.md
+Description-Content-Type: text/markdown
+
+# TagHound
+
+Declarative tagging for Python: write matching rules in YAML or JSON, and TagHound attaches tags to your dicts or whole pandas DataFrames.
+
+Rules stay readable and editable by non-technical users, while your pipeline code stays a one-liner. Typical uses:
+
+- **Categorize bank transactions** — regex rules on merchant strings turn a CSV export into budget categories, no ML training required
+- **Triage tickets and log events** — keyword and threshold rules attach routing tags (severity, team, topic) to each incoming record
+- **Enrich scraped datasets** — bulk-tag job postings or product listings in a pandas pipeline, then rank matches by rule weights
+
+## Installation
+
+Requires Python 3.11+.
+
+```bash
+pip install taghound
+```
+
+Latest from source: `pip install git+https://github.com/rzagreb/TagHound.git`
+
+## Quick start
+
+Create `rules.yml`:
+
+```yaml
+- id: food/coffee
+  label: Coffee
+  weight: 3
+  and:
+    - key: merchant
+      op: "~"
+      value: starbucks|blue bottle
+
+- id: alerts/big-purchase
+  and:
+    - key: amount
+      op: ">"
+      value: 100
+```
+
+Then:
+
+```python
+from taghound import TagHound
+
+th = TagHound.rules_from_yaml("rules.yml")
+
+print(th.find_all_tags({"merchant": "STARBUCKS #1234", "amount": 6.40}))
+# ('food/coffee',)
+print(th.find_all_tags({"merchant": "Delta Airlines", "amount": 420.00}))
+# ('alerts/big-purchase',)
+```
+
+## Rule format
+
+A rule is a unique `id` plus a tree of conditions under `and` / `or`, nested as deep as you need:
+
+```yaml
+- id: inventory/tall-tropical-tree  # required, unique; returned as the tag
+  label: Tall tropical tree         # optional, defaults to id
+  weight: 12                        # optional score, defaults to 0
+  info: internal note, not matched  # optional
+  and:
+    - key: type
+      value: tree                   # no `op` means `=`
+    - or:
+        - key: height
+          op: ">"
+          value: 20
+        - key: location
+          op: "~"
+          value: tropical
+```
+
+### Operators
+
+| Op | Meaning | Value types |
+|---|---|---|
+| `=` | equal (default when `op` is omitted) | int, float, str, bool |
+| `!=` | not equal | int, float, str, bool |
+| `>` `<` `>=` `<=` | numeric comparison | int, float |
+| `in` | field value is in the list | list |
+| `not_in` | field value is not in the list | list |
+| `~` | regex match | str or list of str |
+| `!~` | regex does not match | str or list of str |
+
+Regex matching is case-insensitive, and a list value is OR-joined (`starbucks|blue bottle`). Patterns are wrapped in `(?<!\w)(?:...)(?!\w)` so they match whole words; pass `merge_pattern=r"{pattern}"` to `rules_from_yaml`/`rules_from_json` for raw substring behavior, or any other wrapper with a `{pattern}` placeholder.
+
+Invalid rules (bad regex, unknown operator) raise at load time, not on first evaluation.
+
+## Tagging a DataFrame
+
+For large batches, evaluating a whole DataFrame at once is usually faster than calling `find_all_tags` per row (the break-even depends on your rules, so measure):
+
+```python
+import pandas as pd
+
+df = pd.DataFrame([
+    {"merchant": "Blue Bottle Coffee", "amount": 5.75},
+    {"merchant": "Delta Airlines", "amount": 420.00},
+])
+
+print(th.find_tags_using_vector(df))
+#              merchant  amount                   tags
+# 0  Blue Bottle Coffee    5.75          [food/coffee]
+# 1      Delta Airlines  420.00  [alerts/big-purchase]
+```
+
+The tags column is added to the input DataFrame in place; rename it with `output_column_name=`. Alternatively, `output_format="columns"` returns a copy with one boolean column per rule (`food/coffee`, `alerts/big-purchase`) — handy for filtering and aggregation.
+
+## Scoring and labeling matches
+
+Rule weights and labels are exposed as maps, so ranking matched records is a couple of lines:
+
+```python
+tags = th.find_all_tags({"merchant": "STARBUCKS #1234", "amount": 6.40})
+
+score = sum(th.rule_id_to_weight_map[t] for t in tags)
+labels = [th.rule_id_to_label_map[t] for t in tags]
+print(score, labels)
+# 3.0 ['Coffee']
+```
+
+## Rules in code
+
+Skip the files entirely by building rules with any Python callable:
+
+```python
+from taghound import TagHound
+from taghound.models import TagRule
+
+rules = [
+    TagRule(
+        id="python_rule",
+        label="Python",
+        weight=10,
+        required_fields={"language", "year"},
+        scalar_check=lambda d: d["language"] == "python" and d["year"] > 1990,
+    )
+]
+
+th = TagHound(rules=rules)
+```
+
+JSON works the same as YAML with an identical structure: `TagHound.rules_from_json("rules.json")`.
+
+## Example
+
+[examples/greek_gods](examples/greek_gods) tags a CSV of Greek gods with role/domain rules and prints the resulting DataFrame: `uv run python examples/greek_gods/attribute_tags.py`
+
+## Development
+
+```bash
+uv sync      # set up the environment
+just         # list recipes: test, lint, bench, profile, ...
+just check   # lint + tests, same as CI
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

taghound-0.2.0/README.md

@@ -0,0 +1,161 @@
+# TagHound
+
+Declarative tagging for Python: write matching rules in YAML or JSON, and TagHound attaches tags to your dicts or whole pandas DataFrames.
+
+Rules stay readable and editable by non-technical users, while your pipeline code stays a one-liner. Typical uses:
+
+- **Categorize bank transactions** — regex rules on merchant strings turn a CSV export into budget categories, no ML training required
+- **Triage tickets and log events** — keyword and threshold rules attach routing tags (severity, team, topic) to each incoming record
+- **Enrich scraped datasets** — bulk-tag job postings or product listings in a pandas pipeline, then rank matches by rule weights
+
+## Installation
+
+Requires Python 3.11+.
+
+```bash
+pip install taghound
+```
+
+Latest from source: `pip install git+https://github.com/rzagreb/TagHound.git`
+
+## Quick start
+
+Create `rules.yml`:
+
+```yaml
+- id: food/coffee
+  label: Coffee
+  weight: 3
+  and:
+    - key: merchant
+      op: "~"
+      value: starbucks|blue bottle
+
+- id: alerts/big-purchase
+  and:
+    - key: amount
+      op: ">"
+      value: 100
+```
+
+Then:
+
+```python
+from taghound import TagHound
+
+th = TagHound.rules_from_yaml("rules.yml")
+
+print(th.find_all_tags({"merchant": "STARBUCKS #1234", "amount": 6.40}))
+# ('food/coffee',)
+print(th.find_all_tags({"merchant": "Delta Airlines", "amount": 420.00}))
+# ('alerts/big-purchase',)
+```
+
+## Rule format
+
+A rule is a unique `id` plus a tree of conditions under `and` / `or`, nested as deep as you need:
+
+```yaml
+- id: inventory/tall-tropical-tree  # required, unique; returned as the tag
+  label: Tall tropical tree         # optional, defaults to id
+  weight: 12                        # optional score, defaults to 0
+  info: internal note, not matched  # optional
+  and:
+    - key: type
+      value: tree                   # no `op` means `=`
+    - or:
+        - key: height
+          op: ">"
+          value: 20
+        - key: location
+          op: "~"
+          value: tropical
+```
+
+### Operators
+
+| Op | Meaning | Value types |
+|---|---|---|
+| `=` | equal (default when `op` is omitted) | int, float, str, bool |
+| `!=` | not equal | int, float, str, bool |
+| `>` `<` `>=` `<=` | numeric comparison | int, float |
+| `in` | field value is in the list | list |
+| `not_in` | field value is not in the list | list |
+| `~` | regex match | str or list of str |
+| `!~` | regex does not match | str or list of str |
+
+Regex matching is case-insensitive, and a list value is OR-joined (`starbucks|blue bottle`). Patterns are wrapped in `(?<!\w)(?:...)(?!\w)` so they match whole words; pass `merge_pattern=r"{pattern}"` to `rules_from_yaml`/`rules_from_json` for raw substring behavior, or any other wrapper with a `{pattern}` placeholder.
+
+Invalid rules (bad regex, unknown operator) raise at load time, not on first evaluation.
+
+## Tagging a DataFrame
+
+For large batches, evaluating a whole DataFrame at once is usually faster than calling `find_all_tags` per row (the break-even depends on your rules, so measure):
+
+```python
+import pandas as pd
+
+df = pd.DataFrame([
+    {"merchant": "Blue Bottle Coffee", "amount": 5.75},
+    {"merchant": "Delta Airlines", "amount": 420.00},
+])
+
+print(th.find_tags_using_vector(df))
+#              merchant  amount                   tags
+# 0  Blue Bottle Coffee    5.75          [food/coffee]
+# 1      Delta Airlines  420.00  [alerts/big-purchase]
+```
+
+The tags column is added to the input DataFrame in place; rename it with `output_column_name=`. Alternatively, `output_format="columns"` returns a copy with one boolean column per rule (`food/coffee`, `alerts/big-purchase`) — handy for filtering and aggregation.
+
+## Scoring and labeling matches
+
+Rule weights and labels are exposed as maps, so ranking matched records is a couple of lines:
+
+```python
+tags = th.find_all_tags({"merchant": "STARBUCKS #1234", "amount": 6.40})
+
+score = sum(th.rule_id_to_weight_map[t] for t in tags)
+labels = [th.rule_id_to_label_map[t] for t in tags]
+print(score, labels)
+# 3.0 ['Coffee']
+```
+
+## Rules in code
+
+Skip the files entirely by building rules with any Python callable:
+
+```python
+from taghound import TagHound
+from taghound.models import TagRule
+
+rules = [
+    TagRule(
+        id="python_rule",
+        label="Python",
+        weight=10,
+        required_fields={"language", "year"},
+        scalar_check=lambda d: d["language"] == "python" and d["year"] > 1990,
+    )
+]
+
+th = TagHound(rules=rules)
+```
+
+JSON works the same as YAML with an identical structure: `TagHound.rules_from_json("rules.json")`.
+
+## Example
+
+[examples/greek_gods](examples/greek_gods) tags a CSV of Greek gods with role/domain rules and prints the resulting DataFrame: `uv run python examples/greek_gods/attribute_tags.py`
+
+## Development
+
+```bash
+uv sync      # set up the environment
+just         # list recipes: test, lint, bench, profile, ...
+just check   # lint + tests, same as CI
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

taghound-0.2.0/pyproject.toml

@@ -0,0 +1,60 @@
+[project]
+name = "taghound"
+version = "0.2.0"
+description = "TagHound: A Python library for managing and evaluating tag rules using scalar and vector operations. Supports YAML and JSON rule loading."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Roman Zagrebnev" }]
+keywords = ["tags", "rules", "YAML", "JSON", "Python"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Operating System :: OS Independent",
+    "Typing :: Typed",
+]
+dependencies = [
+    "pyyaml>=6.0.2",
+    "pandas>=2.2.3,<3",
+]
+
+[project.urls]
+Homepage = "https://github.com/rzagreb/TagHound"
+Repository = "https://github.com/rzagreb/TagHound"
+Documentation = "https://github.com/rzagreb/TagHound#readme"
+Changelog = "https://github.com/rzagreb/TagHound/blob/main/CHANGELOG.md"
+
+[dependency-groups]
+dev = [
+    "pytest==9.1.1",
+    "ruff==0.15.18",
+]
+profiling = [
+    "line-profiler==5.0.2",
+    "memray==1.19.3",
+    "pytest-benchmark==5.2.3",
+]
+
+[tool.uv]
+# Cap transitives to releases at least 30 days old (dependency soak window)
+constraint-dependencies = [
+    "numpy<=2.4.6",
+    "pillow<=12.2.0",
+    "typing-extensions<=4.15.0",
+    "tzdata<=2026.2",
+]
+
+[tool.uv.build-backend]
+module-root = ""
+
+[tool.pytest.ini_options]
+testpaths = ["tests", "taghound"]
+pythonpath = ["."]
+addopts = "--doctest-modules"
+
+[build-system]
+requires = ["uv_build>=0.11.21,<0.12"]
+build-backend = "uv_build"

taghound-0.2.0/taghound/__init__.py

@@ -0,0 +1,5 @@
+"""TagHound: rule-based tagging for dicts and pandas DataFrames."""
+
+from taghound.taghound import TagHound
+
+__all__ = ["TagHound"]

taghound-0.2.0/taghound/constants.py

@@ -0,0 +1,87 @@
+"""Shared enums, type aliases, and defaults for rule definitions."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from enum import Enum
+from typing import Any
+
+import pandas as pd
+
+PyEvalFn = Callable[[Mapping[str, Any]], bool]
+PdEvalFn = Callable[[pd.DataFrame], pd.Series]
+
+
+class LogicalOperator(Enum):
+    """Logical operators combining condition lists."""
+
+    AND = "and"
+    OR = "or"
+
+
+class ComparisonOperator(Enum):
+    """Comparison operators usable in a condition's `op` field."""
+
+    EQUAL = "="
+    NOT_EQUAL = "!="
+    GREATER_THAN = ">"
+    GREATER_THAN_OR_EQUAL = ">="
+    LESS_THAN = "<"
+    LESS_THAN_OR_EQUAL = "<="
+    IS = "is"
+    IS_NOT = "is_not"
+    IN = "in"
+    NOT_IN = "not_in"
+    REGEX_MATCH = "~"
+    REGEX_NOT_MATCH = "!~"
+
+
+ComparisonOperatorRegexOnly = {
+    ComparisonOperator.REGEX_MATCH,
+    ComparisonOperator.REGEX_NOT_MATCH,
+}
+ComparisonOperatorNumericOnly = {
+    ComparisonOperator.GREATER_THAN,
+    ComparisonOperator.GREATER_THAN_OR_EQUAL,
+    ComparisonOperator.LESS_THAN,
+    ComparisonOperator.LESS_THAN_OR_EQUAL,
+}
+ComparisonOperatorBoolOnly = {
+    ComparisonOperator.IS,
+    ComparisonOperator.IS_NOT,
+}
+ComparisonOperatorListOnly = {
+    ComparisonOperator.IN,
+    ComparisonOperator.NOT_IN,
+}
+
+
+class RuleKey(Enum):
+    """Top-level keys of a rule definition."""
+
+    ID = "id"
+    LABEL = "label"
+    WEIGHT = "weight"
+    INFO = "info"
+    ROOT_AND = LogicalOperator.AND.value
+    ROOT_OR = LogicalOperator.OR.value
+
+
+class ComparisonKey(Enum):
+    """Keys of a single comparison condition."""
+
+    KEY = "key"
+    OPERATOR = "op"
+    VALUE = "value"
+
+
+DEFAULT_COMPARISON_OPERATOR = ComparisonOperator.EQUAL
+""" Default comparison operator to use when not specified """
+
+DEFAULT_WEIGHT = 0.0
+""" Default weight to use when not specified """
+
+# - This is better than \b...\b because it also matches cases like `C++`
+# - Limitations: does not work when we need to match `.python` with `python` pattern
+DEFAULT_REGEX_MERGE_PATTERN = r"(?<!\w)(?:{pattern})(?!\w)"
+""" Pattern used to merge list of patterns into a single regex pattern """

taghound-0.2.0/taghound/exceptions.py

@@ -0,0 +1,13 @@
+"""Exceptions raised while parsing rule definitions."""
+
+
+class InvalidOperatorError(Exception):
+    """A logical node uses an operator other than `and`/`or`."""
+
+
+class RuleAndOrTogetherError(Exception):
+    """A rule's root condition has both `and` and `or`."""
+
+
+class MissingRootConditionError(Exception):
+    """A rule's root condition has neither `and` nor `or`."""

taghound-0.2.0/taghound/models.py

@@ -0,0 +1,38 @@
+"""Data model for tag rules."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from typing import Any
+
+from taghound.constants import PdEvalFn, PyEvalFn
+
+
+@dataclass(frozen=True, eq=True, slots=True)
+class TagRule:
+    """A single tag rule: identity, metadata, and its prebuilt check functions."""
+
+    id: str
+    """ Unique identifier for the rule. """
+
+    label: str = field(compare=False)
+    """ The label for the rule. No uniqueness is enforced. """
+
+    weight: float = field(compare=False)
+    """ The weight of the rule. """
+
+    required_fields: set[str] = field(compare=False)
+    """ The required fields for the rule. """
+
+    info: str | None = field(compare=False, default=None)
+    """ Internal comments for the rule. """
+
+    scalar_check: PyEvalFn | None = field(compare=False, default=None)
+    """ Scalar function used to check if the rule is satisfied. """
+
+    vector_check: PdEvalFn | None = field(compare=False, default=None)
+    """ Vector function used to check if the rule is satisfied. """
+
+    data: Mapping[str, Any] = field(compare=False, default_factory=dict)
+    """ The original data used to create the TagRule object. """

taghound-0.2.0/taghound/scalar/__init__.py

@@ -0,0 +1 @@
+"""Scalar (one mapping at a time) rule evaluation."""