kindred-keeper 0.1.0__tar.gz

kindred_keeper-0.1.0/LICENSE

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

kindred_keeper-0.1.0/MANIFEST.in

@@ -0,0 +1,2 @@
+recursive-include kindred_keeper/static *
+recursive-include examples *

kindred_keeper-0.1.0/PKG-INFO

@@ -0,0 +1,113 @@
+Metadata-Version: 2.4
+Name: kindred-keeper
+Version: 0.1.0
+Summary: A local-first relationship memory desk for thoughtful follow-ups.
+Author: Kindred Keeper maintainers
+License-Expression: MIT
+Keywords: relationships,personal-crm,local-first,planning
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Kindred Keeper
+
+Kindred Keeper is a private, local-first relationship memory desk for thoughtful follow-ups. Add people you care about, jot down small details after calls or visits, and it builds a practical plan for check-ins, promises, birthdays, and meaningful moments.
+
+Everything runs on your computer with the Python standard library. There is no account, upload, telemetry, or hosted database.
+
+![Kindred Keeper dashboard](docs/screenshot.svg)
+
+## Features
+
+- Local browser app backed by a JSON file on your machine.
+- Contact profiles with relationship, cadence, interests, and last touchpoint.
+- Note analysis that extracts interests, promises, dates, sentiment, and relationship signals.
+- Lightweight local classifier trained on celebration, support, commitment, and interest examples.
+- Planning workflow that ranks overdue follow-ups, open commitments, and upcoming dates.
+- Suggested message drafts that stay specific to the person and the reason for reaching out.
+- Copy-ready weekly relationship plan.
+- Seeded demo workspace so the full workflow is visible on first launch.
+
+## Installation
+
+Requirements:
+
+- Python 3.10 or newer
+
+```bash
+git clone https://github.com/iwaheedsattar/kindred-keeper.git
+cd kindred-keeper
+python3 app.py
+```
+
+Open [http://127.0.0.1:8768](http://127.0.0.1:8768).
+
+To use a custom local data file:
+
+```bash
+python3 app.py --data ./my-kindred-data.json
+```
+
+## Example Usage
+
+1. Launch the app with `python3 app.py`.
+2. Review the seeded relationship plan.
+3. Add a person you want to stay close to.
+4. Save a note such as:
+
+```text
+Lina loves Korean food and ceramics. Promised to send the podcast link. Her recital is Jul 16.
+```
+
+5. Review the follow-up plan and copy the weekly plan into your calendar or notes app.
+
+## How It Works
+
+Kindred Keeper uses a small local planning pipeline:
+
+1. Notes are tokenized and scored with a compact multinomial classifier.
+2. Extractors find promises, dates, and interest phrases.
+3. Each contact receives warmth and attention scores based on cadence, open commitments, support signals, and recent notes.
+4. The planner ranks next actions and writes a short message draft for each one.
+
+The pipeline is intentionally small and transparent so personal relationship notes stay local and understandable.
+
+## Development
+
+```bash
+python3 -m unittest discover -s tests
+python3 app.py --no-open --data ./.kindred-keeper-data.json
+```
+
+Package build:
+
+```bash
+python3 -m build --no-isolation
+```
+
+## Project Layout
+
+- `kindred_keeper/engine.py` contains note analysis, scoring, and planning.
+- `kindred_keeper/storage.py` manages the local JSON workspace.
+- `kindred_keeper/server.py` serves the local web app and JSON API.
+- `static/` contains the browser UI.
+- `tests/` covers extraction, summary scoring, and action planning.
+
+## Roadmap
+
+- Calendar export for planned check-ins.
+- Import from a simple contacts CSV.
+- Reminder notifications in a desktop wrapper.
+- Optional encrypted data file.
+- Better recurring-date handling for birthdays and anniversaries.
+
+## License
+
+MIT

kindred_keeper-0.1.0/README.md

@@ -0,0 +1,95 @@
+# Kindred Keeper
+
+Kindred Keeper is a private, local-first relationship memory desk for thoughtful follow-ups. Add people you care about, jot down small details after calls or visits, and it builds a practical plan for check-ins, promises, birthdays, and meaningful moments.
+
+Everything runs on your computer with the Python standard library. There is no account, upload, telemetry, or hosted database.
+
+![Kindred Keeper dashboard](docs/screenshot.svg)
+
+## Features
+
+- Local browser app backed by a JSON file on your machine.
+- Contact profiles with relationship, cadence, interests, and last touchpoint.
+- Note analysis that extracts interests, promises, dates, sentiment, and relationship signals.
+- Lightweight local classifier trained on celebration, support, commitment, and interest examples.
+- Planning workflow that ranks overdue follow-ups, open commitments, and upcoming dates.
+- Suggested message drafts that stay specific to the person and the reason for reaching out.
+- Copy-ready weekly relationship plan.
+- Seeded demo workspace so the full workflow is visible on first launch.
+
+## Installation
+
+Requirements:
+
+- Python 3.10 or newer
+
+```bash
+git clone https://github.com/iwaheedsattar/kindred-keeper.git
+cd kindred-keeper
+python3 app.py
+```
+
+Open [http://127.0.0.1:8768](http://127.0.0.1:8768).
+
+To use a custom local data file:
+
+```bash
+python3 app.py --data ./my-kindred-data.json
+```
+
+## Example Usage
+
+1. Launch the app with `python3 app.py`.
+2. Review the seeded relationship plan.
+3. Add a person you want to stay close to.
+4. Save a note such as:
+
+```text
+Lina loves Korean food and ceramics. Promised to send the podcast link. Her recital is Jul 16.
+```
+
+5. Review the follow-up plan and copy the weekly plan into your calendar or notes app.
+
+## How It Works
+
+Kindred Keeper uses a small local planning pipeline:
+
+1. Notes are tokenized and scored with a compact multinomial classifier.
+2. Extractors find promises, dates, and interest phrases.
+3. Each contact receives warmth and attention scores based on cadence, open commitments, support signals, and recent notes.
+4. The planner ranks next actions and writes a short message draft for each one.
+
+The pipeline is intentionally small and transparent so personal relationship notes stay local and understandable.
+
+## Development
+
+```bash
+python3 -m unittest discover -s tests
+python3 app.py --no-open --data ./.kindred-keeper-data.json
+```
+
+Package build:
+
+```bash
+python3 -m build --no-isolation
+```
+
+## Project Layout
+
+- `kindred_keeper/engine.py` contains note analysis, scoring, and planning.
+- `kindred_keeper/storage.py` manages the local JSON workspace.
+- `kindred_keeper/server.py` serves the local web app and JSON API.
+- `static/` contains the browser UI.
+- `tests/` covers extraction, summary scoring, and action planning.
+
+## Roadmap
+
+- Calendar export for planned check-ins.
+- Import from a simple contacts CSV.
+- Reminder notifications in a desktop wrapper.
+- Optional encrypted data file.
+- Better recurring-date handling for birthdays and anniversaries.
+
+## License
+
+MIT

kindred_keeper-0.1.0/examples/notes.txt

@@ -0,0 +1,3 @@
+Maya loves ceramics and jazz. Her studio show opens Jul 8. Promised to send the harbour walk photos.
+Omar sounded stressed after the move. Need to call about helping set up the kitchen shelves.
+Nora likes gardening and asked about tomato seedlings. Birthday is Aug 12.

kindred_keeper-0.1.0/kindred_keeper/__init__.py

@@ -0,0 +1,3 @@
+"""Kindred Keeper local relationship planning package."""
+
+__all__ = ["engine", "storage"]

kindred_keeper-0.1.0/kindred_keeper/engine.py

@@ -0,0 +1,360 @@
+from __future__ import annotations
+
+from collections import Counter, defaultdict
+from dataclasses import dataclass
+from datetime import date, datetime, timedelta
+import math
+import re
+from typing import Iterable
+
+
+STOPWORDS = {
+    "a",
+    "and",
+    "are",
+    "as",
+    "at",
+    "be",
+    "for",
+    "from",
+    "has",
+    "have",
+    "i",
+    "in",
+    "is",
+    "it",
+    "of",
+    "on",
+    "or",
+    "she",
+    "he",
+    "they",
+    "the",
+    "their",
+    "to",
+    "we",
+    "with",
+    "you",
+}
+
+TRAINING = {
+    "celebration": [
+        "birthday dinner graduation promoted won anniversary new baby congratulations",
+        "party celebrate engagement wedding milestone good news proud achievement",
+        "finished marathon got accepted opening night launch recital performance",
+    ],
+    "support": [
+        "surgery sick hospital grief difficult stressed burned out tired lonely",
+        "lost job breakup funeral caring parent overwhelmed anxious worried",
+        "treatment recovering diagnosis trouble moving house emergency",
+    ],
+    "commitment": [
+        "promised send introduce follow up remind book tickets share recipe",
+        "owed call lend return plan coffee dinner help review",
+        "need to check ask about send photos schedule visit",
+    ],
+    "interest": [
+        "loves gardening jazz hiking chess cooking photography soccer books",
+        "favorite restaurant tea dogs movies ceramics cycling baking",
+        "interested in travel history podcasts painting theatre yoga",
+    ],
+}
+
+POSITIVE_WORDS = {
+    "happy",
+    "excited",
+    "proud",
+    "great",
+    "good",
+    "celebrate",
+    "better",
+    "enjoyed",
+    "love",
+    "kind",
+    "fun",
+}
+NEGATIVE_WORDS = {
+    "sad",
+    "hard",
+    "difficult",
+    "sick",
+    "stressed",
+    "worried",
+    "lonely",
+    "tired",
+    "overwhelmed",
+    "grief",
+    "emergency",
+    "anxious",
+}
+
+TOKEN_RE = re.compile(r"[a-z][a-z'-]{1,}")
+DATE_RE = re.compile(
+    r"\b(?:(jan|feb|mar|apr|may|jun|jul|aug|sep|sept|oct|nov|dec)[a-z]*\.?\s+(\d{1,2})|(\d{4})-(\d{2})-(\d{2}))\b",
+    re.I,
+)
+PROMISE_RE = re.compile(
+    r"\b(?:promised|promise|owe|owed|need to|should|remember to|follow up|send|share|introduce|book|call|text|visit)\b[^.!\n]{0,90}",
+    re.I,
+)
+INTEREST_RE = re.compile(
+    r"\b(?:loves?|likes?|favorite|into|interested in|enjoys?)\s+([^.;\n]{2,80})",
+    re.I,
+)
+
+
+@dataclass
+class Signal:
+    label: str
+    score: float
+    evidence: str
+
+
+@dataclass
+class PlannedAction:
+    contact_id: str
+    contact_name: str
+    title: str
+    reason: str
+    priority: int
+    due: str
+    tone: str
+
+
+def tokenize(text: str) -> list[str]:
+    return [t for t in TOKEN_RE.findall(text.lower()) if t not in STOPWORDS]
+
+
+class NaiveSignalClassifier:
+    def __init__(self) -> None:
+        self.label_counts: dict[str, Counter[str]] = {}
+        self.label_totals: dict[str, int] = {}
+        self.vocabulary: set[str] = set()
+        for label, examples in TRAINING.items():
+            counter: Counter[str] = Counter()
+            for example in examples:
+                counter.update(tokenize(example))
+            self.label_counts[label] = counter
+            self.label_totals[label] = sum(counter.values())
+            self.vocabulary.update(counter.keys())
+
+    def score(self, text: str) -> list[Signal]:
+        tokens = tokenize(text)
+        if not tokens:
+            return []
+        vocab_size = max(len(self.vocabulary), 1)
+        raw: dict[str, float] = {}
+        for label, counts in self.label_counts.items():
+            total = self.label_totals[label] + vocab_size
+            value = math.log(1 / len(self.label_counts))
+            for token in tokens:
+                value += math.log((counts[token] + 1) / total)
+            raw[label] = value
+        peak = max(raw.values())
+        exp = {label: math.exp(value - peak) for label, value in raw.items()}
+        total_exp = sum(exp.values()) or 1.0
+        ranked = []
+        for label, value in exp.items():
+            score = value / total_exp
+            if score >= 0.18:
+                ranked.append(Signal(label, round(score, 3), _evidence_for(label, text)))
+        return sorted(ranked, key=lambda item: item.score, reverse=True)
+
+
+CLASSIFIER = NaiveSignalClassifier()
+
+
+def _evidence_for(label: str, text: str) -> str:
+    words = set(TRAINING[label][0].split())
+    fragments = re.split(r"(?<=[.!?])\s+|\n+", text.strip())
+    for fragment in fragments:
+        if words.intersection(tokenize(fragment)):
+            return fragment.strip()[:180]
+    return text.strip()[:180]
+
+
+def sentiment_score(text: str) -> int:
+    tokens = tokenize(text)
+    positives = sum(1 for token in tokens if token in POSITIVE_WORDS)
+    negatives = sum(1 for token in tokens if token in NEGATIVE_WORDS)
+    return max(-5, min(5, positives - negatives))
+
+
+def extract_interests(text: str) -> list[str]:
+    found: list[str] = []
+    for match in INTEREST_RE.finditer(text):
+        phrase = re.sub(r"\band\b", ",", match.group(1), flags=re.I)
+        for part in re.split(r"[,/]| and ", phrase):
+            cleaned = re.sub(r"[^a-zA-Z0-9 '-]", "", part).strip().lower()
+            if 2 <= len(cleaned) <= 36:
+                found.append(cleaned)
+    return _unique(found)[:8]
+
+
+def extract_promises(text: str) -> list[str]:
+    promises = []
+    for match in PROMISE_RE.finditer(text):
+        item = re.sub(r"\s+", " ", match.group(0)).strip(" .")
+        if len(item) > 5:
+            promises.append(item[0].upper() + item[1:])
+    return _unique(promises)[:8]
+
+
+def extract_dates(text: str, today: date | None = None) -> list[str]:
+    today = today or date.today()
+    dates: list[str] = []
+    month_lookup = {
+        "jan": 1,
+        "feb": 2,
+        "mar": 3,
+        "apr": 4,
+        "may": 5,
+        "jun": 6,
+        "jul": 7,
+        "aug": 8,
+        "sep": 9,
+        "sept": 9,
+        "oct": 10,
+        "nov": 11,
+        "dec": 12,
+    }
+    for match in DATE_RE.finditer(text):
+        if match.group(1):
+            month = month_lookup[match.group(1).lower()[:3]]
+            day = int(match.group(2))
+            year = today.year
+            candidate = date(year, month, day)
+            if candidate < today - timedelta(days=7):
+                candidate = date(year + 1, month, day)
+        else:
+            candidate = date(int(match.group(3)), int(match.group(4)), int(match.group(5)))
+        dates.append(candidate.isoformat())
+    return _unique(dates)[:8]
+
+
+def analyze_note(text: str, today: date | None = None) -> dict:
+    signals = CLASSIFIER.score(text)
+    return {
+        "signals": [signal.__dict__ for signal in signals],
+        "sentiment": sentiment_score(text),
+        "interests": extract_interests(text),
+        "promises": extract_promises(text),
+        "dates": extract_dates(text, today=today),
+    }
+
+
+def build_contact_summary(contact: dict, notes: Iterable[dict], today: date | None = None) -> dict:
+    today = today or date.today()
+    notes = sorted(notes, key=lambda row: row.get("created_at", ""), reverse=True)
+    all_interests: list[str] = list(contact.get("interests", []))
+    open_promises: list[str] = []
+    next_dates: list[str] = []
+    signal_counts: Counter[str] = Counter()
+    sentiment_total = 0
+    for note in notes:
+        analysis = note.get("analysis", {})
+        all_interests.extend(analysis.get("interests", []))
+        open_promises.extend(analysis.get("promises", []))
+        next_dates.extend(d for d in analysis.get("dates", []) if d >= today.isoformat())
+        sentiment_total += int(analysis.get("sentiment", 0))
+        for signal in analysis.get("signals", []):
+            signal_counts[signal["label"]] += 1
+    last_seen = contact.get("last_seen") or (notes[0]["created_at"][:10] if notes else "")
+    days_since = _days_since(last_seen, today)
+    cadence = int(contact.get("cadence_days") or 30)
+    warmth = max(0, min(100, 74 - min(days_since, 90) + min(len(notes) * 4, 18) + sentiment_total * 3))
+    attention = max(0, min(100, int((days_since / max(cadence, 1)) * 55) + len(open_promises) * 12 + signal_counts["support"] * 14))
+    return {
+        "id": contact["id"],
+        "name": contact["name"],
+        "relationship": contact.get("relationship", ""),
+        "last_seen": last_seen,
+        "days_since": days_since,
+        "cadence_days": cadence,
+        "warmth": warmth,
+        "attention": attention,
+        "interests": _unique(all_interests)[:8],
+        "open_promises": _unique(open_promises)[:6],
+        "upcoming_dates": sorted(_unique(next_dates))[:4],
+        "top_signals": signal_counts.most_common(4),
+        "note_count": len(notes),
+    }
+
+
+def plan_actions(contacts: list[dict], notes_by_contact: dict[str, list[dict]], today: date | None = None) -> list[PlannedAction]:
+    today = today or date.today()
+    actions: list[PlannedAction] = []
+    for contact in contacts:
+        summary = build_contact_summary(contact, notes_by_contact.get(contact["id"], []), today=today)
+        due_base = today + timedelta(days=max(0, min(14, summary["cadence_days"] - summary["days_since"])))
+        if summary["open_promises"]:
+            actions.append(
+                PlannedAction(
+                    contact["id"],
+                    contact["name"],
+                    summary["open_promises"][0],
+                    "You wrote down a commitment that is still worth closing.",
+                    min(100, summary["attention"] + 25),
+                    today.isoformat(),
+                    "clear and reliable",
+                )
+            )
+        if summary["upcoming_dates"]:
+            event_date = datetime.fromisoformat(summary["upcoming_dates"][0]).date()
+            days_until = (event_date - today).days
+            if 0 <= days_until <= 21:
+                actions.append(
+                    PlannedAction(
+                        contact["id"],
+                        contact["name"],
+                        f"Prepare a note for {event_date.strftime('%b %-d')}",
+                        "An upcoming date appeared in your notes.",
+                        85 - days_until,
+                        max(today, event_date - timedelta(days=3)).isoformat(),
+                        "warm and specific",
+                    )
+                )
+        if summary["attention"] >= 45:
+            interest = summary["interests"][0] if summary["interests"] else contact.get("relationship", "life")
+            actions.append(
+                PlannedAction(
+                    contact["id"],
+                    contact["name"],
+                    f"Send a check-in about {interest}",
+                    f"It has been {summary['days_since']} days since the last touchpoint.",
+                    summary["attention"],
+                    due_base.isoformat(),
+                    "low-pressure",
+                )
+            )
+    actions.sort(key=lambda item: (-item.priority, item.due, item.contact_name))
+    return actions[:10]
+
+
+def suggest_message(contact: dict, summary: dict, action: PlannedAction) -> str:
+    interest = summary["interests"][0] if summary["interests"] else "how things are going"
+    if "Prepare a note" in action.title:
+        return f"Hi {contact['name'].split()[0]}, I remembered {action.title.replace('Prepare a note for ', '')} is coming up and wanted to send something thoughtful. Hope it is a good one."
+    if summary["open_promises"] and action.title == summary["open_promises"][0]:
+        return f"Hi {contact['name'].split()[0]}, I remembered I said I would {action.title[0].lower() + action.title[1:]}. I am on it and wanted to close the loop."
+    return f"Hi {contact['name'].split()[0]}, I was thinking about you and {interest}. How has that been going lately?"
+
+
+def _days_since(value: str, today: date) -> int:
+    if not value:
+        return 999
+    try:
+        return max(0, (today - datetime.fromisoformat(value[:10]).date()).days)
+    except ValueError:
+        return 999
+
+
+def _unique(items: Iterable[str]) -> list[str]:
+    seen = set()
+    result = []
+    for item in items:
+        key = item.lower().strip()
+        if key and key not in seen:
+            seen.add(key)
+            result.append(item.strip())
+    return result