deaf-intelligence 1.0.1

package/LICENSE.md

@@ -0,0 +1,77 @@
+# Functional Source License, Version 1.1, Apache 2.0 Future License
+
+## Abbreviation
+
+FSL-1.1-Apache-2.0
+
+## Notice
+
+Copyright 2026 Karel "KAYO" Dittrich / DEAF (deaf.audio)
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+Karel "KAYO" Dittrich / DEAF (deaf.audio)
+
+### The Software
+
+Artist-OS MCP Server — Spotify artist intelligence and archival tool.
+
+### Use Grant
+
+Subject to the conditions below, we hereby grant you a non-exclusive,
+royalty-free, worldwide, non-sublicensable, non-transferable license to
+use, copy, modify, and distribute the Software, in each case subject to
+the limitations and conditions below.
+
+### Limitations
+
+You may NOT use the Software:
+
+1. **As a Competing Product.** You may not provide the Software to third
+   parties as a hosted or managed service that allows such third parties
+   to use the Software's substantial functionality. This limitation does
+   not apply if you are using the Software for internal, non-commercial
+   purposes or for personal use.
+
+2. **To Circumvent Licensing.** You may not remove or alter any licensing,
+   copyright, or other notices of the Licensor in the Software.
+
+### Change Date
+
+Two (2) years from the date of each release of the Software.
+
+### Change License
+
+Apache License, Version 2.0
+
+### Future License
+
+On the Change Date, this license converts to the Change License, and
+all Limitations cease to apply. This is automatic — no action is required
+by you or us.
+
+### No Warranty
+
+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.
+
+---
+
+## About FSL
+
+The Functional Source License (FSL) was created by Sentry. It is designed
+to give developers freedom to use, modify, and learn from source code,
+while protecting the licensor from competitors who would take their work
+and offer it as a competing hosted service.
+
+After 2 years, the code becomes fully open source under Apache 2.0.
+
+Learn more: https://fsl.software

package/README.md

@@ -0,0 +1,75 @@
+# DEAF Intelligence
+
+> Your Spotify career intelligence layer. Track any artist, build history, get insights.
+
+## What It Does
+
+MCP server that turns Spotify data into career intelligence. No API keys, no login, no setup.
+
+Give it a Spotify URL — it archives the full public profile, computes intelligence metrics, and builds a history that Spotify deletes after 2 years.
+
+## Install
+
+### Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "deaf-intelligence": {
+      "command": "npx",
+      "args": ["-y", "deaf-intelligence"]
+    }
+  }
+}
+```
+
+### Claude Code
+
+```bash
+claude mcp add deaf-intelligence -- npx -y deaf-intelligence
+```
+
+## Tools
+
+| Tool | What |
+|------|------|
+| `track_artist` | Start tracking — scrapes full profile, all tracks, images |
+| `show_stats` | Current metrics, history, trends |
+| `show_tracks` | All tracks sorted by streams, velocity, date |
+| `show_insights` | Intelligence report — velocity ranking, catalog health, release cadence, milestones, recommendations |
+| `show_cities` | Top listener cities |
+| `show_related` | Related artists |
+| `list_artists` | All tracked artists |
+| `run_scrape` | Add new daily snapshot |
+
+## Data
+
+Everything stored locally on your machine:
+- Full discography with play counts
+- Popularity score (0-100) per track
+- Monthly listeners, followers, world rank
+- Top cities, related artists, playlists
+- Profile and cover art images (archived)
+
+Run daily to build history. The longer you use it, the more patterns emerge.
+
+## Why
+
+- **Spotify deletes data after 2 years.** We keep it forever.
+- **MCP-native.** Ask questions in natural language.
+- **Intelligence, not just numbers.** Velocity ranking, catalog health, milestone projections, actionable recommendations.
+
+## Requirements
+
+- Node.js 20+
+- System Chrome or Edge (for scraping)
+
+## License
+
+FSL-1.1-Apache-2.0 (Functional Source License)
+
+## Links
+
+- Website: [deaf.audio](https://deaf.audio)

package/dist/constrained-disagg.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Constrained Temporal Disaggregation with Continuity
+ *
+ * Solves: given N days split into EST [0..B-1] and S4A_PREV [B..N-1],
+ * produce daily values where:
+ *   - sum(EST) = estTotal
+ *   - sum(S4A_PREV) = prevAgg
+ *   - v[B-1] ≈ v[B]  (no jump at boundary)
+ *   - v[N-1] ≈ firstS4aVal (anchor at end)
+ *   - release spike preserved (Denton proportional)
+ *   - all values >= 0
+ *
+ * Method: Proportional Denton scaling + boundary blending + deficit absorption.
+ *
+ * Classical Denton/Chow-Lin handle EITHER sum OR endpoint constraints, not both.
+ * (Denton 1971, Dagum & Cholette 2006, Chow-Lin 1971 — all use a single
+ * aggregation matrix encoding one constraint type.)
+ *
+ * We solve the custom QP with dual constraints:
+ *   min  (y - s)' W (y - s)     [shape preservation]
+ *   s.t. sum(y) = T              [sum constraint]
+ *        y[n] = E                [endpoint constraint]
+ *        y >= 0                  [non-negativity]
+ *
+ * Practical implementation:
+ *   1. Build indicator shape s (spike + decay + ramp)
+ *   2. Proportional scale: y = s × (T / sum(s))  →  preserves spike ratios
+ *   3. Blend last K days toward endpoint E         →  smooth boundary
+ *   4. Absorb sum deficit into interior            →  exact sum
+ *
+ * References:
+ *   - Denton (1971), "Adjustment of Monthly or Quarterly Series to Annual Totals"
+ *   - Dagum & Cholette (2006), "Benchmarking, Temporal Distribution, and Reconciliation"
+ *   - Dergachev et al. (2019), "Analyzing the Spotify Top 200 Through a Point Process Lens"
+ *   - tempdisagg R package (Sax & Steiner, 2013)
+ */
+export interface DisaggInput {
+    /** Total days in both periods combined */
+    totalDays: number;
+    /** Index where S4A_PREV starts (= number of EST days) */
+    boundaryIdx: number;
+    /** Required sum of EST period */
+    estTotal: number;
+    /** Required sum of S4A_PREV period */
+    prevAgg: number;
+    /** Known daily value at day N (first real S4A day — the anchor) */
+    firstS4aVal: number;
+    /** Release date as day index (0-based from start). -1 if before range. */
+    releaseDayIdx: number;
+    /** Spike amplitude (0 = no spike) */
+    spikeA: number;
+    /** Spike decay rate (e.g. 0.05 for ~14d half-life) */
+    spikeLambda: number;
+    /** Baseline daily rate (catalog floor) */
+    baseline: number;
+}
+export interface DisaggOutput {
+    daily: number[];
+    boundaryValue: number;
+    estSum: number;
+    prevSum: number;
+    maxError: number;
+}
+export declare function constrainedDisaggregate(input: DisaggInput): DisaggOutput;
+export declare function roundWithDiffusion(values: number[]): number[];
+/**
+ * Largest Remainder rounding with pinned anchor.
+ * Pins values[anchorIdx] = anchorVal, then distributes (target - anchorVal)
+ * across remaining positions using Hamilton's method.
+ *
+ * Guarantees:
+ *   - result[anchorIdx] = anchorVal (exact)
+ *   - sum(result) = target (exact)
+ *   - each result[i] = floor(x[i]) or ceil(x[i])
+ */
+export declare function roundWithAnchor(values: number[], anchorIdx: number, anchorVal: number, explicitTarget?: number): number[];