memstrata-conversational 0.6.1__tar.gz

memstrata_conversational-0.6.1/LICENSE-COMMERCIAL

@@ -0,0 +1,26 @@
+MEMORY LAYER PRO — COMMERCIAL LICENSE
+
+Copyright (c) 2026 Neeraj Yadav (yadu9989). All Rights Reserved.
+
+This software and associated documentation files (the "Software") are the
+proprietary and confidential property of the copyright holder. Unauthorized
+copying, distribution, modification, or use of this software, in whole or in
+part, is strictly prohibited without express written permission.
+
+PERMITTED USE
+A valid Memory Layer Pro license grants the licensee the right to:
+  1. Install and run the Software on machines owned or controlled by the licensee.
+  2. Use the Software for the licensee's own development workflows.
+
+RESTRICTIONS
+The licensee may not:
+  1. Sublicense, sell, rent, lease, or transfer rights to the Software.
+  2. Reverse-engineer, decompile, or disassemble the Software.
+  3. Remove or alter any proprietary notices or labels on the Software.
+  4. Use the Software to build a competing product.
+
+NO WARRANTY
+The Software is provided "AS IS" without warranty of any kind. The copyright
+holder shall not be liable for any damages arising from use of the Software.
+
+For licensing inquiries: yadavneeraj8@gmail.com

memstrata_conversational-0.6.1/PKG-INFO

@@ -0,0 +1,80 @@
+Metadata-Version: 2.4
+Name: memstrata-conversational
+Version: 0.6.1
+Summary: MemStrata Pro — token-budgeted context harness, licensing, and packaging atop the memstrata open core
+License: MEMORY LAYER PRO — COMMERCIAL LICENSE
+        
+        Copyright (c) 2026 Neeraj Yadav (yadu9989). All Rights Reserved.
+        
+        This software and associated documentation files (the "Software") are the
+        proprietary and confidential property of the copyright holder. Unauthorized
+        copying, distribution, modification, or use of this software, in whole or in
+        part, is strictly prohibited without express written permission.
+        
+        PERMITTED USE
+        A valid Memory Layer Pro license grants the licensee the right to:
+          1. Install and run the Software on machines owned or controlled by the licensee.
+          2. Use the Software for the licensee's own development workflows.
+        
+        RESTRICTIONS
+        The licensee may not:
+          1. Sublicense, sell, rent, lease, or transfer rights to the Software.
+          2. Reverse-engineer, decompile, or disassemble the Software.
+          3. Remove or alter any proprietary notices or labels on the Software.
+          4. Use the Software to build a competing product.
+        
+        NO WARRANTY
+        The Software is provided "AS IS" without warranty of any kind. The copyright
+        holder shall not be liable for any damages arising from use of the Software.
+        
+        For licensing inquiries: yadavneeraj8@gmail.com
+        
+Keywords: llm,context,proxy,harness,memory,telemetry,mcp,licensing
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development
+Requires-Python: >=3.10
+Description-Content-Type: text/plain
+License-File: LICENSE-COMMERCIAL
+Requires-Dist: memstrata<0.7.0,>=0.6.1
+Requires-Dist: fastapi>=0.115
+Requires-Dist: uvicorn[standard]>=0.32
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.10
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: tiktoken>=0.7
+Requires-Dist: pystray>=0.19
+Requires-Dist: Pillow>=10.0
+Requires-Dist: keyring>=25.0
+Requires-Dist: cryptography>=42
+Requires-Dist: tomli>=2.0; python_version < "3.11"
+Requires-Dist: numpy<3,>=1.26
+Requires-Dist: tree-sitter-go<0.24,>=0.23
+Requires-Dist: tree-sitter-rust<0.24,>=0.23
+Requires-Dist: tree-sitter-java<0.24,>=0.23
+Requires-Dist: tree-sitter-c<0.24,>=0.23
+Requires-Dist: tree-sitter-cpp<0.24,>=0.23
+Requires-Dist: tree-sitter-c-sharp<0.24,>=0.23
+Requires-Dist: tree-sitter-ruby<0.24,>=0.23
+Requires-Dist: tree-sitter-php<0.24,>=0.23
+Requires-Dist: tree-sitter-bash<0.24,>=0.23
+Provides-Extra: langchain
+Requires-Dist: langchain-core<2,>=1.4; extra == "langchain"
+Provides-Extra: nli
+Requires-Dist: onnxruntime<2,>=1.18; extra == "nli"
+Requires-Dist: tokenizers<1,>=0.19; extra == "nli"
+Requires-Dist: truststore<1,>=0.10; extra == "nli"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: respx>=0.21; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: mypy>=1.11; extra == "dev"
+Dynamic: license-file
+
+MemStrata Conversational product package.

memstrata_conversational-0.6.1/billing/__init__.py

@@ -0,0 +1,18 @@
+"""
+memory-layer-pro billing subsystem — Phase 23 (Money-Back Guarantee).
+
+Public API:
+  reconcile.compute_cycle_savings  — aggregate measured savings for a billing cycle
+  credit.compute_credit            — derive credit amount from savings vs subscription
+  webhook.handle_invoice_upcoming  — Stripe webhook handler
+  email_notify.render_reconciliation_email / send_reconciliation_email
+"""
+from .credit import Credit, compute_credit
+from .reconcile import CycleSavings, compute_cycle_savings
+
+__all__ = [
+    "CycleSavings",
+    "compute_cycle_savings",
+    "Credit",
+    "compute_credit",
+]

memstrata_conversational-0.6.1/billing/credit.py

@@ -0,0 +1,109 @@
+"""
+Phase 23.1 — credit calculation rules.
+
+Single source of truth for the money-back guarantee math. The credit cap rule
+(credit ≤ subscription_usd) must be enforced here and nowhere else; callers
+must not re-implement it.
+
+Money math uses integer cents (Kimi C3 / K3-H7) so half-cent boundaries do not
+depend on IEEE-754 banker's rounding. Float dollars only appear at the API edge.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from decimal import ROUND_HALF_UP, Decimal
+
+
+@dataclass(frozen=True)
+class Credit:
+    credit_usd: float
+    shortfall_usd: float
+    subscription_usd: float
+    savings_usd: float
+    rationale: str
+
+    @property
+    def is_due(self) -> bool:
+        return self.credit_usd > 0.0
+
+
+def usd_to_cents(amount_usd: float | Decimal | int | str | None) -> int:
+    """Convert a dollar amount to integer cents with half-up rounding.
+
+    Public so dashboard / reconcile / webhooks share one money substrate (K3-M5).
+    ``None`` and non-numeric → 0.
+    """
+    if amount_usd is None:
+        return 0
+    try:
+        d = Decimal(str(amount_usd))
+    except Exception:
+        return 0
+    if d.is_nan() or d.is_infinite():
+        return 0
+    return int((d * 100).quantize(Decimal("1"), rounding=ROUND_HALF_UP))
+
+
+def cents_to_usd(cents: int) -> float:
+    """Integer cents → float dollars (display / API edge only)."""
+    return float(Decimal(int(cents)) / Decimal(100))
+
+
+# Back-compat private aliases
+_to_cents = usd_to_cents
+_cents_to_usd = cents_to_usd
+
+
+def sum_usd_as_cents(amounts: list[float | Decimal | int | str | None]) -> int:
+    """Sum dollar amounts in integer cents (no binary float accumulation)."""
+    return sum(usd_to_cents(a) for a in amounts)
+
+
+def compute_credit(savings_usd: float, subscription_usd: float) -> Credit:
+    """
+    Derive the credit due to a user from measured savings vs subscription cost.
+
+    Rules (AV5.3 §4.1):
+      shortfall = max(0, subscription_usd - savings_usd)
+      credit    = min(shortfall, subscription_usd)   ← cap: never owe beyond subscription
+
+    The cap prevents a degenerate case where a subscription amount of $0 or a
+    negative savings figure could produce a nonsensical result.
+
+    Raises ValueError for negative inputs — savings and subscription must both
+    be non-negative dollar amounts.
+    """
+    if savings_usd < 0:
+        raise ValueError(f"savings_usd must be ≥ 0, got {savings_usd}")
+    if subscription_usd < 0:
+        raise ValueError(f"subscription_usd must be ≥ 0, got {subscription_usd}")
+
+    savings_cents = usd_to_cents(savings_usd)
+    sub_cents = usd_to_cents(subscription_usd)
+    shortfall_cents = max(0, sub_cents - savings_cents)
+    credit_cents = min(shortfall_cents, sub_cents)
+
+    credit = cents_to_usd(credit_cents)
+    shortfall = cents_to_usd(shortfall_cents)
+    sub_usd = cents_to_usd(sub_cents)
+    sav_usd = cents_to_usd(savings_cents)
+
+    if credit_cents == 0:
+        rationale = (
+            f"Savings ${sav_usd:.2f} ≥ subscription ${sub_usd:.2f}; "
+            f"no credit due."
+        )
+    else:
+        rationale = (
+            f"Savings ${sav_usd:.2f} < subscription ${sub_usd:.2f}; "
+            f"crediting ${credit:.2f} (shortfall capped at subscription ceiling "
+            f"${sub_usd:.2f})."
+        )
+
+    return Credit(
+        credit_usd=credit,
+        shortfall_usd=shortfall,
+        subscription_usd=sub_usd,
+        savings_usd=sav_usd,
+        rationale=rationale,
+    )

memstrata_conversational-0.6.1/billing/email_notify.py

@@ -0,0 +1,282 @@
+"""
+Phase 23.3 — end-of-cycle reconciliation email.
+
+Renders and (optionally) sends the transactional email showing the user's
+cost-vs-savings footprint for the billing cycle.
+
+Template content per AV5.3 §4.1. The sender backend is configurable via
+MEMORY_LAYER_EMAIL_BACKEND env var: 'sendgrid' | 'resend' | 'smtp' | 'noop'.
+"""
+from __future__ import annotations
+
+import logging
+import os
+import smtplib
+import textwrap
+from dataclasses import dataclass
+from email.mime.multipart import MIMEMultipart
+from email.mime.text import MIMEText
+
+from .credit import Credit
+from .reconcile import CycleSavings
+
+log = logging.getLogger(__name__)
+
+
+# ---------------------------------------------------------------------------
+# Rendered email
+# ---------------------------------------------------------------------------
+
+@dataclass
+class ReconciliationEmail:
+    to_address: str
+    subject: str
+    body_text: str
+    body_html: str
+
+
+def render_reconciliation_email(
+    user_email: str,
+    month_label: str,
+    savings: CycleSavings,
+    credit: Credit,
+) -> ReconciliationEmail:
+    """
+    Render the end-of-cycle reconciliation email per AV5.3 §4.1.
+
+    Parameters
+    ----------
+    user_email:  Recipient address.
+    month_label: Human-readable billing period, e.g. "May 2026".
+    savings:     CycleSavings from reconcile.compute_cycle_savings.
+    credit:      Credit from credit.compute_credit.
+    """
+    subject = f"Your Memory Layer reconciliation for {month_label}"
+
+    if credit.is_due:
+        credit_line = f"Credit on next invoice: ${credit.credit_usd:.2f}"
+        footer = (
+            "Your dashboard remains active. Memory Layer learns and improves with use;\n"
+            "next month's savings should grow as your project state densifies."
+        )
+    else:
+        credit_line = (
+            f"No credit due — your savings (${savings.total_usd:.2f}) exceeded "
+            f"your subscription (${credit.subscription_usd:.2f})."
+        )
+        footer = (
+            "You're net positive this month! Your savings exceeded your subscription "
+            "cost.\nKeep using Memory Layer — your project knowledge is compounding."
+        )
+
+    body_text = textwrap.dedent(f"""\
+        Subject: {subject}
+
+        This cycle:
+          Input savings:     ${savings.input_savings_usd:.2f}  (measured)
+          Cache savings:     ${savings.cache_savings_usd:.2f}  (measured)
+          Output savings:    ${savings.output_savings_usd:.2f}  (cohort-measured)
+          Total savings:     ${savings.total_usd:.2f}
+          Subscription:      ${credit.subscription_usd:.2f}
+
+        {credit_line}
+
+        {footer}
+
+        — The Memory Layer Team
+    """)
+
+    body_html = _render_html(
+        month_label=month_label,
+        savings=savings,
+        credit=credit,
+        credit_line=credit_line,
+        footer=footer,
+    )
+
+    return ReconciliationEmail(
+        to_address=user_email,
+        subject=subject,
+        body_text=body_text,
+        body_html=body_html,
+    )
+
+
+def _render_html(
+    *,
+    month_label: str,
+    savings: CycleSavings,
+    credit: Credit,
+    credit_line: str,
+    footer: str,
+) -> str:
+    highlight = "#2ecc71" if not credit.is_due else "#e67e22"
+    return f"""\
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <title>Memory Layer Reconciliation</title>
+  <style>
+    body {{ font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
+           background: #f9f9f9; margin: 0; padding: 20px; }}
+    .card {{ background: #fff; border-radius: 8px; max-width: 540px; margin: 0 auto;
+             padding: 32px; box-shadow: 0 2px 8px rgba(0,0,0,.08); }}
+    h1 {{ font-size: 1.2rem; color: #111; margin-bottom: 24px; }}
+    table {{ width: 100%; border-collapse: collapse; margin-bottom: 16px; }}
+    td {{ padding: 6px 0; color: #333; font-size: .95rem; }}
+    td.label {{ color: #666; }}
+    td.amount {{ text-align: right; font-variant-numeric: tabular-nums; }}
+    .divider {{ border-top: 1px solid #eee; margin: 12px 0; }}
+    .credit-line {{ font-size: 1rem; font-weight: 600; color: {highlight};
+                   margin: 16px 0; }}
+    .footer {{ margin-top: 24px; font-size: .85rem; color: #888; }}
+  </style>
+</head>
+<body>
+  <div class="card">
+    <h1>Memory Layer — {month_label} reconciliation</h1>
+    <table>
+      <tr><td class="label">Input savings</td>
+          <td class="amount">${savings.input_savings_usd:.2f} <small>measured</small></td></tr>
+      <tr><td class="label">Cache savings</td>
+          <td class="amount">${savings.cache_savings_usd:.2f} <small>measured</small></td></tr>
+      <tr><td class="label">Output savings</td>
+          <td class="amount">${savings.output_savings_usd:.2f} <small>cohort-measured</small></td></tr>
+    </table>
+    <div class="divider"></div>
+    <table>
+      <tr><td class="label">Total savings</td>
+          <td class="amount"><strong>${savings.total_usd:.2f}</strong></td></tr>
+      <tr><td class="label">Subscription</td>
+          <td class="amount">${credit.subscription_usd:.2f}</td></tr>
+    </table>
+    <div class="credit-line">{credit_line}</div>
+    <div class="footer">{footer.replace(chr(10), '<br>')}</div>
+    <div class="footer" style="margin-top:12px">— The Memory Layer Team</div>
+  </div>
+</body>
+</html>"""
+
+
+# ---------------------------------------------------------------------------
+# Send backends
+# ---------------------------------------------------------------------------
+
+def send_reconciliation_email(
+    email: ReconciliationEmail,
+    *,
+    backend: str | None = None,
+    sendgrid_api_key: str | None = None,
+    resend_api_key: str | None = None,
+    smtp_host: str = "localhost",
+    smtp_port: int = 587,
+    smtp_username: str | None = None,
+    smtp_password: str | None = None,
+    from_address: str = "noreply@memorylayer.dev",
+) -> bool:
+    """
+    Send `email` via the configured backend. Returns True on success.
+
+    Backend priority:
+      1. `backend` argument if supplied.
+      2. MEMORY_LAYER_EMAIL_BACKEND env var.
+      3. Falls back to 'noop' (logs only, no send).
+    """
+    resolved = backend or os.environ.get("MEMORY_LAYER_EMAIL_BACKEND", "noop")
+
+    if resolved == "sendgrid":
+        return _send_sendgrid(
+            email, api_key=sendgrid_api_key or os.environ["SENDGRID_API_KEY"],
+            from_address=from_address,
+        )
+    if resolved == "resend":
+        return _send_resend(
+            email, api_key=resend_api_key or os.environ["RESEND_API_KEY"],
+            from_address=from_address,
+        )
+    if resolved == "smtp":
+        return _send_smtp(
+            email, host=smtp_host, port=smtp_port,
+            username=smtp_username, password=smtp_password,
+            from_address=from_address,
+        )
+
+    # noop — log and return True so callers don't treat this as an error
+    log.info(
+        "email_notify [noop] would send '%s' to %s",
+        email.subject, email.to_address,
+    )
+    return True
+
+
+def _send_sendgrid(email: ReconciliationEmail, *, api_key: str, from_address: str) -> bool:
+    try:
+        import sendgrid
+        from sendgrid.helpers.mail import Mail, To, From, Subject, HtmlContent, Content
+
+        sg = sendgrid.SendGridAPIClient(api_key=api_key)
+        message = Mail(
+            from_email=from_address,
+            to_emails=email.to_address,
+            subject=email.subject,
+            html_content=email.body_html,
+        )
+        message.add_content(Content("text/plain", email.body_text))
+        response = sg.send(message)
+        success = 200 <= response.status_code < 300
+        if not success:
+            log.error("SendGrid returned %s", response.status_code)
+        return success
+    except Exception as exc:
+        log.error("SendGrid send failed: %s", exc)
+        return False
+
+
+def _send_resend(email: ReconciliationEmail, *, api_key: str, from_address: str) -> bool:
+    try:
+        import resend
+
+        resend.api_key = api_key
+        params = {
+            "from": from_address,
+            "to": [email.to_address],
+            "subject": email.subject,
+            "html": email.body_html,
+            "text": email.body_text,
+        }
+        resend.Emails.send(params)
+        return True
+    except Exception as exc:
+        log.error("Resend send failed: %s", exc)
+        return False
+
+
+def _send_smtp(
+    email: ReconciliationEmail,
+    *,
+    host: str,
+    port: int,
+    username: str | None,
+    password: str | None,
+    from_address: str,
+) -> bool:
+    try:
+        msg = MIMEMultipart("alternative")
+        msg["Subject"] = email.subject
+        msg["From"] = from_address
+        msg["To"] = email.to_address
+        msg.attach(MIMEText(email.body_text, "plain"))
+        msg.attach(MIMEText(email.body_html, "html"))
+
+        with smtplib.SMTP(host, port) as server:
+            server.ehlo()
+            if port != 25:
+                server.starttls()
+            if username and password:
+                server.login(username, password)
+            server.sendmail(from_address, [email.to_address], msg.as_string())
+        return True
+    except Exception as exc:
+        log.error("SMTP send failed: %s", exc)
+        return False

memstrata_conversational-0.6.1/billing/reconcile.py

@@ -0,0 +1,120 @@
+"""
+Phase 23.1 — billing reconciliation.
+
+Aggregates measured savings from telemetry_session_timeline for a user's billing
+cycle. Only the three honest measurement bases are included; output_estimated is
+excluded from all credit-eligible totals (Hard Rule 60).
+
+Money accumulation is integer cents end-to-end (Kimi K3-M5 / H7): SQLite float
+SUM is never trusted for credit math.
+"""
+from __future__ import annotations
+
+import sqlite3
+from dataclasses import dataclass
+from datetime import datetime
+
+from billing.credit import cents_to_usd, sum_usd_as_cents, usd_to_cents
+
+
+_CREDIT_ELIGIBLE_BASES = ("input_measured", "cache_measured", "output_cohort_measured")
+
+
+@dataclass
+class CycleSavings:
+    user_id: str
+    cycle_start: datetime
+    cycle_end: datetime
+    input_savings_usd: float
+    cache_savings_usd: float
+    output_savings_usd: float
+    # Integer cents retained for exact credit handoff (optional consumers).
+    input_savings_cents: int = 0
+    cache_savings_cents: int = 0
+    output_savings_cents: int = 0
+
+    @property
+    def total_cents(self) -> int:
+        return (
+            self.input_savings_cents
+            + self.cache_savings_cents
+            + self.output_savings_cents
+        )
+
+    @property
+    def total_usd(self) -> float:
+        return cents_to_usd(self.total_cents)
+
+    def to_dict(self) -> dict:
+        return {
+            "user_id": self.user_id,
+            "cycle_start": self.cycle_start.isoformat(),
+            "cycle_end": self.cycle_end.isoformat(),
+            "input_savings_usd": round(self.input_savings_usd, 2),
+            "cache_savings_usd": round(self.cache_savings_usd, 2),
+            "output_savings_usd": round(self.output_savings_usd, 2),
+            "total_usd": round(self.total_usd, 2),
+            "input_savings_cents": self.input_savings_cents,
+            "cache_savings_cents": self.cache_savings_cents,
+            "output_savings_cents": self.output_savings_cents,
+            "total_cents": self.total_cents,
+        }
+
+
+def compute_cycle_savings(
+    user_id: str,
+    cycle_start: datetime,
+    cycle_end: datetime,
+    *,
+    conn: sqlite3.Connection,
+) -> CycleSavings:
+    """
+    Sum credit-eligible savings for `user_id` between `cycle_start` and `cycle_end`.
+
+    Filters to measurement_basis IN ('input_measured', 'cache_measured',
+    'output_cohort_measured'). Rows tagged 'output_estimated' are intentionally
+    excluded — they are not auditable and never credited (Hard Rule 60).
+
+    Each row is converted to integer cents with half-up rounding, then summed —
+    never ``SUM(float)`` in SQLite / Python float accumulate.
+    """
+    placeholders = ",".join("?" for _ in _CREDIT_ELIGIBLE_BASES)
+    rows = conn.execute(
+        f"""
+        SELECT
+            saved_input_cost_usd,
+            saved_cache_cost_usd,
+            saved_output_cost_usd
+        FROM telemetry_session_timeline
+        WHERE user_id          = ?
+          AND recorded_at BETWEEN ? AND ?
+          AND measurement_basis IN ({placeholders})
+        """,
+        (
+            user_id,
+            cycle_start.isoformat(),
+            cycle_end.isoformat(),
+            *_CREDIT_ELIGIBLE_BASES,
+        ),
+    ).fetchall()
+
+    in_c = sum_usd_as_cents([r[0] for r in rows])
+    ca_c = sum_usd_as_cents([r[1] for r in rows])
+    ou_c = sum_usd_as_cents([r[2] for r in rows])
+
+    return CycleSavings(
+        user_id=user_id,
+        cycle_start=cycle_start,
+        cycle_end=cycle_end,
+        input_savings_usd=cents_to_usd(in_c),
+        cache_savings_usd=cents_to_usd(ca_c),
+        output_savings_usd=cents_to_usd(ou_c),
+        input_savings_cents=in_c,
+        cache_savings_cents=ca_c,
+        output_savings_cents=ou_c,
+    )
+
+
+def savings_total_usd(*parts: float) -> float:
+    """Sum display-side USD parts via cents (dashboard / API helpers)."""
+    return cents_to_usd(sum(usd_to_cents(p) for p in parts))