pysince 0.1.0__tar.gz

pysince-0.1.0/PKG-INFO

@@ -0,0 +1,5 @@
+Metadata-Version: 2.4
+Name: pysince
+Version: 0.1.0
+Summary: Temporal context for LLM conversations
+Requires-Python: >=3.10

pysince-0.1.0/pyproject.toml

@@ -0,0 +1,16 @@
+[build-system]
+requires = ["setuptools>=64", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pysince"
+version = "0.1.0"
+description = "Temporal context for LLM conversations"
+requires-python = ">=3.10"
+dependencies = []
+
+[project.scripts]
+pysince = "since.cli:main"
+
+[tool.setuptools.packages.find]
+include = ["since*"]

pysince-0.1.0/pysince.egg-info/PKG-INFO

@@ -0,0 +1,5 @@
+Metadata-Version: 2.4
+Name: pysince
+Version: 0.1.0
+Summary: Temporal context for LLM conversations
+Requires-Python: >=3.10

pysince-0.1.0/pysince.egg-info/SOURCES.txt

@@ -0,0 +1,22 @@
+pyproject.toml
+pysince.egg-info/PKG-INFO
+pysince.egg-info/SOURCES.txt
+pysince.egg-info/dependency_links.txt
+pysince.egg-info/entry_points.txt
+pysince.egg-info/top_level.txt
+since/__init__.py
+since/cli.py
+since/core.py
+since/decorator.py
+since/format.py
+since/models.py
+since/stale_files.py
+since/store.py
+since/timeparse.py
+tests/test_decorator.py
+tests/test_format.py
+tests/test_integration.py
+tests/test_retrieval.py
+tests/test_stale_files.py
+tests/test_timeparse.py
+tests/test_ttl.py

pysince-0.1.0/pysince.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

pysince-0.1.0/pysince.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pysince = since.cli:main

pysince-0.1.0/pysince.egg-info/top_level.txt

@@ -0,0 +1 @@
+since

pysince-0.1.0/setup.cfg

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

pysince-0.1.0/since/__init__.py

@@ -0,0 +1,8 @@
+from .core import enrich_message, with_time
+from .decorator import since_time
+from .models import Message
+from .store import Store
+
+sense_time = since_time
+
+__all__ = ["Message", "Store", "enrich_message", "sense_time", "since_time", "with_time"]

pysince-0.1.0/since/cli.py

@@ -0,0 +1,101 @@
+from __future__ import annotations
+
+import argparse
+import datetime
+import sys
+from pathlib import Path
+
+from .core import with_time
+from .store import Store
+
+
+def cmd_enrich(args: argparse.Namespace) -> None:
+    store = Store(args.db)
+    messages = store.load_session(args.session_id)
+    if not messages:
+        print(f"Session '{args.session_id}' not found", file=sys.stderr)
+        sys.exit(1)
+
+    prompt = with_time(messages, store=store)
+    for entry in prompt:
+        print(f"[{entry['role']}]\n{entry['content']}\n")
+
+
+def cmd_search(args: argparse.Namespace) -> None:
+    store = Store(args.db)
+    messages = store.load_session(args.session_id)
+    if not messages:
+        print(f"Session '{args.session_id}' not found", file=sys.stderr)
+        sys.exit(1)
+
+    now = datetime.datetime.now(datetime.timezone.utc).replace(tzinfo=None)
+
+    if args.range:
+        parts = args.range.split()
+        if len(parts) == 2 and parts[1] in ("ago",):
+            try:
+                value = int(parts[0])
+            except ValueError:
+                print(f"Invalid range: {args.range}", file=sys.stderr)
+                sys.exit(1)
+            start = now - datetime.timedelta(days=value)
+        else:
+            try:
+                start = datetime.datetime.fromisoformat(args.range)
+            except ValueError:
+                print(f"Invalid range: {args.range}", file=sys.stderr)
+                sys.exit(1)
+        end = now
+        results = store.load_range(args.session_id, start, end)
+    else:
+        results = messages[-20:]
+
+    from .format import format_absolute
+    for m in results:
+        print(format_absolute(m))
+
+
+def cmd_stats(args: argparse.Namespace) -> None:
+    store = Store(args.db)
+    info = store.session_info(args.session_id)
+    if not info:
+        print(f"Session '{args.session_id}' not found", file=sys.stderr)
+        sys.exit(1)
+
+    now = datetime.datetime.now(datetime.timezone.utc).replace(tzinfo=None)
+    from .format import _format_timedelta_long
+    print(f"Session:      {args.session_id}")
+    print(f"Messages:     {info['count']}")
+    print(f"Started:      {info['first'].isoformat()}")
+    print(f"Last message: {info['last'].isoformat()}")
+    print(f"Duration:     {_format_timedelta_long(info['last'] - info['first'])}")
+    print(f"Age:          {_format_timedelta_long(now - info['first'])}")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(prog="since", description="Temporal context for LLM conversations")
+    parser.add_argument("--db", default="~/.ticks/store.db", type=str, help="SQLite database path")
+
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p_enrich = sub.add_parser("enrich", help="Enrich a session with temporal context")
+    p_enrich.add_argument("session_id", type=str)
+    p_enrich.set_defaults(func=cmd_enrich)
+
+    p_search = sub.add_parser("search", help="Search messages by time range")
+    p_search.add_argument("session_id", type=str)
+    p_search.add_argument("--range", type=str, default="", help="Time range (e.g. '3 days ago' or ISO 8601)")
+    p_search.set_defaults(func=cmd_search)
+
+    p_stats = sub.add_parser("stats", help="Show session statistics")
+    p_stats.add_argument("session_id", type=str)
+    p_stats.set_defaults(func=cmd_stats)
+
+    args = parser.parse_args()
+    args.db = Path(Path.home() / ".ticks" / "store.db") if args.db == "~/.ticks/store.db" else Path(args.db)
+    args.db.parent.mkdir(parents=True, exist_ok=True)
+    args.func(args)
+
+
+if __name__ == "__main__":
+    main()

pysince-0.1.0/since/core.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+import datetime
+
+from .format import build_prompt, format_absolute
+from .models import Message
+from .store import Store
+from .timeparse import detect_temporal, parse_temporal
+
+
+def with_time(
+    messages: list[Message],
+    now: datetime.datetime | None = None,
+    store: Store | None = None,
+    include_nudge: bool = True,
+    user_input: str | None = None,
+    tz_name: str = "UTC",
+) -> list[dict]:
+    if now is None:
+        now = datetime.datetime.now(datetime.timezone.utc).replace(tzinfo=None)
+
+    extra_context = None
+    session_id = messages[0].session_id if messages else None
+
+    if store and session_id and user_input and detect_temporal(user_input):
+        parsed = parse_temporal(user_input, now)
+        if parsed:
+            start, end = parsed
+            retrieved = store.load_range(session_id, start, end)
+            existing_ids = {(m.session_id, m.turn_id) for m in messages}
+            extra_context = [m for m in retrieved if (m.session_id, m.turn_id) not in existing_ids]
+
+    stale_info = None
+    if store and session_id:
+        stale_info = store.stale_messages(session_id, now)
+
+    prompt = build_prompt(
+        messages=messages,
+        now=now,
+        include_nudge=include_nudge,
+        extra_context=extra_context,
+        tz_name=tz_name,
+        stale_info=stale_info,
+    )
+
+    return prompt
+
+
+def enrich_message(msg: Message, now: datetime.datetime | None = None, tz_name: str = "UTC") -> str:
+    if now is None:
+        now = datetime.datetime.now(datetime.timezone.utc).replace(tzinfo=None)
+    return format_absolute(msg, tz_name)

pysince-0.1.0/since/decorator.py

@@ -0,0 +1,81 @@
+from __future__ import annotations
+
+import datetime
+import functools
+import re
+from typing import Any, Callable
+
+_TS_PREFIX = re.compile(
+    r'^\[[A-Z][a-z]{2} [A-Z][a-z]{2} \d{1,2}, \d{1,2}:\d{2} ?(?:AM|PM)\]\s*'
+)
+
+from .core import with_time
+from .models import Message
+from .store import Store
+
+
+def since_time(
+    store: Store,
+    session_id: str | None = None,
+    timezone: str = "UTC",
+) -> Callable:
+    def decorator(func: Callable) -> Callable:
+        sid = session_id or func.__name__
+
+        @functools.wraps(func)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            now = datetime.datetime.now(datetime.timezone.utc).replace(tzinfo=None)
+
+            ttl_class = kwargs.pop("__ttl_class__", "slow")
+            source_id = kwargs.pop("__source_id__", None)
+
+            messages = kwargs.get("messages")
+            if messages is None and args:
+                messages = args[0]
+
+            if not messages or not isinstance(messages, list):
+                return func(*args, **kwargs)
+
+            last_user = None
+            for m in reversed(messages):
+                if m.get("role") == "user":
+                    last_user = m
+                    break
+
+            user_text = last_user.get("content", "") if last_user else ""
+
+            if last_user:
+                turn = store.next_turn(sid)
+                msg = Message(sid, turn, "user", user_text, now,
+                              timezone=timezone, ttl_class=ttl_class, source_id=source_id)
+                store.insert(msg)
+
+            history = store.load_session(sid)
+            enriched = with_time(history, now=now, store=store, user_input=user_text, tz_name=timezone)
+
+            new_kwargs = dict(kwargs)
+            new_kwargs["messages"] = enriched
+            result = func(*args, **new_kwargs)
+
+            reply = None
+            if hasattr(result, "choices") and result.choices:
+                choice = result.choices[0]
+                if hasattr(choice, "message") and hasattr(choice.message, "content"):
+                    reply = choice.message.content
+                elif isinstance(choice, dict):
+                    reply = choice.get("message", {}).get("content")
+
+            if reply:
+                clean = reply
+                while _TS_PREFIX.match(clean):
+                    clean = _TS_PREFIX.sub("", clean)
+                turn = store.next_turn(sid)
+                msg = Message(sid, turn, "assistant", clean, now,
+                              timezone=timezone, ttl_class=ttl_class, source_id=source_id)
+                store.insert(msg)
+
+            return result
+
+        return wrapper
+
+    return decorator

pysince-0.1.0/since/format.py

@@ -0,0 +1,173 @@
+from __future__ import annotations
+
+import datetime
+import re
+import zoneinfo
+
+from .models import Message, StaleInfo, TIME_OF_DAY_BANDS
+
+PROMPTING_NUDGE = (
+    "Every message has a UTC timestamp. The 'Now:' line below is the "
+    "current time — use it for all time references. Never guess the time."
+)
+
+GAP_THRESHOLD = datetime.timedelta(minutes=30)
+
+
+def _utc_to_local(dt: datetime.datetime, tz_name: str) -> datetime.datetime:
+    if tz_name == "UTC":
+        return dt
+    if tz_name.startswith("UTC") and len(tz_name) > 3:
+        sign = 1 if tz_name[3] == "+" else -1
+        parts = tz_name[4:].split(":")
+        h, m = int(parts[0]), int(parts[1]) if len(parts) > 1 else 0
+        offset = datetime.timedelta(hours=sign * h, minutes=sign * m)
+        tz = datetime.timezone(offset)
+        return dt.replace(tzinfo=datetime.timezone.utc).astimezone(tz).replace(tzinfo=None)
+    try:
+        tz = zoneinfo.ZoneInfo(tz_name)
+        return dt.replace(tzinfo=datetime.timezone.utc).astimezone(tz).replace(tzinfo=None)
+    except zoneinfo.ZoneInfoNotFoundError:
+        return dt
+
+
+def _time_of_day_band(dt: datetime.datetime) -> str:
+    hour = dt.hour
+    for (start, end), label in TIME_OF_DAY_BANDS.items():
+        if start <= hour < end:
+            return label
+    return "night"
+
+
+def _format_timedelta_short(td: datetime.timedelta) -> str:
+    total_seconds = int(td.total_seconds())
+    if total_seconds < 0:
+        return "in the future"
+    if total_seconds < 60:
+        return "just now"
+    if total_seconds < 3600:
+        m = total_seconds // 60
+        return f"{m}m ago"
+    if total_seconds < 86400:
+        h = total_seconds // 3600
+        m = (total_seconds % 3600) // 60
+        return f"{h}h {m}m ago" if m else f"{h}h ago"
+    if total_seconds < 604800:
+        d = total_seconds // 86400
+        h = (total_seconds % 86400) // 3600
+        return f"{d}d {h}h ago" if h else f"{d}d ago"
+    days = total_seconds // 86400
+    if days < 30:
+        w = days // 7
+        d = days % 7
+        return f"{w}w {d}d ago" if d else f"{w}w ago"
+    if days < 365:
+        mo = days // 30
+        d = days % 30
+        return f"{mo}mo {d}d ago" if d else f"{mo}mo ago"
+    y = days // 365
+    d = days % 365
+    return f"{y}y {d}d ago" if d else f"{y}y ago"
+
+
+def _format_timedelta_compact(td: datetime.timedelta) -> str:
+    total_seconds = int(td.total_seconds())
+    if total_seconds < 0:
+        return "0s"
+    if total_seconds < 60:
+        return f"{total_seconds}s"
+    if total_seconds < 3600:
+        return f"{total_seconds // 60}m"
+    if total_seconds < 86400:
+        return f"{total_seconds // 3600}h {(total_seconds % 3600) // 60}m"
+    days = total_seconds // 86400
+    h = (total_seconds % 86400) // 3600
+    return f"{days}d {h}h"
+
+
+def _format_absolute_label(dt: datetime.datetime) -> str:
+    return dt.strftime("%a %b %d, %I:%M%p").lstrip("0").replace("  ", " ")
+
+
+_TS_PREFIX = re.compile(
+    r'^\[[A-Z][a-z]{2} [A-Z][a-z]{2} \d{1,2}, \d{1,2}:\d{2} ?(?:AM|PM)\]\s*'
+)
+
+
+def format_absolute(msg: Message, tz_name: str = "UTC") -> str:
+    ts = _utc_to_local(msg.created_at, tz_name)
+    clean = _TS_PREFIX.sub("", msg.content)
+    return f"[{_format_absolute_label(ts)}]  {clean}"
+
+
+def _build_tail(
+    history: list[Message],
+    now: datetime.datetime,
+    tz_name: str = "UTC",
+    stale_info: list[StaleInfo] | None = None,
+) -> str:
+    lines = []
+
+    local_now = _utc_to_local(now, tz_name) if tz_name != "UTC" else now
+    now_str = local_now.strftime("%a %b %d, %I:%M %p").lstrip("0").replace("  ", " ")
+    band = _time_of_day_band(local_now)
+    lines.append(f"Now: {now_str} ({band})")
+
+    if history:
+        session_age = now - history[0].created_at
+        last_gap = now - history[-1].created_at
+
+        lines.append(f"Session: {_format_timedelta_compact(session_age)} · {len(history) + 1} messages")
+
+        if last_gap > GAP_THRESHOLD:
+            lines.append(f"Gap: {_format_timedelta_short(last_gap)} between messages — welcome back!")
+        elif last_gap.total_seconds() > 60:
+            lines.append(f"Last message: {_format_timedelta_short(last_gap)}")
+    else:
+        lines.append(f"Session: just started · 1 message")
+
+    if stale_info:
+        for s in stale_info:
+            kind = {"event": "invalidated", "ephemeral": "expired"}.get(s.ttl_class, s.ttl_class)
+            src = f" ({s.source_id})" if s.source_id else ""
+            lines.append(f"⚠ Stale: \"{s.content_preview}\"{src} — {kind}, {_format_timedelta_compact(s.age)} old")
+
+    return "\n".join(lines)
+
+
+def build_prompt(
+    messages: list[Message],
+    now: datetime.datetime,
+    include_nudge: bool = True,
+    extra_context: list[Message] | None = None,
+    tz_name: str = "UTC",
+    stale_info: list[StaleInfo] | None = None,
+) -> list[dict]:
+    result = []
+
+    if include_nudge:
+        result.append({"role": "system", "content": PROMPTING_NUDGE})
+
+    if extra_context:
+        result.append({"role": "system", "content": f"--- Retrieved from history ({len(extra_context)} messages) ---"})
+        for msg in extra_context:
+            result.append({"role": msg.role, "content": format_absolute(msg, tz_name)})
+        result.append({"role": "system", "content": "--- End of retrieved history ---"})
+
+    history_msgs = messages
+    current_content = None
+
+    if messages and messages[-1].role == "user":
+        history_msgs = messages[:-1]
+        current_content = messages[-1].content
+
+    for msg in history_msgs:
+        result.append({"role": msg.role, "content": format_absolute(msg, tz_name)})
+
+    tail = _build_tail(history_msgs, now, tz_name, stale_info)
+    result.append({"role": "system", "content": tail})
+
+    if current_content:
+        result.append({"role": "user", "content": current_content})
+
+    return result

pysince-0.1.0/since/models.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+import datetime
+from dataclasses import dataclass
+
+
+@dataclass
+class Message:
+    session_id: str
+    turn_id: int
+    role: str
+    content: str
+    created_at: datetime.datetime
+    timezone: str = "UTC"
+    ttl_class: str = "slow"
+    source_id: str | None = None
+    invalidated_at: datetime.datetime | None = None
+
+
+@dataclass
+class StaleInfo:
+    turn_id: int
+    ttl_class: str
+    source_id: str | None
+    content_preview: str
+    age: datetime.timedelta
+
+
+TIME_OF_DAY_BANDS = {
+    (0, 5): "night",
+    (5, 12): "morning",
+    (12, 17): "afternoon",
+    (17, 21): "evening",
+    (21, 24): "night",
+}
+
+EPHEMERAL_TTL = datetime.timedelta(minutes=5)

pysince-0.1.0/since/stale_files.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+import datetime
+import os
+from pathlib import Path
+
+from .models import Message
+from .store import Store
+
+
+def _now() -> datetime.datetime:
+    return datetime.datetime.now(datetime.timezone.utc).replace(tzinfo=None)
+
+
+def stamp_file_read(filepath: str, store: Store, session_id: str) -> str:
+    path = Path(filepath).resolve()
+    if not path.exists():
+        raise FileNotFoundError(str(path))
+    mtime = os.path.getmtime(str(path))
+    source_id = f"read:{path}"
+    content = f"[FILE READ] {path} (mtime={mtime})"
+    turn = store.next_turn(session_id)
+    msg = Message(session_id, turn, "user", content, _now(),
+                  ttl_class="event", source_id=source_id)
+    store.insert(msg)
+    msg2 = Message(session_id, turn + 1, "assistant",
+                   f"I read {path.name} ({path}).",
+                   _now(), ttl_class="event", source_id=source_id)
+    store.insert(msg2)
+    return source_id
+
+
+def is_stale(filepath: str, store: Store, session_id: str) -> bool:
+    path = Path(filepath).resolve()
+    if not path.exists():
+        return True
+    current_mtime = os.path.getmtime(str(path))
+    source_id = f"read:{path}"
+    msgs = store.load_session(session_id)
+    for m in reversed(msgs):
+        if m.source_id == source_id and m.ttl_class == "event" and m.invalidated_at is None:
+            try:
+                stored = float(m.content.split("mtime=")[1].rstrip(")"))
+            except (IndexError, ValueError):
+                continue
+            if current_mtime != stored:
+                return True
+            return False
+    return False
+
+
+def check_and_invalidate(filepath: str, store: Store, session_id: str) -> bool:
+    """Returns True if the file was found stale and invalidated."""
+    path = Path(filepath).resolve()
+    abs_path = str(path)
+    source_id = f"read:{abs_path}"
+    try:
+        current_mtime = os.path.getmtime(abs_path)
+    except FileNotFoundError:
+        return False
+    msgs = store.load_session(session_id)
+    found = False
+    for m in reversed(msgs):
+        if m.source_id == source_id and m.ttl_class == "event" and m.invalidated_at is None:
+            found = True
+            try:
+                stored = float(m.content.split("mtime=")[1].rstrip(")"))
+            except (IndexError, ValueError):
+                continue
+            if current_mtime != stored:
+                n = store.invalidate(source_id)
+                return n > 0
+            return False
+    return found