narrata 0.1.0__tar.gz

narrata-0.1.0/.gitignore

@@ -0,0 +1,23 @@
+__pycache__/
+*.py[cod]
+.venv/
+src/*/.venv/
+.uv-cache/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.coverage
+coverage.xml
+htmlcov/
+dist/
+build/
+*.egg-info/
+.DS_Store
+.vscode/
+
+# Custom
+PROPOSAL.md
+DEVELOPER.md
+.agents
+uv.lock
+src/*/uv.lock

narrata-0.1.0/LICENSE

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

narrata-0.1.0/PKG-INFO

@@ -0,0 +1,164 @@
+Metadata-Version: 2.4
+Name: narrata
+Version: 0.1.0
+Summary: LLM-oriented narration and compression for time series data
+Author-email: Marcin Miklitz <11770857+marcinmiklitz@users.noreply.github.com>
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: numpy<3.0.0,>=1.24
+Requires-Dist: pandas<4.0.0,>=2.0.0
+Requires-Dist: scipy>=1.10.0
+Requires-Dist: toons>=0.4.2
+Provides-Extra: all
+Requires-Dist: pandas-ta-openbb>=0.4.23; extra == 'all'
+Requires-Dist: ruptures>=1.1.9; (python_version < '3.14') and extra == 'all'
+Requires-Dist: tslearn>=0.6.4; extra == 'all'
+Provides-Extra: indicators
+Requires-Dist: pandas-ta-openbb>=0.4.23; extra == 'indicators'
+Provides-Extra: patterns
+Requires-Dist: pandas-ta-openbb>=0.4.23; extra == 'patterns'
+Provides-Extra: regimes
+Requires-Dist: ruptures>=1.1.9; (python_version < '3.14') and extra == 'regimes'
+Provides-Extra: symbolic
+Requires-Dist: ruptures>=1.1.9; (python_version < '3.14') and extra == 'symbolic'
+Requires-Dist: tslearn>=0.6.4; extra == 'symbolic'
+Description-Content-Type: text/markdown
+
+# narrata
+
+`narrata` turns OHLCV price series into compact, deterministic text summaries optimized for LLM context.
+
+## Installation
+
+```bash
+pip install narrata
+```
+
+Install optional backends:
+
+```bash
+pip install "narrata[all]"
+```
+
+Requires Python 3.11+ and pandas 2.0+.
+
+## Quickstart
+
+```python
+import numpy as np
+import pandas as pd
+
+from narrata import narrate
+
+n = 120
+dates = pd.date_range("2025-01-01", periods=n, freq="D")
+rng = np.random.default_rng(7)
+close = np.linspace(140.0, 175.0, n) + rng.normal(0.0, 1.0, n)
+open_ = close + rng.normal(0.0, 0.6, n)
+high = np.maximum(open_, close) + np.abs(rng.normal(0.7, 0.2, n))
+low = np.minimum(open_, close) - np.abs(rng.normal(0.7, 0.2, n))
+volume = rng.integers(900_000, 2_100_000, n)
+
+df = pd.DataFrame(
+    {"Open": open_, "High": high, "Low": low, "Close": close, "Volume": volume},
+    index=dates,
+)
+df.attrs["ticker"] = "AAPL"
+
+print(narrate(df))
+```
+
+Example output:
+
+```text
+AAPL (120 pts, daily): ▁▁▂▂▂▃▃▄▄▄▄▅▆▆▆▆▇▇██
+Date range: 2025-01-01 to 2025-04-30
+Range: [$139.99, $175.68]  Mean: $157.35  Std: $10.33
+Start: $140.00  End: $175.19  Change: +25.14%
+Regime: Uptrend since 2025-01-02 (low volatility)
+RSI(14): 65.1 (neutral-bullish)  MACD: bullish crossover 1 day ago
+BB: near upper band
+Volume: 0.98x 20-day avg (average)
+Volatility: 23rd percentile (low)
+SAX(16): aaabbccdeeffgggh
+Patterns: Ascending triangle forming since 2025-03-02
+Candlestick: Doji on 2025-04-29
+Support: $145.13 (13 touches), $139.99 (6 touches)  Resistance: $175.68 (3 touches)
+```
+
+## Fallback vs extras (same input)
+
+Using the same deterministic 252-point dataset:
+
+Fallback-only (`pip install narrata`):
+
+```text
+AAPL (252 pts, business-daily): ▁▂▁▂▂▃▃▃▄▄▄▅▆▆▆▆▇▇▇█
+Date range: 2024-01-02 to 2024-12-18
+Range: [$140.61, $201.32]  Mean: $170.44  Std: $17.52
+Start: $141.05  End: $201.32  Change: +42.73%
+Regime: Uptrend since 2024-12-10 (low volatility)
+RSI(14): 72.9 (overbought)  MACD: bullish crossover 7 days ago
+BB: above upper band
+SMA 50/200: golden cross
+Volume: 0.95x 20-day avg (average)
+Volatility: 1st percentile (extremely low)
+SAX(16): aaabbcdeefggghhh
+Patterns: Ascending triangle forming since 2024-09-26
+Candlestick: Bullish Engulfing on 2024-12-17
+Support: $193.16 (27 touches), $156.63 (26 touches)  Resistance: $201.32 (4 touches)
+```
+
+With extras (`pip install "narrata[all]"`):
+
+```text
+AAPL (252 pts, business-daily): ▁▂▁▂▂▃▃▃▄▄▄▅▆▆▆▆▇▇▇█
+Date range: 2024-01-02 to 2024-12-18
+Range: [$140.61, $201.32]  Mean: $170.44  Std: $17.52
+Start: $141.05  End: $201.32  Change: +42.73%
+Regime: Uptrend since 2024-10-02 (low volatility)
+RSI(14): 72.9 (overbought)  MACD: bullish crossover 7 days ago
+BB: above upper band
+SMA 50/200: golden cross
+Volume: 0.95x 20-day avg (average)
+Volatility: 1st percentile (extremely low)
+SAX(16): aaabbbcddefggghh
+Patterns: Ascending triangle forming since 2024-09-26
+Candlestick: Doji on 2024-12-11
+Support: $193.16 (27 touches), $156.63 (26 touches)  Resistance: $201.32 (4 touches)
+```
+
+## Public API imports
+
+```python
+from narrata import (
+    narrate,
+    analyze_summary,
+    analyze_regime,
+    analyze_indicators,
+    sax_encode,
+    astride_encode,
+    detect_patterns,
+    find_support_resistance,
+    make_sparkline,
+    digit_tokenize,
+    to_plain,
+    to_markdown_kv,
+    to_toon,
+)
+```
+
+## FAQ
+
+### Is narrata redundant if I already use OpenBB, yfinance, or another data SDK?
+
+No. `narrata` is complementary. It sits on top of your data access layer and converts OHLCV data into concise, LLM-ready narrative text.
+
+### Does narrata call an LLM or provide LLM endpoints?
+
+No. `narrata` is a pure Python library with deterministic, programmatic analysis and narration. It does not call LLM APIs.
+
+## Citation
+
+If you use `narrata` in research or public projects, cite this package using `CITATION.cff`.

narrata-0.1.0/README.md

@@ -0,0 +1,137 @@
+# narrata
+
+`narrata` turns OHLCV price series into compact, deterministic text summaries optimized for LLM context.
+
+## Installation
+
+```bash
+pip install narrata
+```
+
+Install optional backends:
+
+```bash
+pip install "narrata[all]"
+```
+
+Requires Python 3.11+ and pandas 2.0+.
+
+## Quickstart
+
+```python
+import numpy as np
+import pandas as pd
+
+from narrata import narrate
+
+n = 120
+dates = pd.date_range("2025-01-01", periods=n, freq="D")
+rng = np.random.default_rng(7)
+close = np.linspace(140.0, 175.0, n) + rng.normal(0.0, 1.0, n)
+open_ = close + rng.normal(0.0, 0.6, n)
+high = np.maximum(open_, close) + np.abs(rng.normal(0.7, 0.2, n))
+low = np.minimum(open_, close) - np.abs(rng.normal(0.7, 0.2, n))
+volume = rng.integers(900_000, 2_100_000, n)
+
+df = pd.DataFrame(
+    {"Open": open_, "High": high, "Low": low, "Close": close, "Volume": volume},
+    index=dates,
+)
+df.attrs["ticker"] = "AAPL"
+
+print(narrate(df))
+```
+
+Example output:
+
+```text
+AAPL (120 pts, daily): ▁▁▂▂▂▃▃▄▄▄▄▅▆▆▆▆▇▇██
+Date range: 2025-01-01 to 2025-04-30
+Range: [$139.99, $175.68]  Mean: $157.35  Std: $10.33
+Start: $140.00  End: $175.19  Change: +25.14%
+Regime: Uptrend since 2025-01-02 (low volatility)
+RSI(14): 65.1 (neutral-bullish)  MACD: bullish crossover 1 day ago
+BB: near upper band
+Volume: 0.98x 20-day avg (average)
+Volatility: 23rd percentile (low)
+SAX(16): aaabbccdeeffgggh
+Patterns: Ascending triangle forming since 2025-03-02
+Candlestick: Doji on 2025-04-29
+Support: $145.13 (13 touches), $139.99 (6 touches)  Resistance: $175.68 (3 touches)
+```
+
+## Fallback vs extras (same input)
+
+Using the same deterministic 252-point dataset:
+
+Fallback-only (`pip install narrata`):
+
+```text
+AAPL (252 pts, business-daily): ▁▂▁▂▂▃▃▃▄▄▄▅▆▆▆▆▇▇▇█
+Date range: 2024-01-02 to 2024-12-18
+Range: [$140.61, $201.32]  Mean: $170.44  Std: $17.52
+Start: $141.05  End: $201.32  Change: +42.73%
+Regime: Uptrend since 2024-12-10 (low volatility)
+RSI(14): 72.9 (overbought)  MACD: bullish crossover 7 days ago
+BB: above upper band
+SMA 50/200: golden cross
+Volume: 0.95x 20-day avg (average)
+Volatility: 1st percentile (extremely low)
+SAX(16): aaabbcdeefggghhh
+Patterns: Ascending triangle forming since 2024-09-26
+Candlestick: Bullish Engulfing on 2024-12-17
+Support: $193.16 (27 touches), $156.63 (26 touches)  Resistance: $201.32 (4 touches)
+```
+
+With extras (`pip install "narrata[all]"`):
+
+```text
+AAPL (252 pts, business-daily): ▁▂▁▂▂▃▃▃▄▄▄▅▆▆▆▆▇▇▇█
+Date range: 2024-01-02 to 2024-12-18
+Range: [$140.61, $201.32]  Mean: $170.44  Std: $17.52
+Start: $141.05  End: $201.32  Change: +42.73%
+Regime: Uptrend since 2024-10-02 (low volatility)
+RSI(14): 72.9 (overbought)  MACD: bullish crossover 7 days ago
+BB: above upper band
+SMA 50/200: golden cross
+Volume: 0.95x 20-day avg (average)
+Volatility: 1st percentile (extremely low)
+SAX(16): aaabbbcddefggghh
+Patterns: Ascending triangle forming since 2024-09-26
+Candlestick: Doji on 2024-12-11
+Support: $193.16 (27 touches), $156.63 (26 touches)  Resistance: $201.32 (4 touches)
+```
+
+## Public API imports
+
+```python
+from narrata import (
+    narrate,
+    analyze_summary,
+    analyze_regime,
+    analyze_indicators,
+    sax_encode,
+    astride_encode,
+    detect_patterns,
+    find_support_resistance,
+    make_sparkline,
+    digit_tokenize,
+    to_plain,
+    to_markdown_kv,
+    to_toon,
+)
+```
+
+## FAQ
+
+### Is narrata redundant if I already use OpenBB, yfinance, or another data SDK?
+
+No. `narrata` is complementary. It sits on top of your data access layer and converts OHLCV data into concise, LLM-ready narrative text.
+
+### Does narrata call an LLM or provide LLM endpoints?
+
+No. `narrata` is a pure Python library with deterministic, programmatic analysis and narration. It does not call LLM APIs.
+
+## Citation
+
+If you use `narrata` in research or public projects, cite this package using `CITATION.cff`.

narrata-0.1.0/narrata/__init__.py

@@ -0,0 +1,90 @@
+"""Public API for narrata."""
+
+from importlib.metadata import version
+
+from narrata.analysis.indicators import (
+    analyze_indicators,
+    compute_bollinger,
+    compute_ma_crossover,
+    compute_macd,
+    compute_rsi,
+    compute_volatility_percentile,
+    compute_volume_state,
+    describe_indicators,
+)
+from narrata.analysis.patterns import (
+    describe_candlestick,
+    describe_patterns,
+    detect_candlestick_pattern,
+    detect_chart_pattern,
+    detect_patterns,
+)
+from narrata.analysis.regimes import analyze_regime, describe_regime
+from narrata.analysis.summary import analyze_summary, describe_summary
+from narrata.analysis.support_resistance import describe_support_resistance, find_support_resistance
+from narrata.analysis.symbolic import astride_encode, describe_astride, describe_sax, sax_encode
+from narrata.composition.narrate import narrate
+from narrata.compression.digits import digit_tokenize
+from narrata.exceptions import NarrataError, UnsupportedFormatError, ValidationError
+from narrata.formatting.serializers import format_sections, to_markdown_kv, to_plain, to_toon
+from narrata.rendering.sparkline import make_sparkline
+from narrata.types import (
+    IndicatorStats,
+    LevelStats,
+    OutputFormat,
+    PatternStats,
+    PriceLevel,
+    RegimeStats,
+    SummaryStats,
+    SymbolicStats,
+)
+from narrata.validation.ohlcv import infer_frequency_label, validate_ohlcv_frame
+
+__version__ = version("narrata")
+
+__all__ = [
+    "IndicatorStats",
+    "LevelStats",
+    "NarrataError",
+    "OutputFormat",
+    "PatternStats",
+    "PriceLevel",
+    "RegimeStats",
+    "SummaryStats",
+    "SymbolicStats",
+    "UnsupportedFormatError",
+    "ValidationError",
+    "astride_encode",
+    "analyze_indicators",
+    "analyze_regime",
+    "__version__",
+    "analyze_summary",
+    "compute_bollinger",
+    "compute_ma_crossover",
+    "compute_macd",
+    "compute_rsi",
+    "compute_volatility_percentile",
+    "compute_volume_state",
+    "describe_astride",
+    "describe_candlestick",
+    "describe_indicators",
+    "describe_patterns",
+    "describe_regime",
+    "describe_sax",
+    "describe_summary",
+    "describe_support_resistance",
+    "detect_candlestick_pattern",
+    "detect_chart_pattern",
+    "detect_patterns",
+    "digit_tokenize",
+    "format_sections",
+    "find_support_resistance",
+    "infer_frequency_label",
+    "make_sparkline",
+    "narrate",
+    "sax_encode",
+    "to_markdown_kv",
+    "to_plain",
+    "to_toon",
+    "validate_ohlcv_frame",
+]

narrata-0.1.0/narrata/analysis/__init__.py

@@ -0,0 +1,49 @@
+"""Numerical analysis primitives for narrata."""
+
+from narrata.analysis.indicators import (
+    analyze_indicators,
+    compute_bollinger,
+    compute_ma_crossover,
+    compute_macd,
+    compute_rsi,
+    compute_volatility_percentile,
+    compute_volume_state,
+    describe_indicators,
+)
+from narrata.analysis.patterns import (
+    describe_candlestick,
+    describe_patterns,
+    detect_candlestick_pattern,
+    detect_chart_pattern,
+    detect_patterns,
+)
+from narrata.analysis.regimes import analyze_regime, describe_regime
+from narrata.analysis.summary import analyze_summary, describe_summary
+from narrata.analysis.support_resistance import describe_support_resistance, find_support_resistance
+from narrata.analysis.symbolic import astride_encode, describe_astride, describe_sax, sax_encode
+
+__all__ = [
+    "astride_encode",
+    "analyze_indicators",
+    "analyze_regime",
+    "analyze_summary",
+    "compute_bollinger",
+    "compute_ma_crossover",
+    "compute_macd",
+    "compute_rsi",
+    "compute_volatility_percentile",
+    "compute_volume_state",
+    "describe_astride",
+    "describe_candlestick",
+    "describe_indicators",
+    "describe_patterns",
+    "describe_regime",
+    "describe_sax",
+    "describe_summary",
+    "describe_support_resistance",
+    "detect_candlestick_pattern",
+    "detect_chart_pattern",
+    "detect_patterns",
+    "find_support_resistance",
+    "sax_encode",
+]