steer-learn 0.1.0__tar.gz

steer_learn-0.1.0/PKG-INFO

@@ -0,0 +1,321 @@
+Metadata-Version: 2.4
+Name: steer-learn
+Version: 0.1.0
+Summary: SKLearn extention for Markov models
+Author-email: Miguel <miguel.melo@driverevel.com>
+License: MIT
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: scikit-learn
+Requires-Dist: numpy
+
+# steer_learn
+
+`steer_learn` is a lightweight **scikit-learn-compatible extension** for transition-based and sequence-aware learning.
+It provides estimators for **absorbing Markov chains** and **hidden Markov models (HMMs)**, plus small preprocessing utilities for path-like sequential data.
+
+The package is designed to feel familiar to scikit-learn users:
+
+- estimators inherit from `BaseEstimator`
+- predictive models follow the `fit` / `predict` / `predict_proba` API
+- transformers implement `fit` / `transform`
+- components are easy to compose in sklearn-style workflows where their input/output contracts fit the task
+
+## Why `steer_learn`?
+
+Many real-world systems are naturally described as **state transitions**:
+
+- navigation funnels
+- user journey analysis
+- workflow completion paths
+- process mining
+- discrete state machines
+- sequence classification with previous-state context
+
+`steer_learn` focuses on these settings with a simple API and minimal dependencies.
+
+## Features
+
+### Estimators
+
+- **`MarkovAbsorbingModel`**  
+  Learns transition probabilities for a Markov chain with absorbing states and predicts the most likely absorbing outcome.
+
+- **`HiddenMarkovModel`**  
+  A discrete-emission hidden Markov model classifier that combines transition probabilities with per-dimension categorical emission probabilities.
+
+- **`GaussianHiddenMarkovModel`**  
+  A continuous-emission hidden Markov model classifier that uses multivariate Gaussian emissions.
+
+### Transformers
+
+- **`PathSplitter`**  
+  Splits string paths into tokenized state sequences.
+
+- **`PathFlanker`**  
+  Prefixes each sequence with a start token and appends the aligned target value from `y`, making it a **supervised sequence-preparation transformer**.
+
+- **`TransitionRoller`**  
+  Converts sequences into pairwise transitions.
+
+## Installation
+
+For local development:
+
+```bash
+pip install steer_learn
+```
+
+## Quick start
+
+### 1. Absorbing Markov chain classification
+
+Use `MarkovAbsorbingModel` when each sample represents a transition from one state to the next, encoded as one-hot vectors.
+
+```python
+import numpy as np
+from steer_learn import MarkovAbsorbingModel
+
+# 3 states: A, B, C
+# X = source state, y = target state
+X = np.array([
+    [1, 0, 0],
+    [1, 0, 0],
+    [0, 1, 0],
+    [0, 1, 0],
+])
+
+y = np.array([
+    [0, 1, 0],
+    [0, 1, 0],
+    [0, 0, 1],
+    [0, 0, 1],
+])
+
+clf = MarkovAbsorbingModel()
+clf.fit(X, y)
+
+# Predict the final absorbing destination
+clf.predict(np.array([
+    [1, 0, 0],
+    [0, 1, 0],
+]))
+
+# Probability of each absorbing state
+clf.predict_proba(np.array([
+    [1, 0, 0],
+    [0, 1, 0],
+]))
+```
+
+### 2. Discrete hidden Markov model
+
+Use `HiddenMarkovModel` when:
+
+- the **first column** of `X` is the previous state
+- the remaining columns are **discrete observed symbols**
+- `y` is the current hidden state label
+
+```python
+import numpy as np
+from steer_learn import HiddenMarkovModel
+
+# X columns: [previous_state, symbol_1, symbol_2]
+X = np.array([
+    [0, 1, 2],
+    [0, 1, 1],
+    [1, 0, 2],
+    [1, 0, 1],
+])
+
+y = np.array([0, 0, 1, 1])
+
+clf = HiddenMarkovModel()
+clf.fit(X, y)
+
+pred = clf.predict(X)
+proba = clf.predict_proba(X)
+```
+
+### 3. Gaussian hidden Markov model
+
+Use `GaussianHiddenMarkovModel` when observations are continuous.
+
+```python
+import numpy as np
+from steer_learn import GaussianHiddenMarkovModel
+
+# X columns: [previous_state, feature_1, feature_2]
+X = np.array([
+    [0, 0.2, 1.1],
+    [0, 0.1, 0.9],
+    [1, 2.2, 3.0],
+    [1, 2.0, 2.8],
+])
+
+y = np.array([0, 0, 1, 1])
+
+clf = GaussianHiddenMarkovModel()
+clf.fit(X, y)
+
+pred = clf.predict(X)
+proba = clf.predict_proba(X)
+```
+
+## API design
+
+`steer_learn` follows the core conventions recommended for scikit-learn-compatible extensions:
+
+- **Estimator interface**: predictive models implement `fit`, `predict`, and when available `predict_proba`.
+- **Transformer interface**: preprocessing components implement `fit` and `transform`.
+- **Composable objects**: estimators inherit from `BaseEstimator`, which provides parameter inspection utilities such as `get_params` and `set_params`.
+- **Return `self` from `fit`**: all fitted estimators return the estimator instance.
+- **NumPy-first inputs**: examples use NumPy arrays and sklearn-style tabular inputs.
+
+This makes the project easier to understand for users already familiar with the scikit-learn ecosystem and simplifies future integration with tooling such as pipelines, search utilities, and model evaluation helpers.
+
+## Available objects
+
+### Top-level imports
+
+```python
+from steer_learn import (
+    MarkovAbsorbingModel,
+    HiddenMarkovModel,
+    GaussianHiddenMarkovModel,
+)
+```
+
+### Transformer utilities
+
+```python
+from steer_learn.transformer import (
+    PathSplitter,
+    PathFlanker,
+    TransitionRoller,
+)
+```
+
+## Input conventions
+
+### `MarkovAbsorbingModel`
+
+- `X`: 2D array of one-hot encoded **source** states
+- `y`: 2D array of one-hot encoded **target** states
+- `predict(X)`: returns the most likely absorbing state index
+- `predict_proba(X)`: returns absorbing-state probabilities
+
+### `HiddenMarkovModel`
+
+- `X[:, 0]`: previous state index
+- `X[:, 1:]`: discrete emission symbols
+- `y`: target state index
+- `predict_proba(X)`: returns unnormalized state scores from transition × emission terms
+
+### `GaussianHiddenMarkovModel`
+
+- `X[:, 0]`: previous state index
+- `X[:, 1:]`: continuous-valued observation vector
+- `y`: target state index
+- `predict_proba(X)`: returns Gaussian emission density × transition scores
+
+### `PathSplitter`
+
+- `X`: iterable of path strings
+- output: tokenized sequences split on `sep`
+
+### `PathFlanker`
+
+- parameter: `start_state="<START>"`
+- `X`: iterable of tokenized sequences
+- `y`: iterable of aligned target labels
+- output: each sample becomes `[start_state] + list(x) + [target]`
+
+Example:
+
+```python
+from steer_learn.transformer import PathFlanker
+
+X = [["Landing", "Signup"], ["Landing", "Pricing"]]
+y = ["Activated", "Churned"]
+
+flanker = PathFlanker(start_state="<START>")
+X_flanked = flanker.fit_transform(X, y)
+# ["<START>", "Landing", "Signup", "Activated"]
+# ["<START>", "Landing", "Pricing", "Churned"]
+```
+
+### `TransitionRoller`
+
+- `X`: iterable of sequences
+- output: 2-column transition pairs extracted from consecutive positions
+
+
+## Use cases
+
+`steer_learn` is a good fit for problems such as:
+
+- predicting terminal states in a process
+- estimating next-state probabilities
+- modeling user or system trajectories
+- sequence-aware classification with previous-state context
+- transforming string-based paths into transition datasets
+- preparing supervised transition sequences where the final label is appended to the observed path
+
+## Notes on `PathFlanker`
+
+`PathFlanker` now behaves differently from a typical unsupervised preprocessing transformer:
+
+- it uses `y` during `transform`, not just during `fit`
+- it appends the aligned target label to the end of each sequence
+- it is best understood as a **training-data preparation step** for labeled sequence problems
+
+This is still compatible with the general sklearn estimator style, but it is less conventional than a pure `transform(X)` preprocessing step. In practice, it is most useful in custom preprocessing workflows, dataset construction code, or supervised sequence pipelines where `y` is intentionally available at transform time.
+
+## Example workflow for path data
+
+A typical workflow for journey or state-path data may look like this:
+
+```python
+from steer_learn.transformer import PathSplitter, PathFlanker, TransitionRoller
+
+paths = [
+    "Landing -> Signup",
+    "Landing -> Pricing",
+]
+labels = ["Activated", "Churned"]
+
+splitter = PathSplitter(sep="->")
+flanker = PathFlanker(start_state="<START>")
+roller = TransitionRoller()
+
+X = splitter.fit_transform(paths)
+X = flanker.fit_transform(X, labels)
+transitions = roller.transform(X)
+```
+
+This produces transitions over sequences that begin with `<START>` and end with the aligned target label, which is useful when the target should be modeled as the final state in the path.
+
+## Notes and current scope
+
+This project is intentionally compact and focused. It currently emphasizes:
+
+- educational clarity
+- sklearn-style APIs
+- transition-based modeling primitives
+- simple NumPy-backed implementations
+
+
+## Contributing
+
+Contributions are welcome. A good contribution should preserve the project's core design goals:
+
+- keep the API intuitive for scikit-learn users
+- document estimator inputs and outputs clearly
+- prefer readable, testable implementations
+- maintain consistent naming and import patterns
+
+
+---
+
+If you use `steer_learn` in research, analytics, or production experiments, consider documenting the exact state encoding, label semantics, and sequence assumptions used in your preprocessing pipeline.

steer_learn-0.1.0/README.md

@@ -0,0 +1,310 @@
+# steer_learn
+
+`steer_learn` is a lightweight **scikit-learn-compatible extension** for transition-based and sequence-aware learning.
+It provides estimators for **absorbing Markov chains** and **hidden Markov models (HMMs)**, plus small preprocessing utilities for path-like sequential data.
+
+The package is designed to feel familiar to scikit-learn users:
+
+- estimators inherit from `BaseEstimator`
+- predictive models follow the `fit` / `predict` / `predict_proba` API
+- transformers implement `fit` / `transform`
+- components are easy to compose in sklearn-style workflows where their input/output contracts fit the task
+
+## Why `steer_learn`?
+
+Many real-world systems are naturally described as **state transitions**:
+
+- navigation funnels
+- user journey analysis
+- workflow completion paths
+- process mining
+- discrete state machines
+- sequence classification with previous-state context
+
+`steer_learn` focuses on these settings with a simple API and minimal dependencies.
+
+## Features
+
+### Estimators
+
+- **`MarkovAbsorbingModel`**  
+  Learns transition probabilities for a Markov chain with absorbing states and predicts the most likely absorbing outcome.
+
+- **`HiddenMarkovModel`**  
+  A discrete-emission hidden Markov model classifier that combines transition probabilities with per-dimension categorical emission probabilities.
+
+- **`GaussianHiddenMarkovModel`**  
+  A continuous-emission hidden Markov model classifier that uses multivariate Gaussian emissions.
+
+### Transformers
+
+- **`PathSplitter`**  
+  Splits string paths into tokenized state sequences.
+
+- **`PathFlanker`**  
+  Prefixes each sequence with a start token and appends the aligned target value from `y`, making it a **supervised sequence-preparation transformer**.
+
+- **`TransitionRoller`**  
+  Converts sequences into pairwise transitions.
+
+## Installation
+
+For local development:
+
+```bash
+pip install steer_learn
+```
+
+## Quick start
+
+### 1. Absorbing Markov chain classification
+
+Use `MarkovAbsorbingModel` when each sample represents a transition from one state to the next, encoded as one-hot vectors.
+
+```python
+import numpy as np
+from steer_learn import MarkovAbsorbingModel
+
+# 3 states: A, B, C
+# X = source state, y = target state
+X = np.array([
+    [1, 0, 0],
+    [1, 0, 0],
+    [0, 1, 0],
+    [0, 1, 0],
+])
+
+y = np.array([
+    [0, 1, 0],
+    [0, 1, 0],
+    [0, 0, 1],
+    [0, 0, 1],
+])
+
+clf = MarkovAbsorbingModel()
+clf.fit(X, y)
+
+# Predict the final absorbing destination
+clf.predict(np.array([
+    [1, 0, 0],
+    [0, 1, 0],
+]))
+
+# Probability of each absorbing state
+clf.predict_proba(np.array([
+    [1, 0, 0],
+    [0, 1, 0],
+]))
+```
+
+### 2. Discrete hidden Markov model
+
+Use `HiddenMarkovModel` when:
+
+- the **first column** of `X` is the previous state
+- the remaining columns are **discrete observed symbols**
+- `y` is the current hidden state label
+
+```python
+import numpy as np
+from steer_learn import HiddenMarkovModel
+
+# X columns: [previous_state, symbol_1, symbol_2]
+X = np.array([
+    [0, 1, 2],
+    [0, 1, 1],
+    [1, 0, 2],
+    [1, 0, 1],
+])
+
+y = np.array([0, 0, 1, 1])
+
+clf = HiddenMarkovModel()
+clf.fit(X, y)
+
+pred = clf.predict(X)
+proba = clf.predict_proba(X)
+```
+
+### 3. Gaussian hidden Markov model
+
+Use `GaussianHiddenMarkovModel` when observations are continuous.
+
+```python
+import numpy as np
+from steer_learn import GaussianHiddenMarkovModel
+
+# X columns: [previous_state, feature_1, feature_2]
+X = np.array([
+    [0, 0.2, 1.1],
+    [0, 0.1, 0.9],
+    [1, 2.2, 3.0],
+    [1, 2.0, 2.8],
+])
+
+y = np.array([0, 0, 1, 1])
+
+clf = GaussianHiddenMarkovModel()
+clf.fit(X, y)
+
+pred = clf.predict(X)
+proba = clf.predict_proba(X)
+```
+
+## API design
+
+`steer_learn` follows the core conventions recommended for scikit-learn-compatible extensions:
+
+- **Estimator interface**: predictive models implement `fit`, `predict`, and when available `predict_proba`.
+- **Transformer interface**: preprocessing components implement `fit` and `transform`.
+- **Composable objects**: estimators inherit from `BaseEstimator`, which provides parameter inspection utilities such as `get_params` and `set_params`.
+- **Return `self` from `fit`**: all fitted estimators return the estimator instance.
+- **NumPy-first inputs**: examples use NumPy arrays and sklearn-style tabular inputs.
+
+This makes the project easier to understand for users already familiar with the scikit-learn ecosystem and simplifies future integration with tooling such as pipelines, search utilities, and model evaluation helpers.
+
+## Available objects
+
+### Top-level imports
+
+```python
+from steer_learn import (
+    MarkovAbsorbingModel,
+    HiddenMarkovModel,
+    GaussianHiddenMarkovModel,
+)
+```
+
+### Transformer utilities
+
+```python
+from steer_learn.transformer import (
+    PathSplitter,
+    PathFlanker,
+    TransitionRoller,
+)
+```
+
+## Input conventions
+
+### `MarkovAbsorbingModel`
+
+- `X`: 2D array of one-hot encoded **source** states
+- `y`: 2D array of one-hot encoded **target** states
+- `predict(X)`: returns the most likely absorbing state index
+- `predict_proba(X)`: returns absorbing-state probabilities
+
+### `HiddenMarkovModel`
+
+- `X[:, 0]`: previous state index
+- `X[:, 1:]`: discrete emission symbols
+- `y`: target state index
+- `predict_proba(X)`: returns unnormalized state scores from transition × emission terms
+
+### `GaussianHiddenMarkovModel`
+
+- `X[:, 0]`: previous state index
+- `X[:, 1:]`: continuous-valued observation vector
+- `y`: target state index
+- `predict_proba(X)`: returns Gaussian emission density × transition scores
+
+### `PathSplitter`
+
+- `X`: iterable of path strings
+- output: tokenized sequences split on `sep`
+
+### `PathFlanker`
+
+- parameter: `start_state="<START>"`
+- `X`: iterable of tokenized sequences
+- `y`: iterable of aligned target labels
+- output: each sample becomes `[start_state] + list(x) + [target]`
+
+Example:
+
+```python
+from steer_learn.transformer import PathFlanker
+
+X = [["Landing", "Signup"], ["Landing", "Pricing"]]
+y = ["Activated", "Churned"]
+
+flanker = PathFlanker(start_state="<START>")
+X_flanked = flanker.fit_transform(X, y)
+# ["<START>", "Landing", "Signup", "Activated"]
+# ["<START>", "Landing", "Pricing", "Churned"]
+```
+
+### `TransitionRoller`
+
+- `X`: iterable of sequences
+- output: 2-column transition pairs extracted from consecutive positions
+
+
+## Use cases
+
+`steer_learn` is a good fit for problems such as:
+
+- predicting terminal states in a process
+- estimating next-state probabilities
+- modeling user or system trajectories
+- sequence-aware classification with previous-state context
+- transforming string-based paths into transition datasets
+- preparing supervised transition sequences where the final label is appended to the observed path
+
+## Notes on `PathFlanker`
+
+`PathFlanker` now behaves differently from a typical unsupervised preprocessing transformer:
+
+- it uses `y` during `transform`, not just during `fit`
+- it appends the aligned target label to the end of each sequence
+- it is best understood as a **training-data preparation step** for labeled sequence problems
+
+This is still compatible with the general sklearn estimator style, but it is less conventional than a pure `transform(X)` preprocessing step. In practice, it is most useful in custom preprocessing workflows, dataset construction code, or supervised sequence pipelines where `y` is intentionally available at transform time.
+
+## Example workflow for path data
+
+A typical workflow for journey or state-path data may look like this:
+
+```python
+from steer_learn.transformer import PathSplitter, PathFlanker, TransitionRoller
+
+paths = [
+    "Landing -> Signup",
+    "Landing -> Pricing",
+]
+labels = ["Activated", "Churned"]
+
+splitter = PathSplitter(sep="->")
+flanker = PathFlanker(start_state="<START>")
+roller = TransitionRoller()
+
+X = splitter.fit_transform(paths)
+X = flanker.fit_transform(X, labels)
+transitions = roller.transform(X)
+```
+
+This produces transitions over sequences that begin with `<START>` and end with the aligned target label, which is useful when the target should be modeled as the final state in the path.
+
+## Notes and current scope
+
+This project is intentionally compact and focused. It currently emphasizes:
+
+- educational clarity
+- sklearn-style APIs
+- transition-based modeling primitives
+- simple NumPy-backed implementations
+
+
+## Contributing
+
+Contributions are welcome. A good contribution should preserve the project's core design goals:
+
+- keep the API intuitive for scikit-learn users
+- document estimator inputs and outputs clearly
+- prefer readable, testable implementations
+- maintain consistent naming and import patterns
+
+
+---
+
+If you use `steer_learn` in research, analytics, or production experiments, consider documenting the exact state encoding, label semantics, and sequence assumptions used in your preprocessing pipeline.

steer_learn-0.1.0/pyproject.toml

@@ -0,0 +1,24 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "steer-learn"
+version = "0.1.0"
+description = "SKLearn extention for Markov models"
+authors = [
+    { name = "Miguel", email = "miguel.melo@driverevel.com" }
+]
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.8"
+dependencies = [
+    "scikit-learn",
+    "numpy"
+]
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]

steer_learn-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

steer_learn-0.1.0/src/steer_learn/__init__.py

@@ -0,0 +1,2 @@
+from .markov_chain import MarkovAbsorbingModel
+from .hidden_markov_model import HiddenMarkovModel, GaussianHiddenMarkovModel

steer_learn-0.1.0/src/steer_learn/hidden_markov_model.py

@@ -0,0 +1,119 @@
+from typing import Iterable
+from abc import ABC, abstractmethod
+
+import numpy as np
+from sklearn.base import BaseEstimator, ClassifierMixin
+
+class HiddenMarkovModelBase(BaseEstimator, ClassifierMixin, ABC):
+    _n_states: int
+    _n_dims: int
+    _transitions_matrix: np.ndarray[float, float]
+
+    def fit(self, X, y):
+        prev_states, _ = self._preprocess_x(X)
+        states = np.array(y)
+        self._n_states = max(prev_states.max(), states.max()) + 1
+
+        transitions = np.zeros((self._n_states, self._n_states))
+        for prev_state, state in zip(prev_states, states):
+            transitions[prev_state, state] += 1
+
+        totals = np.sum(transitions, axis=1, keepdims=True)
+        totals[totals == 0] = 1
+        self._transitions_matrix = transitions / totals
+        return self
+
+    @abstractmethod
+    def _emission(self, state: int, symbols: Iterable[int | float]) -> float: ...
+
+    @staticmethod
+    def _preprocess_x(X: Iterable[Iterable[float | int]]) -> (np.ndarray[int], np.ndarray[float, float]):
+        X_processed = np.array(X)
+        x1 = X_processed[:, 0]
+        x2 = X_processed[:, 1:]
+        return x1, x2
+
+    def _transitions(self, state_a: int, state_b: int) -> float:
+        return self._transitions_matrix[state_a, state_b]
+
+    def predict_proba(self, X):
+        prev_states, symbols = self._preprocess_x(X)
+        transitions = np.zeros((len(prev_states), self._n_states))
+        emissions = np.zeros_like(transitions)
+
+        for i, (prev_state, symbol) in enumerate(zip(prev_states, symbols)):
+            for state in range(self._n_states):
+                emissions[i, state] = self._emission(state, symbol)
+                transitions[i, state] = self._transitions(prev_state, state)
+
+        return emissions * transitions
+
+
+    def predict(self, X: Iterable[Iterable[float | int]]) -> np.ndarray[int]:
+        probs = self.predict_proba(X)
+        return np.argmax(probs, axis=1)
+
+class HiddenMarkovModel(HiddenMarkovModelBase):
+    _n_symbols: int
+    _emission_matrix: np.ndarray[float, float]
+
+    def fit(self, X: Iterable[Iterable[int]], y: Iterable[int]):
+        super().fit(X, y)
+        _, symbols = self._preprocess_x(X)
+        states = np.array(y)
+        self._n_symbols = np.max(symbols) + 1
+        self._n_dims = symbols.shape[1]
+        e_matrix = np.zeros((
+            self._n_states,
+            self._n_dims,
+            self._n_symbols
+        ))
+        for state, symbol in zip(states, symbols):
+            for d, symb in enumerate(symbol):
+                e_matrix[state, d, symb] += 1
+        totals = np.sum(e_matrix, axis=2, keepdims=True)
+        self._emission_matrix = e_matrix / totals
+        return self
+
+    def _emission(self, state: int, symbols: Iterable[int]) -> float:
+        result = 1
+        for d, symbol in enumerate(symbols):
+            result *= self._emission_matrix[state, d, symbol]
+        return result
+
+class GaussianHiddenMarkovModel(HiddenMarkovModelBase):
+    _mu: np.ndarray
+    _sigma: np.ndarray
+
+    def fit(self, X: Iterable[Iterable[float | int]], y: Iterable[int]):
+        super().fit(X, y)
+        _, symbols = self._preprocess_x(X)
+        states = np.array(y)
+        self._n_dims = symbols.shape[1]
+        mu = np.zeros((
+            self._n_states,
+            self._n_dims
+        ))
+        sigma = np.zeros((
+            self._n_states,
+            self._n_dims,
+            self._n_dims
+        ))
+        for i in range(self._n_states):
+            mu[i, :] = np.mean(symbols[states == i], axis=0)
+        for i in range(self._n_states):
+            symbol = symbols[states == i]
+            sigma[i, ...] = np.cov(symbol, rowvar=False, bias=True)
+
+        self._mu = mu
+        self._sigma = sigma
+        return self
+
+    def _emission(self, state, symbols):
+        x = np.array(symbols)
+        diff = x - self._mu[state]
+        sigma = self._sigma[state]
+        inv_sigma = np.linalg.inv(sigma)
+        exponent = -0.5 * (diff.T @ inv_sigma @ diff)
+        den = np.sqrt(((2 * np.pi) ** self._n_dims) * np.linalg.det(sigma))
+        return np.exp(exponent) / den

steer_learn-0.1.0/src/steer_learn/markov_chain.py

@@ -0,0 +1,59 @@
+from typing import Iterable
+
+import numpy as np
+from sklearn.base import BaseEstimator, ClassifierMixin
+
+
+class MarkovAbsorbingModel(BaseEstimator, ClassifierMixin):
+    _n_absorbing_states: int
+    _n_transient_states: int
+    _b_matrix: np.ndarray
+    _absorbing_states: np.ndarray
+    _transient_states: np.ndarray
+    _transient_map: np.ndarray
+
+    def fit(self, X: Iterable[Iterable[int]], y: Iterable[Iterable[int]]):
+        srcs = np.array(X)
+        trgs = np.array(y)
+        n_states = srcs.shape[1]
+        srcs = np.argmax(srcs, axis=1)
+        trgs = np.argmax(trgs, axis=1)
+        transitions = np.zeros((
+            n_states,
+            n_states
+        ))
+        for src, trg in zip(srcs, trgs):
+            transitions[src, trg] += 1
+        totals = np.sum(transitions, axis=1)
+        abs_idx = totals == 0
+        trans_idx = totals > 0
+        safe_totals = totals.copy()
+        safe_totals[abs_idx] = 1
+        transitions = transitions / safe_totals[:, None]
+        self._n_absorbing_states = np.sum(abs_idx)
+        self._n_transient_states = np.sum(trans_idx)
+        self._absorbing_states = np.flatnonzero(abs_idx)
+        self._transient_states = np.flatnonzero(trans_idx)
+        self._transient_map = np.full(n_states, -1, dtype=int)
+        self._transient_map[self._transient_states] = np.arange(self._n_transient_states)
+        Q = transitions[np.ix_(trans_idx, trans_idx)]
+        R = transitions[np.ix_(trans_idx, abs_idx)]
+        N = np.linalg.inv(
+            np.identity(self._n_transient_states) - Q
+        )
+        self._b_matrix = N @ R
+        return self
+
+    def predict(self, X: Iterable[Iterable[int]]) -> Iterable[int]:
+        probs = self.predict_proba(X)
+        return self._absorbing_states[np.argmax(probs, axis=1)]
+
+    def predict_proba(self, X: Iterable[Iterable[int]]) -> Iterable[Iterable[float]]:
+        idx = np.argmax(np.array(X), axis=1)
+        probs = np.zeros((len(idx), self._n_absorbing_states))
+        transient_mask = self._transient_map[idx] >= 0
+        probs[transient_mask] = self._b_matrix[self._transient_map[idx[transient_mask]]]
+        for i, state in enumerate(idx):
+            if not transient_mask[i]:
+                probs[i, self._absorbing_states == state] = 1.0
+        return probs

steer_learn-0.1.0/src/steer_learn/transformer.py

@@ -0,0 +1,42 @@
+import numpy as np
+from sklearn.base import BaseEstimator, TransformerMixin
+
+class PathSplitter(BaseEstimator, TransformerMixin):
+    def __init__(self, sep = "->"):
+        self.sep = sep
+
+    def fit(self, X, y=None):
+        return self
+
+    def transform(self, X, y=None):
+        return np.array(
+            [state.strip() for state in x.split(self.sep)]
+            for x in X
+        )
+
+class PathFlanker(BaseEstimator, TransformerMixin):
+    def __init__(self, start_state = "<START>"):
+        self.start_state = start_state
+
+    def fit(self, X, y=None):
+        return self
+
+    def transform(self, X, y=None):
+        return np.array(
+            np.array(
+                [self.start_state] + list(x) + [_y]
+            )
+            for x, _y in zip(X, y)
+        )
+
+class TransitionRoller(BaseEstimator, TransformerMixin):
+    def fit(self, X, y=None):
+        return self
+
+    @staticmethod
+    def transform(self, X, y=None):
+        transitions = []
+        for x in X:
+            for i in range(len(x) - 1):
+                transitions.append([x[i], x[i + 1]])
+        return np.array(transitions)

steer_learn-0.1.0/src/steer_learn.egg-info/PKG-INFO

@@ -0,0 +1,321 @@
+Metadata-Version: 2.4
+Name: steer-learn
+Version: 0.1.0
+Summary: SKLearn extention for Markov models
+Author-email: Miguel <miguel.melo@driverevel.com>
+License: MIT
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: scikit-learn
+Requires-Dist: numpy
+
+# steer_learn
+
+`steer_learn` is a lightweight **scikit-learn-compatible extension** for transition-based and sequence-aware learning.
+It provides estimators for **absorbing Markov chains** and **hidden Markov models (HMMs)**, plus small preprocessing utilities for path-like sequential data.
+
+The package is designed to feel familiar to scikit-learn users:
+
+- estimators inherit from `BaseEstimator`
+- predictive models follow the `fit` / `predict` / `predict_proba` API
+- transformers implement `fit` / `transform`
+- components are easy to compose in sklearn-style workflows where their input/output contracts fit the task
+
+## Why `steer_learn`?
+
+Many real-world systems are naturally described as **state transitions**:
+
+- navigation funnels
+- user journey analysis
+- workflow completion paths
+- process mining
+- discrete state machines
+- sequence classification with previous-state context
+
+`steer_learn` focuses on these settings with a simple API and minimal dependencies.
+
+## Features
+
+### Estimators
+
+- **`MarkovAbsorbingModel`**  
+  Learns transition probabilities for a Markov chain with absorbing states and predicts the most likely absorbing outcome.
+
+- **`HiddenMarkovModel`**  
+  A discrete-emission hidden Markov model classifier that combines transition probabilities with per-dimension categorical emission probabilities.
+
+- **`GaussianHiddenMarkovModel`**  
+  A continuous-emission hidden Markov model classifier that uses multivariate Gaussian emissions.
+
+### Transformers
+
+- **`PathSplitter`**  
+  Splits string paths into tokenized state sequences.
+
+- **`PathFlanker`**  
+  Prefixes each sequence with a start token and appends the aligned target value from `y`, making it a **supervised sequence-preparation transformer**.
+
+- **`TransitionRoller`**  
+  Converts sequences into pairwise transitions.
+
+## Installation
+
+For local development:
+
+```bash
+pip install steer_learn
+```
+
+## Quick start
+
+### 1. Absorbing Markov chain classification
+
+Use `MarkovAbsorbingModel` when each sample represents a transition from one state to the next, encoded as one-hot vectors.
+
+```python
+import numpy as np
+from steer_learn import MarkovAbsorbingModel
+
+# 3 states: A, B, C
+# X = source state, y = target state
+X = np.array([
+    [1, 0, 0],
+    [1, 0, 0],
+    [0, 1, 0],
+    [0, 1, 0],
+])
+
+y = np.array([
+    [0, 1, 0],
+    [0, 1, 0],
+    [0, 0, 1],
+    [0, 0, 1],
+])
+
+clf = MarkovAbsorbingModel()
+clf.fit(X, y)
+
+# Predict the final absorbing destination
+clf.predict(np.array([
+    [1, 0, 0],
+    [0, 1, 0],
+]))
+
+# Probability of each absorbing state
+clf.predict_proba(np.array([
+    [1, 0, 0],
+    [0, 1, 0],
+]))
+```
+
+### 2. Discrete hidden Markov model
+
+Use `HiddenMarkovModel` when:
+
+- the **first column** of `X` is the previous state
+- the remaining columns are **discrete observed symbols**
+- `y` is the current hidden state label
+
+```python
+import numpy as np
+from steer_learn import HiddenMarkovModel
+
+# X columns: [previous_state, symbol_1, symbol_2]
+X = np.array([
+    [0, 1, 2],
+    [0, 1, 1],
+    [1, 0, 2],
+    [1, 0, 1],
+])
+
+y = np.array([0, 0, 1, 1])
+
+clf = HiddenMarkovModel()
+clf.fit(X, y)
+
+pred = clf.predict(X)
+proba = clf.predict_proba(X)
+```
+
+### 3. Gaussian hidden Markov model
+
+Use `GaussianHiddenMarkovModel` when observations are continuous.
+
+```python
+import numpy as np
+from steer_learn import GaussianHiddenMarkovModel
+
+# X columns: [previous_state, feature_1, feature_2]
+X = np.array([
+    [0, 0.2, 1.1],
+    [0, 0.1, 0.9],
+    [1, 2.2, 3.0],
+    [1, 2.0, 2.8],
+])
+
+y = np.array([0, 0, 1, 1])
+
+clf = GaussianHiddenMarkovModel()
+clf.fit(X, y)
+
+pred = clf.predict(X)
+proba = clf.predict_proba(X)
+```
+
+## API design
+
+`steer_learn` follows the core conventions recommended for scikit-learn-compatible extensions:
+
+- **Estimator interface**: predictive models implement `fit`, `predict`, and when available `predict_proba`.
+- **Transformer interface**: preprocessing components implement `fit` and `transform`.
+- **Composable objects**: estimators inherit from `BaseEstimator`, which provides parameter inspection utilities such as `get_params` and `set_params`.
+- **Return `self` from `fit`**: all fitted estimators return the estimator instance.
+- **NumPy-first inputs**: examples use NumPy arrays and sklearn-style tabular inputs.
+
+This makes the project easier to understand for users already familiar with the scikit-learn ecosystem and simplifies future integration with tooling such as pipelines, search utilities, and model evaluation helpers.
+
+## Available objects
+
+### Top-level imports
+
+```python
+from steer_learn import (
+    MarkovAbsorbingModel,
+    HiddenMarkovModel,
+    GaussianHiddenMarkovModel,
+)
+```
+
+### Transformer utilities
+
+```python
+from steer_learn.transformer import (
+    PathSplitter,
+    PathFlanker,
+    TransitionRoller,
+)
+```
+
+## Input conventions
+
+### `MarkovAbsorbingModel`
+
+- `X`: 2D array of one-hot encoded **source** states
+- `y`: 2D array of one-hot encoded **target** states
+- `predict(X)`: returns the most likely absorbing state index
+- `predict_proba(X)`: returns absorbing-state probabilities
+
+### `HiddenMarkovModel`
+
+- `X[:, 0]`: previous state index
+- `X[:, 1:]`: discrete emission symbols
+- `y`: target state index
+- `predict_proba(X)`: returns unnormalized state scores from transition × emission terms
+
+### `GaussianHiddenMarkovModel`
+
+- `X[:, 0]`: previous state index
+- `X[:, 1:]`: continuous-valued observation vector
+- `y`: target state index
+- `predict_proba(X)`: returns Gaussian emission density × transition scores
+
+### `PathSplitter`
+
+- `X`: iterable of path strings
+- output: tokenized sequences split on `sep`
+
+### `PathFlanker`
+
+- parameter: `start_state="<START>"`
+- `X`: iterable of tokenized sequences
+- `y`: iterable of aligned target labels
+- output: each sample becomes `[start_state] + list(x) + [target]`
+
+Example:
+
+```python
+from steer_learn.transformer import PathFlanker
+
+X = [["Landing", "Signup"], ["Landing", "Pricing"]]
+y = ["Activated", "Churned"]
+
+flanker = PathFlanker(start_state="<START>")
+X_flanked = flanker.fit_transform(X, y)
+# ["<START>", "Landing", "Signup", "Activated"]
+# ["<START>", "Landing", "Pricing", "Churned"]
+```
+
+### `TransitionRoller`
+
+- `X`: iterable of sequences
+- output: 2-column transition pairs extracted from consecutive positions
+
+
+## Use cases
+
+`steer_learn` is a good fit for problems such as:
+
+- predicting terminal states in a process
+- estimating next-state probabilities
+- modeling user or system trajectories
+- sequence-aware classification with previous-state context
+- transforming string-based paths into transition datasets
+- preparing supervised transition sequences where the final label is appended to the observed path
+
+## Notes on `PathFlanker`
+
+`PathFlanker` now behaves differently from a typical unsupervised preprocessing transformer:
+
+- it uses `y` during `transform`, not just during `fit`
+- it appends the aligned target label to the end of each sequence
+- it is best understood as a **training-data preparation step** for labeled sequence problems
+
+This is still compatible with the general sklearn estimator style, but it is less conventional than a pure `transform(X)` preprocessing step. In practice, it is most useful in custom preprocessing workflows, dataset construction code, or supervised sequence pipelines where `y` is intentionally available at transform time.
+
+## Example workflow for path data
+
+A typical workflow for journey or state-path data may look like this:
+
+```python
+from steer_learn.transformer import PathSplitter, PathFlanker, TransitionRoller
+
+paths = [
+    "Landing -> Signup",
+    "Landing -> Pricing",
+]
+labels = ["Activated", "Churned"]
+
+splitter = PathSplitter(sep="->")
+flanker = PathFlanker(start_state="<START>")
+roller = TransitionRoller()
+
+X = splitter.fit_transform(paths)
+X = flanker.fit_transform(X, labels)
+transitions = roller.transform(X)
+```
+
+This produces transitions over sequences that begin with `<START>` and end with the aligned target label, which is useful when the target should be modeled as the final state in the path.
+
+## Notes and current scope
+
+This project is intentionally compact and focused. It currently emphasizes:
+
+- educational clarity
+- sklearn-style APIs
+- transition-based modeling primitives
+- simple NumPy-backed implementations
+
+
+## Contributing
+
+Contributions are welcome. A good contribution should preserve the project's core design goals:
+
+- keep the API intuitive for scikit-learn users
+- document estimator inputs and outputs clearly
+- prefer readable, testable implementations
+- maintain consistent naming and import patterns
+
+
+---
+
+If you use `steer_learn` in research, analytics, or production experiments, consider documenting the exact state encoding, label semantics, and sequence assumptions used in your preprocessing pipeline.

steer_learn-0.1.0/src/steer_learn.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+README.md
+pyproject.toml
+src/steer_learn/__init__.py
+src/steer_learn/hidden_markov_model.py
+src/steer_learn/markov_chain.py
+src/steer_learn/transformer.py
+src/steer_learn.egg-info/PKG-INFO
+src/steer_learn.egg-info/SOURCES.txt
+src/steer_learn.egg-info/dependency_links.txt
+src/steer_learn.egg-info/requires.txt
+src/steer_learn.egg-info/top_level.txt

steer_learn-0.1.0/src/steer_learn.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

steer_learn-0.1.0/src/steer_learn.egg-info/requires.txt

@@ -0,0 +1,2 @@
+scikit-learn
+numpy

steer_learn-0.1.0/src/steer_learn.egg-info/top_level.txt

@@ -0,0 +1 @@
+steer_learn