cct-cli 0.7.9.0__py3-none-any.whl

calc_terminal/derivations.py

@@ -0,0 +1,153 @@
+"""
+Real calculus derivations for chemical kinetics rate laws.
+
+These are NOT random numericals — they are the actual step-by-step
+derivation of the integrated rate law from the differential rate law,
+using proper mathematical notation (stacked fractions via mathtext,
+"x" for multiplication, integral signs, etc.), the way it is worked
+out on paper / on a board.
+
+Each function returns a dict consumed by engine.render_derivation():
+    topic, goal, steps: [(label, [compose-parts]), ...], result, note
+"""
+
+from .mathtext import frac_part as F, sub, sup
+
+MUL = "\u00d7"          # x   (never "*")
+INT = "\u222b"          # integral sign
+DDT = "d[R]/dt"
+
+
+def zero_order_derivation():
+    steps = [
+        ("Rate law (differential form)",
+         [f"Rate = \u2212d[R]/dt = k[R]", sup(0), " = k"]),
+        ("Separate the variables",
+         ["\u2212d[R] = k ", "dt"]),
+        ("Integrate both sides",
+         [INT, " ", "from [R]", sub(0), " to [R]", "  \u2212d[R]  =  k ", INT, " from 0 to t  dt"]),
+        ("Evaluate the integral",
+         ["\u2212([R] \u2212 [R]", sub(0), ") = k(t \u2212 0)"]),
+        ("Rearrange for [R]",
+         ["[R] = [R]", sub(0), " \u2212 kt"]),
+        ("Solve for k (rearranged form)",
+         ["k = ", F(f"[R]{sub(0)} \u2212 [R]", "t")]),
+    ]
+    return {
+        "topic": "Derivation \u00b7 Zero Order Integrated Rate Law",
+        "goal": "Derive [R] = [R]\u2080 \u2212 kt starting from the differential rate law of a zero order reaction.",
+        "steps": steps,
+        "result": f"[R] = [R]{sub(0)} \u2212 kt      (equivalently  k = ([R]{sub(0)} \u2212 [R]) / t )",
+        "note": "For a zero order reaction the rate is independent of concentration, so [R] falls "
+                "LINEARLY with time \u2014 a straight line of slope \u2212k when [R] is plotted against t.",
+    }
+
+
+def first_order_derivation():
+    steps = [
+        ("Rate law (differential form)",
+         ["Rate = \u2212d[R]/dt = k[R]"]),
+        ("Separate the variables",
+         ["\u2212", F("d[R]", "[R]"), " = k dt"]),
+        ("Integrate both sides",
+         [INT, " from [R]", sub(0), " to [R]  \u2212", F("d[R]", "[R]"), "  =  k ", INT, " from 0 to t  dt"]),
+        ("Evaluate the integral (\u222bd[R]/[R] = ln[R])",
+         ["\u2212(ln[R] \u2212 ln[R]", sub(0), ") = kt"]),
+        ("Combine logarithms",
+         ["ln(", f"[R]{sub(0)}", "/[R]) = kt"]),
+        ("Solve for k, convert ln \u2192 log", 
+         ["k = ", F("1", "t"), " ln(", f"[R]{sub(0)}", "/[R])  =  ", F("2.303", "t"),
+          f"  log{sub(10)}([R]{sub(0)}/[R])"]),
+    ]
+    return {
+        "topic": "Derivation \u00b7 First Order Integrated Rate Law",
+        "goal": "Derive k = (2.303/t) log([R]\u2080/[R]) starting from the differential rate law of a first order reaction.",
+        "steps": steps,
+        "result": f"k = (2.303/t) \u00d7 log{sub(10)}([R]{sub(0)}/[R])      (equivalently  [R] = [R]{sub(0)} e{sup('-kt')} )",
+        "note": "Because the exponent is linear in t, a plot of ln[R] (or log[R]) against t is a straight "
+                "line of slope \u2212k \u2014 the diagnostic test for first order kinetics.",
+    }
+
+
+def second_order_derivation():
+    steps = [
+        ("Rate law (differential form)",
+         ["Rate = \u2212d[R]/dt = k[R]", sup(2)]),
+        ("Separate the variables",
+         ["\u2212", F("d[R]", "[R]" + sup(2)), " = k dt"]),
+        ("Integrate both sides",
+         [INT, " from [R]", sub(0), " to [R]  \u2212", F("d[R]", "[R]" + sup(2)), "  =  k ", INT, " from 0 to t  dt"]),
+        ("Evaluate the integral (\u222bd[R]/[R]\u00b2 = \u22121/[R])",
+         [F("1", "[R]"), " \u2212 ", F("1", f"[R]{sub(0)}"), " = kt"]),
+        ("Rearrange", 
+         [F("1", "[R]"), " = ", F("1", f"[R]{sub(0)}"), " + kt"]),
+    ]
+    return {
+        "topic": "Derivation \u00b7 Second Order Integrated Rate Law",
+        "goal": "Derive 1/[R] = 1/[R]\u2080 + kt starting from the differential rate law of a second order reaction.",
+        "steps": steps,
+        "result": f"1/[R] = 1/[R]{sub(0)} + kt",
+        "note": "A plot of 1/[R] against t is a straight line of slope +k \u2014 the diagnostic test for "
+                "second order kinetics (unlike zero order, which is linear in [R] itself).",
+    }
+
+def third_order_derivation():
+    steps = [
+        ("Rate law (differential form)",
+         ["Rate = \u2212d[R]/dt = k[R]", sup(3)]),
+        ("Separate the variables",
+         ["\u2212", F("d[R]", "[R]" + sup(3)), " = k dt"]),
+        ("Integrate both sides",
+         [INT, " from [R]", sub(0), " to [R]  \u2212", F("d[R]", "[R]" + sup(3)), "  =  k ", INT, " from 0 to t  dt"]),
+        ("Evaluate the integral (\u222bdx/x\u00b3 = \u22121/(2x\u00b2))",
+         [F("1", "2[R]" + sup(2)), " \u2212 ", F("1", f"2[R]{sub(0)}" + sup(2)), " = kt"]),
+        ("Rearrange",
+         [F("1", "[R]" + sup(2)), " = ", F("1", f"[R]{sub(0)}" + sup(2)), " + 2kt"]),
+    ]
+    return {
+        "topic": "Derivation \u00b7 Third Order Integrated Rate Law",
+        "goal": "Derive 1/[R]\u00b2 = 1/[R]\u2080\u00b2 + 2kt starting from the differential rate law of a third order reaction.",
+        "steps": steps,
+        "result": f"1/[R]{sup(2)} = 1/[R]{sub(0)}{sup(2)} + 2kt",
+        "note": "A plot of 1/[R]\u00b2 against t is a straight line of slope +2k \u2014 the diagnostic test for "
+                "third order kinetics.",
+    }
+
+def half_life_first_derivation():
+    steps = [
+        ("Start from the first order integrated law",
+         ["k = ", F("2.303", "t"), f"  log{sub(10)}([R]{sub(0)}/[R])"]),
+        (f"At t = t{sub('1/2')}, [R] = [R]",
+         [f"[R] = [R]{sub(0)}/2  \u21d2  [R]{sub(0)}/[R] = 2"]),
+        ("Substitute and simplify",
+         ["k = ", F("2.303", f"t{sub('1/2')}"), f"  log{sub(10)}(2)"]),
+        ("Use log\u2081\u2080(2) = 0.301",
+         ["k = ", F("2.303 \u00d7 0.301", f"t{sub('1/2')}"), f"  =  ", F("0.693", f"t{sub('1/2')}")]),
+        ("Solve for t\u2081/\u2082",
+         [f"t{sub('1/2')}", " = ", F("0.693", "k")]),
+    ]
+    return {
+        "topic": "Derivation \u00b7 First Order Half-Life",
+        "goal": "Derive t\u00bd = 0.693/k from the first order integrated rate law.",
+        "steps": steps,
+        "result": f"t{sub('1/2')} = 0.693 / k",
+        "note": "Notice [R]\u2080 cancels out completely \u2014 first order half-life does NOT depend on the "
+                "starting concentration, unlike zero or second order.",
+    }
+
+
+DERIVATIONS = {
+    "zero": zero_order_derivation,
+    "first": first_order_derivation,
+    "second": second_order_derivation,
+    "third": third_order_derivation,
+    "halflife": half_life_first_derivation,
+}
+
+DERIVATION_KEYWORDS = [
+    (r"zero\s*order", "zero"),
+    (r"second\s*order", "second"),
+    (r"third\s*order", "third"),
+    (r"half.?life", "halflife"),
+    (r"first\s*order", "first"),
+]

calc_terminal/device_control.py

@@ -0,0 +1,263 @@
+"""
+CCT — device_control.py: Responsible Device Control (v0.7.7 spec
+section 14).
+
+An extensible automation framework for interacting with the user's own
+authorized devices, designed so that:
+
+  * every capability is a registered provider (Desktop / Android / iOS /
+    Browser / Terminal / Simulation) with an explicit availability
+    check — nothing claims to drive a device it can't;
+  * every action that affects a real device requires explicit user
+    approval (permissions.manager's "device_control" key + the same
+    inline permission-card flow installs use) and is recorded in the
+    activity log (eventbus -> session timeline) with the action, target,
+    and outcome — spec section 14's "every action ... clearly visible
+    in the activity log";
+  * the framework itself never executes anything: providers return a
+    plan (what command/API call would run, what it affects) and the
+    CALLER (the permission flow) decides. This keeps "device control"
+    honest — the same separation the spec asks for between automation
+    and user control.
+
+Built-in providers, stated plainly:
+  * terminal  — runs commands on the user's machine (delegates to the
+                existing shell_commands permission; the same
+                subprocess runner agent.py's run_terminal tool uses).
+  * simulation— CCT's own in-app simulations (atom, orbital, reaction):
+                sandboxed by construction, still approval-gated.
+  * desktop / android / ios / browser — EXTENSION POINTS, not working
+                drivers: they register with `available()` returning
+                False until a provider module implements them
+                (e.g. adb for Android, Playwright for browser). The
+                framework is complete; the drivers are future work —
+                the spec's "where platform APIs allow" is honored by
+                not faking support we don't have.
+"""
+
+if __name__ == "__main__":
+    print("This is a library file and is not meant to be run directly.")
+    import sys
+    sys.exit(1)
+
+import shutil
+import time
+
+from . import eventbus
+
+ACTIVITY_LOG = []  # [{ts, provider, action, target, decision, outcome}]
+MAX_LOG = 200
+
+
+# -------------------------------------------------------------- providers --
+class DeviceProvider:
+    """Base class for a device-control capability. Subclasses implement
+    `available()` and `plan(action, params)`; the permission flow calls
+    `plan()` FIRST, shows the user what would happen, and only then
+    `execute()` (which providers implement only if they can really
+    do the thing)."""
+
+    key = "unnamed"
+    label = "Unnamed provider"
+    description = ""
+
+    def available(self):
+        return False
+
+    def plan(self, action, params):
+        """Returns {"action": str, "target": str, "effect": str,
+        "command": [argv] or None} — the user-visible description of
+        what WOULD happen. Never None."""
+        return {"action": action, "target": "", "effect": "not implemented",
+                "command": None}
+
+    def execute(self, plan):
+        """Actually performs the planned action. Only called after the
+        user approved `plan`. Providers that can't execute return a
+        refusal dict instead of faking it."""
+        return {"ok": False, "note": f"provider '{self.key}' has no executor"}
+
+
+class TerminalProvider(DeviceProvider):
+    """Terminal automation — runs commands through the exact same
+    subprocess runner agent.py's run_terminal tool uses."""
+
+    key = "terminal"
+    label = "Terminal"
+    description = "Run commands on this machine (shell, git, python, docker...)."
+
+    def available(self):
+        return True
+
+    def plan(self, action, params):
+        # Accept either "command" or the generic "target" param — the
+        # CLI /devices flow hands over {"target": "<command>"}.
+        cmd = str(params.get("command") or params.get("target") or "").strip()
+        return {"action": action,
+                "target": cmd,
+                "effect": f"Runs in your terminal: $ {cmd}",
+                "command": cmd}
+
+    def execute(self, plan):
+        import subprocess
+        cmd = plan.get("command")
+        if not cmd:
+            return {"ok": False, "note": "no command in plan"}
+        from . import workspace
+        cwd = workspace.root_dir() or None
+        try:
+            proc = subprocess.run(
+                cmd, shell=True, cwd=cwd, capture_output=True, text=True,
+                timeout=min(max(float(plan.get("timeout", 60) or 60), 1.0), 300.0),
+                encoding="utf-8", errors="replace")
+        except subprocess.TimeoutExpired:
+            return {"ok": False, "note": "command timed out"}
+        except OSError as e:
+            return {"ok": False, "note": f"could not run: {e}"}
+        return {"ok": proc.returncode == 0, "exit_code": proc.returncode,
+                "output": ((proc.stdout or "") + (proc.stderr or "")).strip()}
+
+
+class SimulationProvider(DeviceProvider):
+    """CCT's own in-app simulations — sandboxed by construction but
+    still approval-gated (spec: every action affecting the user's
+    environment is visible and approved)."""
+
+    key = "simulation"
+    label = "Simulation"
+    description = "CAT's in-app simulations (atom, orbital, reaction sims)."
+
+    def available(self):
+        return True
+
+    def plan(self, action, params):
+        sim = str(params.get("simulation", params.get("target", ""))).strip()
+        return {"action": action,
+                "target": sim,
+                "effect": f"Runs the in-app '{sim}' simulation (no system changes)",
+                "command": None}
+
+    def execute(self, plan):
+        # In-app simulations render in the terminal/UI directly — the
+        # caller (app.py / ui/app.py) starts them after approval; this
+        # provider only needs to confirm the plan is runnable.
+        return {"ok": True, "note": "simulation started by caller"}
+
+
+class _ScaffoldedProvider(DeviceProvider):
+    """Extension-point providers (desktop/android/ios/browser): they
+    exist so the framework is complete and the permission/logging
+    machinery is real, but `available()` stays False until an actual
+    driver module is implemented."""
+
+    def available(self):
+        return False
+
+    def plan(self, action, params):
+        return {"action": action,
+                "target": str(params.get("target", "")),
+                "effect": f"{self.label} automation is not available in this build "
+                          "(no driver module registered).",
+                "command": None}
+
+
+class _Desktop(_ScaffoldedProvider):
+    key = "desktop"
+    label = "Desktop"
+    description = "Desktop automation (mouse/keyboard/windows) — extension point."
+
+
+class _Android(_ScaffoldedProvider):
+    key = "android"
+    label = "Android"
+    description = "Android automation via adb — extension point (drivers: adb)."
+
+    def available(self):
+        return bool(shutil.which("adb")) and False  # scaffolded: no driver yet
+
+
+class _IOS(_ScaffoldedProvider):
+    key = "ios"
+    label = "iOS"
+    description = "iOS automation where platform APIs allow — extension point."
+
+
+class _Browser(_ScaffoldedProvider):
+    key = "browser"
+    label = "Browser"
+    description = "Browser automation — extension point (drivers: playwright/selenium)."
+
+
+PROVIDERS = {
+    p.key: p for p in (
+        TerminalProvider(), SimulationProvider(), _Desktop(), _Android(),
+        _IOS(), _Browser())
+}
+
+
+# ------------------------------------------------------------- registry --
+def register_provider(provider):
+    """Extension API: register a DeviceProvider subclass instance under
+    its own key (replaces any provider with the same key)."""
+    PROVIDERS[provider.key] = provider
+    return provider
+
+
+def available_providers():
+    """[{key, label, description, available}] for the /devices view."""
+    return [{"key": p.key, "label": p.label, "description": p.description,
+             "available": p.available()}
+            for p in PROVIDERS.values()]
+
+
+def provider(key):
+    return PROVIDERS.get(key)
+
+
+# --------------------------------------------------------------- logging --
+def log_action(provider_key, action, target, decision, outcome=""):
+    entry = {"ts": time.time(), "provider": provider_key, "action": action,
+             "target": target, "decision": decision, "outcome": outcome}
+    ACTIVITY_LOG.append(entry)
+    del ACTIVITY_LOG[:-MAX_LOG]
+    eventbus.bus.publish(eventbus.DEVICE_ACTION, provider=provider_key,
+                         action=action, target=target, decision=decision,
+                         detail=outcome or action)
+    return entry
+
+
+def activity(limit=50):
+    """Newest first."""
+    return list(reversed(ACTIVITY_LOG))[:limit]
+
+
+# -------------------------------------------------------------- the gate --
+def plan_action(provider_key, action, params):
+    """The one entry point the permission flows call: resolves the
+    provider, builds the user-visible plan. Returns
+    {"ok": bool, "plan": {..}, "reason": str}. Callers then run the
+    existing permission-card flow (device_control key) and only call
+    execute_approved() if the user says yes."""
+    p = provider(provider_key)
+    if p is None:
+        return {"ok": False, "plan": None, "reason": f"unknown provider '{provider_key}'"}
+    if not p.available():
+        return {"ok": False, "plan": None, "reason": f"{p.label} automation is not available in this build"}
+    return {"ok": True, "plan": p.plan(action, params), "reason": ""}
+
+
+def execute_approved(provider_key, plan, params):
+    """Runs a provider's plan AFTER the user approved it. Logs the
+    action with its outcome either way."""
+    p = provider(provider_key)
+    if p is None:
+        log_action(provider_key, (plan or {}).get("action", "?"),
+                   (plan or {}).get("target", ""), "denied", "unknown provider")
+        return {"ok": False, "note": "unknown provider"}
+    result = p.execute(plan)
+    outcome = "approved"
+    if not result.get("ok"):
+        outcome += " \u2014 " + str(result.get("note", "execution failed"))
+    log_action(provider_key, (plan or {}).get("action", "?"),
+               (plan or {}).get("target", ""), "approved", outcome)
+    return result

calc_terminal/diagnostics/__init__.py

@@ -0,0 +1,27 @@
+"""
+CAT Diagnostics Package per §32, §33.
+"""
+
+from __future__ import annotations
+
+from calc_terminal.diagnostics.doctor_engine import (
+    DimensionHealth,
+    DoctorReport,
+    DoctorEngine,
+    doctor_engine,
+)
+from calc_terminal.diagnostics.self_test import (
+    SubsystemTestResult,
+    SelfTestReport,
+    run_self_test,
+)
+
+__all__ = [
+    "DimensionHealth",
+    "DoctorReport",
+    "DoctorEngine",
+    "doctor_engine",
+    "SubsystemTestResult",
+    "SelfTestReport",
+    "run_self_test",
+]