user-intent-discovery 1.1.0__tar.gz

user_intent_discovery-1.1.0/LICENSE

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

user_intent_discovery-1.1.0/PKG-INFO

@@ -0,0 +1,275 @@
+Metadata-Version: 2.4
+Name: user-intent-discovery
+Version: 1.1.0
+Summary: Cluster chatbot questions by semantic similarity and surface the most representative ones, with optional local-LLM summarization. Each pipeline stage (embed, reduce, cluster, summarize) can be run locally or against a remote server.
+License: MIT
+License-File: LICENSE
+Keywords: clustering,embeddings,umap,hdbscan,chatbot,topic-modeling,sentence-transformers,ollama
+Author: Nithin Vikas AV
+Author-email: nithinvikas.av@foxsense.io
+Requires-Python: >=3.10,<4.0
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Text Processing :: Linguistic
+Classifier: Typing :: Typed
+Provides-Extra: ui
+Requires-Dist: fastapi (>=0.110) ; extra == "ui"
+Requires-Dist: hdbscan (>=0.8.33)
+Requires-Dist: numpy (>=1.24)
+Requires-Dist: requests (>=2.31)
+Requires-Dist: scikit-learn (>=1.3)
+Requires-Dist: sentence-transformers (>=2.5)
+Requires-Dist: umap-learn (>=0.5.5)
+Requires-Dist: uvicorn[standard] (>=0.29) ; extra == "ui"
+Project-URL: Documentation, https://bitbucket.org/foxsense/user-intent-discovery
+Project-URL: Homepage, https://bitbucket.org/foxsense/user-intent-discovery
+Project-URL: Repository, https://bitbucket.org/foxsense/user-intent-discovery
+Description-Content-Type: text/markdown
+
+# user-intent-discovery
+
+Cluster short texts (chatbot questions, feedback items, search queries — anything sentence-sized) by semantic similarity, surface the most representative items per cluster, and optionally synthesize each cluster into a single "general question" with a local LLM.
+
+Ships as an importable **Python library**, an optional **FastAPI service with a browser UI**, and a set of **remote stage clients** — so any stage of the pipeline (embed, reduce, cluster, summarize) can run locally or against a different machine. Heavy stages on the GPU box, light ones on your laptop.
+
+## How it works
+
+```
+embed  ->  reduce (UMAP)  ->  cluster (HDBSCAN)  ->  representatives  ->  metrics  ->  summarize (optional)
+```
+
+1. **Embed** each text into a vector with `sentence-transformers`.
+2. **Reduce** to a low-dimensional space with UMAP (density clustering works poorly in high dimensions).
+3. **Cluster** with HDBSCAN, which finds clusters of varying density, labels outliers as noise, and does not require choosing the number of clusters up front.
+4. **Extract representatives**: the N items closest to each cluster's center.
+5. **Score** with silhouette, HDBSCAN persistence, DBCV, and noise ratio.
+6. **Summarize** (optional): one general question per cluster via a local Ollama model.
+
+## Installation
+
+```bash
+pip install user-intent-discovery              # library + remote clients
+pip install "user-intent-discovery[ui]"        # + FastAPI service and browser UI
+```
+
+Requires Python 3.10+.
+
+## Library usage
+
+```python
+from user_intent_discovery import TopicClusterer
+
+questions = [
+    "How do I reset my password?",
+    "I forgot my password, help",
+    "What are your business hours?",
+    "When are you open?",
+    # ...
+]
+
+clusterer = TopicClusterer(min_cluster_size=3)
+result = clusterer.fit(questions)
+
+print(f"Found {result.metrics.n_clusters} clusters "
+      f"({result.metrics.n_noise} noise points)")
+
+for cluster_id in result.top_k_clusters:
+    info = result.clusters[cluster_id]
+    print(f"\nCluster {cluster_id} ({info.size} items):")
+    for rep in info.representatives:
+        print(f"  - {rep.text}")
+```
+
+### With summarization
+
+Summarization needs a running [Ollama](https://ollama.com) server:
+
+```python
+from user_intent_discovery import TopicClusterer
+from user_intent_discovery.summarization import OllamaSummarizer
+
+clusterer = TopicClusterer(
+    min_cluster_size=3,
+    summarizer=OllamaSummarizer(model="llama3.2"),
+)
+result = clusterer.fit(questions)
+
+for cluster_id, question in (result.summaries or {}).items():
+    print(f"Cluster {cluster_id}: {question}")
+```
+
+## Split-compute across machines
+
+The pipeline has four stages and each is behind a protocol (`Embedder`, `Reducer`, `Clusterer`, `Summarizer`). Every protocol has a local implementation and a remote one — `RemoteEmbedder`, `RemoteReducer`, `RemoteClusterer`, `RemoteSummarizer` — that talks to a running `user-intent-discovery` server. Any stage the developer doesn't inject falls back to the local default, so mix-and-match is free.
+
+**All-remote** (laptop only orchestrates; every heavy stage runs elsewhere):
+
+```python
+from user_intent_discovery import TopicClusterer, remote_stages
+
+stages = remote_stages(
+    "http://gpu-box:8000",
+    cluster_dim=5, viz_dim=3,
+    min_cluster_size=3,
+    api_key="s3cret",         # optional; matched against the server's --api-key
+)
+result = TopicClusterer(**stages).fit(questions)
+```
+
+**Selective remote** (embed + summarize remote, UMAP + HDBSCAN local):
+
+```python
+from user_intent_discovery import TopicClusterer, RemoteEmbedder, RemoteSummarizer
+
+clusterer = TopicClusterer(
+    embedder   = RemoteEmbedder("http://gpu-box:8000"),
+    summarizer = RemoteSummarizer("http://gpu-box:8000", model="llama3.2"),
+    min_cluster_size=3,   # UMAP + HDBSCAN kwargs still apply to local defaults
+)
+result = clusterer.fit(questions)
+```
+
+The wire format is JSON (nested float lists). It is fine for tens of thousands of items; a binary format is on the v2 roadmap.
+
+### One-shot remote (no local pipeline)
+
+If you only want to POST texts to a server and get the full result back — no injection, no mix-and-match — use `TopicClustererClient`:
+
+```python
+from user_intent_discovery import TopicClustererClient
+
+client = TopicClustererClient("http://gpu-box:8000")
+result = client.fit(questions, min_cluster_size=3)   # returns a dict
+print(result["metrics"]["n_clusters"])
+```
+
+It only depends on `requests`, so it's the right choice for machines that can't install the ML stack.
+
+## Web service and UI
+
+Installed with the `[ui]` extra:
+
+```bash
+user-intent-discovery serve                                    # http://127.0.0.1:8000
+user-intent-discovery serve --port 9000 --ollama-model llama3.2
+user-intent-discovery serve --no-summarizer                    # UI summarize tab greyed out
+
+# production-ish
+user-intent-discovery serve \
+    --host 0.0.0.0 --port 8000 \
+    --api-key "$(openssl rand -hex 16)" \
+    --cors-origin https://app.example.com \
+    --cors-origin https://staging.example.com
+```
+
+Open the URL in a browser to paste questions, tune parameters, view the 3D cluster map, and summarize clusters.
+
+### API endpoints
+
+| Method | Path         | Purpose                                      |
+|--------|--------------|----------------------------------------------|
+| `POST` | `/ingest`    | Fetch texts from an external URL server-side |
+| `POST` | `/embed`     | Texts to embedding vectors                   |
+| `POST` | `/reduce`    | Vectors to reduced coordinates               |
+| `POST` | `/cluster`   | Coordinates to labels + metrics              |
+| `POST` | `/pipeline`  | One-shot: texts to full result               |
+| `POST` | `/summarize` | Cluster representatives to a question        |
+| `GET`  | `/health`    | Status + `summarizer_available` + `auth_required` |
+| `GET`  | `/`          | The browser UI                               |
+
+The staged endpoints let other apps plug in at a single stage; `/pipeline` is the convenience path the UI uses.
+
+### `/ingest` — fetch questions from your backend
+
+The browser can't fetch cross-origin URLs (CORS) and can't inject auth headers safely, so this endpoint runs the fetch server-side and hands the extracted texts back. The UI's **Fetch from URL** button uses this route.
+
+```bash
+curl -sX POST http://127.0.0.1:8000/ingest \
+  -H 'Content-Type: application/json' \
+  -d '{
+        "url":     "https://chatbot.example.com/api/unanswered",
+        "headers": {"Authorization": "Bearer '"$CHATBOT_TOKEN"'"}
+      }'
+# => {"texts": ["q1","q2",...], "count": 42}
+```
+
+Accepted upstream response shapes (auto-detected):
+
+- JSON list of strings: `["q1", "q2"]`
+- JSON list of objects, keys tried in order: `text`, `question`, `prompt`, `query`, `content`
+- JSON object with a list under `questions` / `texts` / `prompts` / `queries` / `items` / `data`
+- Plain text — split on newlines and commas
+
+Errors: `400` for a non-http(s) URL, `413` if the upstream body exceeds 10 MB, `502` on any upstream network failure, `422` if the body has no extractable texts.
+
+### Auth and CORS
+
+- **`--api-key VALUE`** (or `USER_INTENT_DISCOVERY_API_KEY` env var). When set, every compute endpoint requires `X-API-Key: VALUE`. `/health` and `/` stay open, and `/health` reports `auth_required: true` so clients can adapt.
+- **`--cors-origin URL`** (repeatable). Omit for permissive `*` (dev only); set explicit origins in production.
+
+### Input caps
+
+The server rejects over-large requests at the schema layer with HTTP 422, before any pipeline work:
+
+| Cap                          | Default   | Applies to                          |
+|------------------------------|-----------|-------------------------------------|
+| `MAX_TEXTS`                  | 20,000    | `/embed`, `/pipeline` text lists    |
+| `MAX_TEXT_LENGTH`            | 5,000     | per-text character length           |
+| `MAX_VECTORS`                | 50,000    | `/reduce`, `/cluster` inputs        |
+| `MAX_URL_LENGTH`             | 2,048     | `/ingest` url field                 |
+| `MAX_INGEST_BODY_BYTES`      | 10 MB     | `/ingest` upstream body             |
+| `MAX_CLUSTERS_PER_SUMMARIZE` | 500       | `/summarize` cluster count          |
+| `MAX_REPS_PER_CLUSTER`       | 100       | representatives per cluster         |
+
+Bump the constants in `user_intent_discovery/api/schemas.py` if a real workload legitimately needs more.
+
+## Key parameters
+
+| Parameter | Default | Notes |
+|-----------|---------|-------|
+| `min_cluster_size` | `5` | Smallest group that counts as a cluster. Lower it for small corpora. |
+| `cluster_dim` | `5` | UMAP dimensions clustered on. |
+| `umap_n_neighbors` | `15` | Lower = more local structure (helps on small datasets). |
+| `cluster_selection_method` | `"eom"` | `"leaf"` yields more, finer clusters. |
+| `top_n_per_cluster` | `5` | Representatives kept per cluster. |
+| `top_k_clusters` | `None` | Limit to the K largest clusters. |
+| `viz_dim` | `3` | Visualization dimensions; `0` skips it. |
+| `random_state` | `42` | `None` = faster but non-reproducible. |
+| `embedder`, `cluster_reducer`, `viz_reducer`, `clusterer`, `summarizer` | `None` | Inject any stage to override the local default. |
+
+## Reproducibility vs. speed
+
+By default `random_state=42`, so runs are reproducible but UMAP is single-threaded. Pass `random_state=None` for faster, multi-threaded, non-deterministic runs.
+
+## Errors
+
+Every exception derives from `ToolDiscoveryError` so a single `except` clause catches everything. Narrow subclasses: `EmbeddingError`, `ClusteringError`, `SummarizationError`, `OllamaConnectionError`. Over HTTP: `OllamaConnectionError` → 503, other `ToolDiscoveryError` → 500, schema violations → 422.
+
+## Non-goals (v1)
+
+To keep the first version focused: HDBSCAN only (no KMeans/Agglomerative); UMAP only (no PCA/t-SNE); Ollama only for summarization; embeddings are always computed in-package (no bring-your-own-vectors); nearest-centroid is the only noise-reassignment method; the API is stateless (no server-side sessions).
+
+Planned for v2: text-source abstraction (pull questions from an authenticated endpoint or receive them via webhook), scheduled auto-runs, and a binary wire format for the remote stage clients.
+
+## Development
+
+```bash
+git clone https://nithinvikasav@bitbucket.org/foxsense/user-intent-discovery.git
+cd user-intent-discovery
+poetry install --extras ui
+poetry run pytest -m "not integration"    # skip tests that need a running Ollama
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+

user_intent_discovery-1.1.0/README.md

@@ -0,0 +1,237 @@
+# user-intent-discovery
+
+Cluster short texts (chatbot questions, feedback items, search queries — anything sentence-sized) by semantic similarity, surface the most representative items per cluster, and optionally synthesize each cluster into a single "general question" with a local LLM.
+
+Ships as an importable **Python library**, an optional **FastAPI service with a browser UI**, and a set of **remote stage clients** — so any stage of the pipeline (embed, reduce, cluster, summarize) can run locally or against a different machine. Heavy stages on the GPU box, light ones on your laptop.
+
+## How it works
+
+```
+embed  ->  reduce (UMAP)  ->  cluster (HDBSCAN)  ->  representatives  ->  metrics  ->  summarize (optional)
+```
+
+1. **Embed** each text into a vector with `sentence-transformers`.
+2. **Reduce** to a low-dimensional space with UMAP (density clustering works poorly in high dimensions).
+3. **Cluster** with HDBSCAN, which finds clusters of varying density, labels outliers as noise, and does not require choosing the number of clusters up front.
+4. **Extract representatives**: the N items closest to each cluster's center.
+5. **Score** with silhouette, HDBSCAN persistence, DBCV, and noise ratio.
+6. **Summarize** (optional): one general question per cluster via a local Ollama model.
+
+## Installation
+
+```bash
+pip install user-intent-discovery              # library + remote clients
+pip install "user-intent-discovery[ui]"        # + FastAPI service and browser UI
+```
+
+Requires Python 3.10+.
+
+## Library usage
+
+```python
+from user_intent_discovery import TopicClusterer
+
+questions = [
+    "How do I reset my password?",
+    "I forgot my password, help",
+    "What are your business hours?",
+    "When are you open?",
+    # ...
+]
+
+clusterer = TopicClusterer(min_cluster_size=3)
+result = clusterer.fit(questions)
+
+print(f"Found {result.metrics.n_clusters} clusters "
+      f"({result.metrics.n_noise} noise points)")
+
+for cluster_id in result.top_k_clusters:
+    info = result.clusters[cluster_id]
+    print(f"\nCluster {cluster_id} ({info.size} items):")
+    for rep in info.representatives:
+        print(f"  - {rep.text}")
+```
+
+### With summarization
+
+Summarization needs a running [Ollama](https://ollama.com) server:
+
+```python
+from user_intent_discovery import TopicClusterer
+from user_intent_discovery.summarization import OllamaSummarizer
+
+clusterer = TopicClusterer(
+    min_cluster_size=3,
+    summarizer=OllamaSummarizer(model="llama3.2"),
+)
+result = clusterer.fit(questions)
+
+for cluster_id, question in (result.summaries or {}).items():
+    print(f"Cluster {cluster_id}: {question}")
+```
+
+## Split-compute across machines
+
+The pipeline has four stages and each is behind a protocol (`Embedder`, `Reducer`, `Clusterer`, `Summarizer`). Every protocol has a local implementation and a remote one — `RemoteEmbedder`, `RemoteReducer`, `RemoteClusterer`, `RemoteSummarizer` — that talks to a running `user-intent-discovery` server. Any stage the developer doesn't inject falls back to the local default, so mix-and-match is free.
+
+**All-remote** (laptop only orchestrates; every heavy stage runs elsewhere):
+
+```python
+from user_intent_discovery import TopicClusterer, remote_stages
+
+stages = remote_stages(
+    "http://gpu-box:8000",
+    cluster_dim=5, viz_dim=3,
+    min_cluster_size=3,
+    api_key="s3cret",         # optional; matched against the server's --api-key
+)
+result = TopicClusterer(**stages).fit(questions)
+```
+
+**Selective remote** (embed + summarize remote, UMAP + HDBSCAN local):
+
+```python
+from user_intent_discovery import TopicClusterer, RemoteEmbedder, RemoteSummarizer
+
+clusterer = TopicClusterer(
+    embedder   = RemoteEmbedder("http://gpu-box:8000"),
+    summarizer = RemoteSummarizer("http://gpu-box:8000", model="llama3.2"),
+    min_cluster_size=3,   # UMAP + HDBSCAN kwargs still apply to local defaults
+)
+result = clusterer.fit(questions)
+```
+
+The wire format is JSON (nested float lists). It is fine for tens of thousands of items; a binary format is on the v2 roadmap.
+
+### One-shot remote (no local pipeline)
+
+If you only want to POST texts to a server and get the full result back — no injection, no mix-and-match — use `TopicClustererClient`:
+
+```python
+from user_intent_discovery import TopicClustererClient
+
+client = TopicClustererClient("http://gpu-box:8000")
+result = client.fit(questions, min_cluster_size=3)   # returns a dict
+print(result["metrics"]["n_clusters"])
+```
+
+It only depends on `requests`, so it's the right choice for machines that can't install the ML stack.
+
+## Web service and UI
+
+Installed with the `[ui]` extra:
+
+```bash
+user-intent-discovery serve                                    # http://127.0.0.1:8000
+user-intent-discovery serve --port 9000 --ollama-model llama3.2
+user-intent-discovery serve --no-summarizer                    # UI summarize tab greyed out
+
+# production-ish
+user-intent-discovery serve \
+    --host 0.0.0.0 --port 8000 \
+    --api-key "$(openssl rand -hex 16)" \
+    --cors-origin https://app.example.com \
+    --cors-origin https://staging.example.com
+```
+
+Open the URL in a browser to paste questions, tune parameters, view the 3D cluster map, and summarize clusters.
+
+### API endpoints
+
+| Method | Path         | Purpose                                      |
+|--------|--------------|----------------------------------------------|
+| `POST` | `/ingest`    | Fetch texts from an external URL server-side |
+| `POST` | `/embed`     | Texts to embedding vectors                   |
+| `POST` | `/reduce`    | Vectors to reduced coordinates               |
+| `POST` | `/cluster`   | Coordinates to labels + metrics              |
+| `POST` | `/pipeline`  | One-shot: texts to full result               |
+| `POST` | `/summarize` | Cluster representatives to a question        |
+| `GET`  | `/health`    | Status + `summarizer_available` + `auth_required` |
+| `GET`  | `/`          | The browser UI                               |
+
+The staged endpoints let other apps plug in at a single stage; `/pipeline` is the convenience path the UI uses.
+
+### `/ingest` — fetch questions from your backend
+
+The browser can't fetch cross-origin URLs (CORS) and can't inject auth headers safely, so this endpoint runs the fetch server-side and hands the extracted texts back. The UI's **Fetch from URL** button uses this route.
+
+```bash
+curl -sX POST http://127.0.0.1:8000/ingest \
+  -H 'Content-Type: application/json' \
+  -d '{
+        "url":     "https://chatbot.example.com/api/unanswered",
+        "headers": {"Authorization": "Bearer '"$CHATBOT_TOKEN"'"}
+      }'
+# => {"texts": ["q1","q2",...], "count": 42}
+```
+
+Accepted upstream response shapes (auto-detected):
+
+- JSON list of strings: `["q1", "q2"]`
+- JSON list of objects, keys tried in order: `text`, `question`, `prompt`, `query`, `content`
+- JSON object with a list under `questions` / `texts` / `prompts` / `queries` / `items` / `data`
+- Plain text — split on newlines and commas
+
+Errors: `400` for a non-http(s) URL, `413` if the upstream body exceeds 10 MB, `502` on any upstream network failure, `422` if the body has no extractable texts.
+
+### Auth and CORS
+
+- **`--api-key VALUE`** (or `USER_INTENT_DISCOVERY_API_KEY` env var). When set, every compute endpoint requires `X-API-Key: VALUE`. `/health` and `/` stay open, and `/health` reports `auth_required: true` so clients can adapt.
+- **`--cors-origin URL`** (repeatable). Omit for permissive `*` (dev only); set explicit origins in production.
+
+### Input caps
+
+The server rejects over-large requests at the schema layer with HTTP 422, before any pipeline work:
+
+| Cap                          | Default   | Applies to                          |
+|------------------------------|-----------|-------------------------------------|
+| `MAX_TEXTS`                  | 20,000    | `/embed`, `/pipeline` text lists    |
+| `MAX_TEXT_LENGTH`            | 5,000     | per-text character length           |
+| `MAX_VECTORS`                | 50,000    | `/reduce`, `/cluster` inputs        |
+| `MAX_URL_LENGTH`             | 2,048     | `/ingest` url field                 |
+| `MAX_INGEST_BODY_BYTES`      | 10 MB     | `/ingest` upstream body             |
+| `MAX_CLUSTERS_PER_SUMMARIZE` | 500       | `/summarize` cluster count          |
+| `MAX_REPS_PER_CLUSTER`       | 100       | representatives per cluster         |
+
+Bump the constants in `user_intent_discovery/api/schemas.py` if a real workload legitimately needs more.
+
+## Key parameters
+
+| Parameter | Default | Notes |
+|-----------|---------|-------|
+| `min_cluster_size` | `5` | Smallest group that counts as a cluster. Lower it for small corpora. |
+| `cluster_dim` | `5` | UMAP dimensions clustered on. |
+| `umap_n_neighbors` | `15` | Lower = more local structure (helps on small datasets). |
+| `cluster_selection_method` | `"eom"` | `"leaf"` yields more, finer clusters. |
+| `top_n_per_cluster` | `5` | Representatives kept per cluster. |
+| `top_k_clusters` | `None` | Limit to the K largest clusters. |
+| `viz_dim` | `3` | Visualization dimensions; `0` skips it. |
+| `random_state` | `42` | `None` = faster but non-reproducible. |
+| `embedder`, `cluster_reducer`, `viz_reducer`, `clusterer`, `summarizer` | `None` | Inject any stage to override the local default. |
+
+## Reproducibility vs. speed
+
+By default `random_state=42`, so runs are reproducible but UMAP is single-threaded. Pass `random_state=None` for faster, multi-threaded, non-deterministic runs.
+
+## Errors
+
+Every exception derives from `ToolDiscoveryError` so a single `except` clause catches everything. Narrow subclasses: `EmbeddingError`, `ClusteringError`, `SummarizationError`, `OllamaConnectionError`. Over HTTP: `OllamaConnectionError` → 503, other `ToolDiscoveryError` → 500, schema violations → 422.
+
+## Non-goals (v1)
+
+To keep the first version focused: HDBSCAN only (no KMeans/Agglomerative); UMAP only (no PCA/t-SNE); Ollama only for summarization; embeddings are always computed in-package (no bring-your-own-vectors); nearest-centroid is the only noise-reassignment method; the API is stateless (no server-side sessions).
+
+Planned for v2: text-source abstraction (pull questions from an authenticated endpoint or receive them via webhook), scheduled auto-runs, and a binary wire format for the remote stage clients.
+
+## Development
+
+```bash
+git clone https://nithinvikasav@bitbucket.org/foxsense/user-intent-discovery.git
+cd user-intent-discovery
+poetry install --extras ui
+poetry run pytest -m "not integration"    # skip tests that need a running Ollama
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

user_intent_discovery-1.1.0/pyproject.toml

@@ -0,0 +1,96 @@
+[tool.poetry]
+name = "user-intent-discovery"
+version = "1.1.0"
+description = "Cluster chatbot questions by semantic similarity and surface the most representative ones, with optional local-LLM summarization. Each pipeline stage (embed, reduce, cluster, summarize) can be run locally or against a remote server."
+authors = ["Nithin Vikas AV <nithinvikas.av@foxsense.io>"]
+license = "MIT"
+readme = "README.md"
+packages = [{ include = "user_intent_discovery", from = "src" }]
+keywords = ["clustering", "embeddings", "umap", "hdbscan", "chatbot", "topic-modeling", "sentence-transformers", "ollama"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Text Processing :: Linguistic",
+    "Typing :: Typed",
+]
+
+# TODO: fill in with your actual GitHub handle (no spaces) before publishing.
+homepage = "https://bitbucket.org/foxsense/user-intent-discovery"
+repository = "https://bitbucket.org/foxsense/user-intent-discovery"
+documentation = "https://bitbucket.org/foxsense/user-intent-discovery"
+
+[tool.poetry.dependencies]
+python = ">=3.10,<4.0"
+numpy = ">=1.24"
+sentence-transformers = ">=2.5"
+umap-learn = ">=0.5.5"
+hdbscan = ">=0.8.33"
+scikit-learn = ">=1.3"
+requests = ">=2.31"
+# --- ui extra (optional) ---
+fastapi = { version = ">=0.110", optional = true }
+uvicorn = { version = ">=0.29", extras = ["standard"], optional = true }
+
+[tool.poetry.extras]
+ui = ["fastapi", "uvicorn"]
+
+[tool.poetry.group.dev.dependencies]
+pytest = "*"
+pytest-cov = "*"
+black = "*"
+isort = "*"
+flake8 = "*"
+mypy = "*"
+pre-commit = "*"
+sphinx = "*"
+sphinx-rtd-theme = "*"
+httpx = "*"
+
+[tool.poetry.scripts]
+user-intent-discovery = "user_intent_discovery.api.cli:main"
+
+[build-system]
+requires = ["poetry-core>=1.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+# ---------------- tool configs ----------------
+
+[tool.black]
+line-length = 88
+target-version = ["py310"]
+
+[tool.isort]
+profile = "black"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = [
+    "integration: tests needing a running Ollama server (skip with -m 'not integration')",
+]
+
+[tool.coverage.run]
+source = ["user_intent_discovery"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+files = ["src"]
+
+# Third-party libs ship no type stubs — don't let strict mode fail on them.
+[[tool.mypy.overrides]]
+module = ["umap.*", "hdbscan.*", "sentence_transformers.*", "sklearn.*"]
+ignore_missing_imports = true
+
+# Relax strictness on the test suite.
+[[tool.mypy.overrides]]
+module = "tests.*"
+disallow_untyped_defs = false
+disallow_incomplete_defs = false

user_intent_discovery-1.1.0/src/user_intent_discovery/__init__.py

@@ -0,0 +1,46 @@
+"""user-intent-discovery: cluster chatbot questions and surface representative ones.
+
+Public API:
+    TopicClusterer   -- the orchestrator; call .fit(texts) to get results.
+    ClusteringResult -- the dataclass returned by fit().
+
+Split-compute across machines: pass any of the ``Remote*`` stages into
+``TopicClusterer`` (or use :func:`user_intent_discovery.remote.remote_stages` to build
+all four at once) to run individual stages on a different server::
+
+    from user_intent_discovery import TopicClusterer
+    from user_intent_discovery.remote import remote_stages
+
+    stages = remote_stages("http://gpu-box:8000", cluster_dim=5, viz_dim=3)
+    result = TopicClusterer(**stages, min_cluster_size=3).fit(questions)
+
+Everything else (custom embedders, summarizers, the API app factory) lives in
+submodules and can be imported directly, e.g.::
+
+    from user_intent_discovery.summarization import OllamaSummarizer
+    from user_intent_discovery.api import create_app
+"""
+
+from .client import TopicClustererClient
+from .pipeline import TopicClusterer
+from .remote import (
+    RemoteClusterer,
+    RemoteEmbedder,
+    RemoteReducer,
+    RemoteSummarizer,
+    remote_stages,
+)
+from .results import ClusteringResult
+
+__all__ = [
+    "TopicClusterer",
+    "TopicClustererClient",
+    "ClusteringResult",
+    "RemoteEmbedder",
+    "RemoteReducer",
+    "RemoteClusterer",
+    "RemoteSummarizer",
+    "remote_stages",
+]
+
+__version__ = "1.1.0"