solyanka 0.0.1__tar.gz

solyanka-0.0.1/.gitignore

@@ -0,0 +1,14 @@
+**/__pycache__
+*.pyc
+.pytest_cache/
+.mypy_cache/
+dist/
+build/
+*.egg-info/
+.env
+*/coverage/
+logs/*
+!logs/.gitkeep
+**/tmp
+shared
+.worktree/

solyanka-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+    MIT License
+
+    Copyright (c) kvokka. All rights reserved.
+
+    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

solyanka-0.0.1/PKG-INFO

@@ -0,0 +1,101 @@
+Metadata-Version: 2.4
+Name: solyanka
+Version: 0.0.1
+Summary: Transaction pattern utilities and dataset for statement generators
+Author-email: Development Team <dev@company.com>
+License:     MIT License
+        
+            Copyright (c) kvokka. All rights reserved.
+        
+            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
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: jsonschema>=4.23; extra == 'dev'
+Requires-Dist: pytest>=8.2; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Solyanka
+
+Shared helpers and datasets that power the statement generators and downstream synthetic-data
+pipelines (including LLM fine-tuning sets).
+The first module exported by this repository focuses on transaction patterns: the curated YAML
+files, the schema that keeps them in shape, and a tiny loader to consume them from any
+application (FastAPI, CLI tools, notebooks, etc).
+
+## Installation
+
+```bash
+pip install solyanka
+```
+
+For local development (tests + linters):
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Usage
+
+```python
+from solyanka import PatternsService, EEA_COUNTRIES
+
+service = PatternsService()
+general = service.load_general_patterns()
+eea = service.load_eea_patterns()
+thailand_specific = service.load_country_patterns("Thailand")
+
+# Preferred helper: auto-mix general + (eea) + country overrides
+full_set = service.get_country_patterns("Germany")
+
+# Advanced filtering (e.g. validation scripts)
+custom = service.get_patterns(country="Germany", include="general,eea")
+
+# API-friendly dicts
+payload = service.get_pattern_dicts(country="Spain")
+```
+
+If you need to point the loader to different files (e.g. while editing YAML locally),
+either pass `PatternsService(base_dir=Path("./transaction_patterns"))` or set the
+`TRANSACTION_PATTERNS_DIR` environment variable.
+
+## Pattern sets
+
+- **General** – always included via `load_general_patterns()`.
+- **EEA** – supplement auto-applied for EEA countries via `load_eea_patterns()`.
+- **Country-specific** – call `load_country_patterns("Germany")`; the helper normalizes slugs internally.
+
+`get_country_patterns(country)` mixes general + (EEA when applicable) + country-level patterns and accepts empty/None values.
+`get_patterns(country, include)` exposes finer control when tooling needs only certain slices. `include` accepts a comma-separated subset of `{"general", "eea", "country"}`; invalid values raise `ValueError`.
+`get_pattern_dicts(...)` mirrors these parameters but returns normalized dictionaries that are ready for JSON responses.
+
+## Development
+
+- `pytest` validates every YAML file against `schema.json`.
+- GitHub Actions run tests on push/pull_request and build/publish artifacts when a semver tag is pushed.
+
+Contributions should keep the dataset human-friendly: no generated UUIDs in the patterns,
+clear field names, and comments that help reviewers understand why a pattern exists.
+
+### Tests
+
+```bash
+poetry run pytest
+```

solyanka-0.0.1/README.md

@@ -0,0 +1,67 @@
+# Solyanka
+
+Shared helpers and datasets that power the statement generators and downstream synthetic-data
+pipelines (including LLM fine-tuning sets).
+The first module exported by this repository focuses on transaction patterns: the curated YAML
+files, the schema that keeps them in shape, and a tiny loader to consume them from any
+application (FastAPI, CLI tools, notebooks, etc).
+
+## Installation
+
+```bash
+pip install solyanka
+```
+
+For local development (tests + linters):
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Usage
+
+```python
+from solyanka import PatternsService, EEA_COUNTRIES
+
+service = PatternsService()
+general = service.load_general_patterns()
+eea = service.load_eea_patterns()
+thailand_specific = service.load_country_patterns("Thailand")
+
+# Preferred helper: auto-mix general + (eea) + country overrides
+full_set = service.get_country_patterns("Germany")
+
+# Advanced filtering (e.g. validation scripts)
+custom = service.get_patterns(country="Germany", include="general,eea")
+
+# API-friendly dicts
+payload = service.get_pattern_dicts(country="Spain")
+```
+
+If you need to point the loader to different files (e.g. while editing YAML locally),
+either pass `PatternsService(base_dir=Path("./transaction_patterns"))` or set the
+`TRANSACTION_PATTERNS_DIR` environment variable.
+
+## Pattern sets
+
+- **General** – always included via `load_general_patterns()`.
+- **EEA** – supplement auto-applied for EEA countries via `load_eea_patterns()`.
+- **Country-specific** – call `load_country_patterns("Germany")`; the helper normalizes slugs internally.
+
+`get_country_patterns(country)` mixes general + (EEA when applicable) + country-level patterns and accepts empty/None values.
+`get_patterns(country, include)` exposes finer control when tooling needs only certain slices. `include` accepts a comma-separated subset of `{"general", "eea", "country"}`; invalid values raise `ValueError`.
+`get_pattern_dicts(...)` mirrors these parameters but returns normalized dictionaries that are ready for JSON responses.
+
+## Development
+
+- `pytest` validates every YAML file against `schema.json`.
+- GitHub Actions run tests on push/pull_request and build/publish artifacts when a semver tag is pushed.
+
+Contributions should keep the dataset human-friendly: no generated UUIDs in the patterns,
+clear field names, and comments that help reviewers understand why a pattern exists.
+
+### Tests
+
+```bash
+poetry run pytest
+```

solyanka-0.0.1/pyproject.toml

@@ -0,0 +1,40 @@
+[project]
+name = "solyanka"
+version = "0.0.1"
+description = "Transaction pattern utilities and dataset for statement generators"
+readme = "README.md"
+requires-python = ">=3.11"
+license = {file = "LICENSE"}
+authors = [
+    {name = "Development Team", email = "dev@company.com"},
+]
+dependencies = [
+    "pyyaml>=6.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.2",
+    "jsonschema>=4.23",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build]
+include = [
+    "solyanka",
+    "README.md",
+    "LICENSE",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["solyanka"]
+
+[tool.pytest.ini_options]
+addopts = "-ra --strict-markers --strict-config"
+testpaths = ["tests"]
+markers = [
+    "transaction_patterns: validate transaction pattern YAML files against the schema",
+]

solyanka-0.0.1/solyanka/__init__.py

@@ -0,0 +1,6 @@
+"""Solyanka – lightweight helpers for statement generation tooling."""
+
+from .transaction_patterns.service import EEA_COUNTRIES, Pattern, PatternsService
+
+__all__ = ["EEA_COUNTRIES", "Pattern", "PatternsService"]
+__version__ = "0.1.0"

solyanka-0.0.1/solyanka/transaction_patterns/__init__.py

@@ -0,0 +1,5 @@
+"""Transaction pattern utilities."""
+
+from .service import EEA_COUNTRIES, Pattern, PatternsService
+
+__all__ = ["EEA_COUNTRIES", "Pattern", "PatternsService"]

solyanka-0.0.1/solyanka/transaction_patterns/data/README.md

@@ -0,0 +1,79 @@
+# Transaction Patterns
+
+This directory contains YAML files with transaction patterns for generating card transactions.
+
+## Structure
+
+- `general.yml`: Contains transaction patterns that are common to all countries.
+- `eea.yml`: Contains transaction patterns specific to EEA (European Economic Area) countries.
+- `[country_code].yml`: Contains transaction patterns specific to a country. For example, `portugal.yml` contains patterns for Portugal.
+
+## Pattern Format
+
+Each pattern is a YAML object with the following fields:
+
+### Required Fields
+
+- `title`: The merchant name. Can be a string or a template object for dynamic generation.
+- `currency`: The currency of the transaction (3-letter currency code).
+- `amount_range`: A dictionary with `min` and `max` values for the transaction amount.
+- `amount_format`: An integer that controls the rounding of the generated transaction amount.
+  - A positive integer `n` rounds the amount to `n` decimal places (e.g., `2` for `12.34`).
+  - `0` rounds the amount to the nearest whole number (e.g., `12`).
+  - A negative integer `-n` rounds the amount to the nearest `10^|n|` (e.g., `-2` for rounding to the nearest 100, like `100`, `200`).
+- `types`: An array of tags categorizing the merchant (e.g., `["shopping", "groceries"]`).
+
+### Optional Fields
+
+- `weight` (optional): The relative probability weight for pattern selection. Defaults to 1000.
+- `refund_probability` (optional): The probability (from 0.0 to 1.0) that a transaction will be refunded. If not provided, defaults to system default.
+- `refundDelayMinHours` (optional): The minimum number of hours after a transaction that a refund can be generated. Defaults to 72.
+- `refundDelayMaxHours` (optional): The maximum number of hours after a transaction that a refund can be generated. Defaults to 288.
+- `numberOfOccurrences` (optional): The maximum number of times this transaction pattern can be used globally across a statement. If not provided, allows unlimited use.
+- `subscription_frequency_days` (optional): The frequency in days for recurring transactions. If provided, additional transactions will be generated every `subscription_frequency_days` days from the initial occurrence.
+
+### Template Titles
+
+The `title` field supports dynamic generation using templates:
+
+```yaml
+title:
+  type: template
+  template: "Revolut**{num}* DUBLIN"
+  params:
+    num:
+      generator: random_digits
+      length: 4
+      global_constant: true
+```
+
+#### Supported Generators
+
+- `random_digits`: Generates random digit strings
+  - `length`: Number of digits
+  - `zero_pad`: Whether to pad with leading zeros (default: true)
+- `random_alnum`: Generates random alphanumeric strings
+  - `length`: Number of characters
+  - `charset`: Custom character set (optional)
+- `choice`: Selects from a list of options
+  - `options`: Array of possible values
+  - `weights`: Optional array of selection weights
+
+#### Supported Transforms
+
+- `transform.case`: Apply case transformation
+  - `upper`: Convert to uppercase
+  - `lower`: Convert to lowercase
+  - `title`: Convert to title case
+
+#### Global Constants
+
+- `global_constant: true`: Ensures the same value is used across all instances of this parameter within a statement generation session.
+
+## Schema
+
+The JSON schema for the transaction patterns is available at [`schema.json`](schema.json).
+
+## Creating Transaction Patterns
+
+To create new transaction patterns, refer to the [Transaction Pattern Creation Guide](transaction_pattern_creation.md).

solyanka-0.0.1/solyanka/transaction_patterns/data/brazil.yml

@@ -0,0 +1,231 @@
+# Brazil Transaction Patterns
+# Generated from BRL transaction data analysis
+
+# Transportation - Uber rides
+- title: "Uber *Uber *Trip Sao Paulo"
+  currency: "BRL"
+  amount_range:
+    min: 5.00
+    max: 150.00
+  amount_format: 2
+  types: ["transportation", "rideshare", "uber"]
+  weight: 800
+
+- title: "Uber *Trip Help.uber.com SAO PAULO"
+  currency: "BRL"
+  amount_range:
+    min: 5.00
+    max: 150.00
+  amount_format: 2
+  types: ["transportation", "rideshare", "uber"]
+  weight: 600
+
+# Food & Dining - Cafes
+- title: "Cafe Fratelli Franqueador SAO PAULO"
+  currency: "BRL"
+  amount_range:
+    min: 10.00
+    max: 120.00
+  amount_format: 2
+  types: ["food", "cafe", "coffee"]
+  weight: 400
+
+- title: "Cafeteria Bsg SAO PAULO"
+  currency: "BRL"
+  amount_range:
+    min: 10.00
+    max: 120.00
+  amount_format: 2
+  types: ["food", "cafe", "coffee"]
+  weight: 300
+
+- title: "Rac Cafe Ltda SAO PAULO"
+  currency: "BRL"
+  amount_range:
+    min: 10.00
+    max: 120.00
+  amount_format: 2
+  types: ["food", "cafe", "coffee"]
+  weight: 200
+
+# Healthcare - Pharmacies
+- title: "Raia Drogasil SAO PAULO"
+  currency: "BRL"
+  amount_range:
+    min: 5.00
+    max: 150.00
+  amount_format: 2
+  types: ["healthcare", "pharmacy", "medicine"]
+  weight: 300
+
+- title: "Drogaria Sao Paulo Sa SAO PAULO"
+  currency: "BRL"
+  amount_range:
+    min: 5.00
+    max: 150.00
+  amount_format: 2
+  types: ["healthcare", "pharmacy", "medicine"]
+  weight: 250
+
+- title: "Drogaria Discover SAO PAULO"
+  currency: "BRL"
+  amount_range:
+    min: 5.00
+    max: 150.00
+  amount_format: 2
+  types: ["healthcare", "pharmacy", "medicine"]
+  weight: 200
+
+# Personal Care - Barbershops
+- title: "Barbearia Retrogol SAO PAULO"
+  currency: "BRL"
+  amount_range:
+    min: 100.00
+    max: 200.00
+  amount_format: 0
+  types: ["personal_care", "barbershop", "grooming"]
+  weight: 100
+
+# Food & Dining - Restaurants
+- title: "Restaurante Kanpai SAO PAULO"
+  currency: "BRL"
+  amount_range:
+    min: 50.00
+    max: 400.00
+  amount_format: 2
+  types: ["food", "restaurant", "dining"]
+  weight: 200
+
+- title: "Z Deli Sanduiches SAO PAULO"
+  currency: "BRL"
+  amount_range:
+    min: 30.00
+    max: 350.00
+  amount_format: 2
+  types: ["food", "restaurant", "deli", "sandwiches"]
+  weight: 150
+
+# Travel - Hotels
+- title: "Hotel At Booking.com SAO PAULO"
+  currency: "BRL"
+  amount_range:
+    min: 500.00
+    max: 2500.00
+  amount_format: 2
+  types: ["travel", "hotel", "accommodation"]
+  weight: 50
+
+- title: "Booking.com Hotel SAO PAULO"
+  currency: "BRL"
+  amount_range:
+    min: 500.00
+    max: 2500.00
+  amount_format: 2
+  types: ["travel", "hotel", "accommodation"]
+  weight: 50
+
+# Shopping - General retail
+- title: "Shopping Center SAO PAULO"
+  currency: "BRL"
+  amount_range:
+    min: 20.00
+    max: 400.00
+  amount_format: 0
+  types: ["shopping", "retail", "general"]
+  weight: 200
+
+# Supermarkets and grocery stores
+- title: "Supermercado Pao De Acucar SAO PAULO"
+  currency: "BRL"
+  amount_range:
+    min: 20.00
+    max: 300.00
+  amount_format: 2
+  types: ["food", "grocery", "supermarket"]
+  weight: 300
+
+- title: "Extra Supermercados SAO PAULO"
+  currency: "BRL"
+  amount_range:
+    min: 25.00
+    max: 350.00
+  amount_format: 2
+  types: ["food", "grocery", "supermarket"]
+  weight: 250
+
+# Gas stations
+- title: "Posto Ipiranga SAO PAULO"
+  currency: "BRL"
+  amount_range:
+    min: 50.00
+    max: 400.00
+  amount_format: 2
+  types: ["fuel", "gas_station", "automotive"]
+  weight: 200
+
+- title: "Shell Brasil SAO PAULO"
+  currency: "BRL"
+  amount_range:
+    min: 50.00
+    max: 400.00
+  amount_format: 2
+  types: ["fuel", "gas_station", "automotive"]
+  weight: 180
+
+# Fast food chains
+- title: "McDonald's SAO PAULO"
+  currency: "BRL"
+  amount_range:
+    min: 15.00
+    max: 80.00
+  amount_format: 2
+  types: ["food", "fast_food", "restaurant"]
+  weight: 300
+
+- title: "Burger King SAO PAULO"
+  currency: "BRL"
+  amount_range:
+    min: 15.00
+    max: 75.00
+  amount_format: 2
+  types: ["food", "fast_food", "restaurant"]
+  weight: 200
+
+# Public transportation
+- title: "Metro Sao Paulo"
+  currency: "BRL"
+  amount_range:
+    min: 4.00
+    max: 15.00
+  amount_format: 2
+  types: ["transportation", "public_transport", "metro"]
+  weight: 400
+
+# Entertainment
+- title: "Cinema Cinemark SAO PAULO"
+  currency: "BRL"
+  amount_range:
+    min: 20.00
+    max: 60.00
+  amount_format: 2
+  types: ["entertainment", "cinema", "movies"]
+  weight: 100
+
+# Clothing stores
+- title: "C&A SAO PAULO"
+  currency: "BRL"
+  amount_range:
+    min: 30.00
+    max: 300.00
+  amount_format: 2
+  types: ["shopping", "clothing", "fashion"]
+  weight: 150
+
+- title: "Renner SAO PAULO"
+  currency: "BRL"
+  amount_range:
+    min: 40.00
+    max: 350.00
+  amount_format: 2
+  types: ["shopping", "clothing", "fashion"]
+  weight: 120

solyanka-0.0.1/solyanka/transaction_patterns/data/eea.yml

@@ -0,0 +1,10 @@
+- title: "Flixbus Berlin"
+  currency: "EUR"
+  amount_range:
+    min: 15.0
+    max: 100.0
+  amount_format: 2
+  types:
+    - "traveling"
+    - "transportation"
+  weight: 30

solyanka-0.0.1/solyanka/transaction_patterns/data/france.yml

@@ -0,0 +1,18 @@
+- title:
+    type: template
+    template: "Hotel Tpe2 Vad {city}"
+    params:
+      city:
+        generator: choice
+        options: ["Bordeaux", "Paris", "Lyon"]
+        transform:
+          case: upper
+  currency: "EUR"
+  amount_range:
+    min: 250
+    max: 1000.0
+  amount_format: 2
+  types:
+    - "traveling"
+    - "hotel"
+  weight: 20