systemu 0.7.0__py3-none-any.whl

sharing_on/__init__.py

@@ -0,0 +1,3 @@
+"""sharing_on — Record computer activity, generate step-by-step instructions."""
+
+__version__ = "0.7.0"

sharing_on/__main__.py

@@ -0,0 +1,6 @@
+"""Allow running as `python -m sharing_on`."""
+
+from sharing_on.cli import main
+
+if __name__ == "__main__":
+    main()

sharing_on/analyzer/__init__.py

@@ -0,0 +1 @@
+"""Analyzer subpackage — step detection and instruction generation."""

sharing_on/analyzer/generator.py

@@ -0,0 +1,332 @@
+"""LLM-powered instruction generator — converts detected steps into
+human-readable, step-by-step instructions using OpenRouter API.
+
+Uses the OpenAI-compatible client library with OpenRouter's base URL.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import List, Optional
+
+from openai import OpenAI
+
+from sharing_on.analyzer.step_detector import Step
+from sharing_on.events.models import EventAction, EventCategory
+from sharing_on.redactor import redact
+
+logger = logging.getLogger(__name__)
+
+
+SYSTEM_PROMPT = """You are an expert Standard Operating Procedure (SOP) writer.
+Your job is to analyze captured computer activity and produce a clear, narrative
+document that another person can follow to reproduce the exact same task.
+
+## Your Approach
+
+1. **Infer the Overall Intent**: Before writing any steps, analyze ALL the captured
+   events holistically. Determine WHAT the user was trying to accomplish at a high
+   level (e.g., "Create a daily financial market summary report" or "Deploy a
+   microservice to production"). State this intent clearly at the top of the document
+   as a one-paragraph executive summary.
+
+2. **Identify Subtasks**: Break the full activity into logical subtasks or phases
+   (e.g., "Phase 1: Research — Gather market data", "Phase 2: Documentation —
+   Compile findings into a report"). Each subtask should have a clear heading and
+   a brief description of its purpose before the numbered steps.
+
+3. **Write Narrative Steps**: Each step should read like a clear instruction from
+   a knowledgeable colleague, not a robotic log. Use natural language.
+   - BAD:  "Clicked 'Save' (ButtonControl) in Save As dialog"
+   - GOOD: "Save the file by clicking the **Save** button in the Save As dialog."
+
+## Rules
+
+1. Write each step as a clear, action-oriented instruction
+2. Include exact commands, URLs, and file paths when detected
+3. Mention which application was used at the start of each step (e.g., "**In Google Chrome**, ...")
+4. Be specific but concise — assume the reader is technically competent but unfamiliar with this task
+5. If clipboard content was pasted, mention what was pasted and where
+6. Format file changes as markdown diff blocks
+7. Do NOT invent steps that weren't captured — only document what actually happened
+8. Group closely related sub-actions (like repeated formatting clicks) into a single step and describe the intent
+9. When a UI element was clicked, describe it by its visible label or name, NOT by coordinates
+10. If a URL was navigated to, include the full URL
+11. When a repeated action is noted (e.g., "clicked 15 times"), describe the intent
+    (e.g., "Reduced the font size to approximately 10pt by clicking the decrease button repeatedly")
+12. If an input field was changed, mention which field and what value was entered
+13. If the user switched between apps to copy/reference information, describe the workflow
+    (e.g., "Switch to the browser tab showing NSE India to note the closing Nifty value, then return to the Google Doc to enter it")
+
+## Output Format
+
+```markdown
+# [Task Title — inferred from activity]
+
+## Overview
+[1-2 paragraph executive summary of what was accomplished and why]
+
+## Subtask 1: [Phase Name]
+[Brief description of this phase's purpose]
+
+1. **[App Name]** — [Clear narrative instruction]
+2. ...
+
+## Subtask 2: [Phase Name]
+...
+
+## Result
+[Brief description of the final outcome — e.g., what file was created, what was deployed, etc.]
+```
+
+Return ONLY the Markdown document. Do not add any preamble or explanation outside the document."""
+
+
+def generate_instructions(
+    steps: List[Step],
+    session_name: str,
+    platform_info: str,
+    duration_seconds: float,
+    api_key: str,
+    base_url: str = "https://openrouter.ai/api/v1",
+    model: str = "openai/gpt-4o-mini",
+    intent: Optional["IntentExtraction"] = None,    # noqa: F821 — fwd ref
+) -> str:
+    """Send captured steps to the LLM and get back formatted instructions.
+
+    Args:
+        steps: List of detected steps with their events.
+        session_name: Name of the capture session.
+        platform_info: Platform description string.
+        duration_seconds: Total session duration.
+        api_key: OpenRouter API key.
+        base_url: OpenRouter API base URL.
+        model: LLM model identifier.
+        intent: (v0.6.0-a) optional pre-extracted intent.  When present, the
+            LLM is told the user's actual outcome up-front and instructed
+            to anchor the narrative on that intent rather than re-inferring
+            it from the click sequence.
+
+    Returns:
+        Markdown-formatted step-by-step instructions.
+    """
+    if not steps:
+        return "_No activity was captured during this session._"
+
+    # Build the structured step data for the LLM
+    step_descriptions = []
+    for step in steps:
+        step_desc = _format_step_for_llm(step)
+        step_descriptions.append(step_desc)
+
+    # when intent is pre-extracted, surface it explicitly so the
+    # narrative LLM doesn't have to re-derive it from clicks (which is the
+    # whole reason the click-mirroring failure mode exists).
+    intent_block = ""
+    if intent is not None and getattr(intent, "is_usable", False):
+        intent_block = (
+            "## Pre-Inferred User Intent\n\n"
+            f"- **Intent:** {intent.intent}\n"
+            f"- **Expected outcome:** {intent.expected_outcome}\n"
+            f"- **Success signal:** {intent.success_signal}\n\n"
+            "Anchor your narrative on this stated intent.  The captured steps "
+            "below describe HOW the user happened to do it; your job is to "
+            "narrate them in a way that serves the stated intent, not to "
+            "re-derive intent from the click sequence.\n\n"
+            "---\n\n"
+        )
+
+    user_prompt = f"""Task Name: {session_name}
+Platform: {platform_info}
+Total Duration: {duration_seconds:.0f} seconds
+Number of Steps Detected: {len(steps)}
+
+{intent_block}Below are the captured steps with their raw events. Convert these into clear,
+reproducible instructions.
+
+---
+
+{chr(10).join(step_descriptions)}
+"""
+
+    # Redact PII before sending to LLM
+    user_prompt = redact(user_prompt)
+
+    try:
+        client = OpenAI(
+            api_key=api_key,
+            base_url=base_url,
+        )
+
+        response = client.chat.completions.create(
+            model=model,
+            messages=[
+                {"role": "system", "content": SYSTEM_PROMPT},
+                {"role": "user", "content": user_prompt},
+            ],
+            temperature=0.3,       # Low creativity, high accuracy
+            max_tokens=4000,
+            top_p=0.9,
+        )
+
+        instructions = response.choices[0].message.content or ""
+        logger.info(
+            f"Generated instructions: {len(instructions)} chars, "
+            f"tokens used: {response.usage.total_tokens if response.usage else 'unknown'}"
+        )
+        return instructions.strip()
+
+    except Exception as e:
+        logger.error(f"LLM instruction generation failed: {e}")
+        # Fallback: generate basic instructions without LLM
+        return _generate_fallback_instructions(steps, session_name)
+
+
+def _format_step_for_llm(step: Step) -> str:
+    """Format a single step's events into a readable description for the LLM."""
+    lines = []
+    lines.append(f"### Step {step.step_number}")
+
+    if step.label:
+        lines.append(f"**User Label:** {step.label}")
+
+    if step.primary_app:
+        lines.append(f"**Primary Application:** {step.primary_app}")
+
+    if step.start_time:
+        lines.append(f"**Time:** {step.start_time.strftime('%H:%M:%S')}")
+        lines.append(f"**Duration:** {step.duration_seconds:.1f}s")
+
+    lines.append("")
+    lines.append("**Events:**")
+
+    # Emit relevant events (skip screenshots — they're referenced separately)
+    for event in step.events:
+        if event.category == EventCategory.SCREEN:
+            continue
+
+        if event.action == EventAction.WINDOW_FOCUS:
+            app = event.application or "Unknown"
+            title = event.window_title or ""
+            lines.append(f"- Switched to **{app}**: {title}")
+
+        elif event.action == EventAction.FILE_CREATED:
+            lines.append(f"- Created file: `{event.file_path}`")
+
+        elif event.action == EventAction.FILE_MODIFIED:
+            lines.append(f"- Modified file: `{event.file_path}`")
+            diff = event.data.get("diff")
+            if diff:
+                # Truncate very long diffs for the LLM
+                if len(diff) > 2000:
+                    diff = diff[:2000] + "\n... (truncated)"
+                lines.append(f"  ```diff\n{diff}\n  ```")
+
+        elif event.action == EventAction.FILE_DELETED:
+            lines.append(f"- Deleted file: `{event.file_path}`")
+
+        elif event.action == EventAction.FILE_MOVED:
+            dest = event.data.get("dest_path", "unknown")
+            lines.append(f"- Moved file: `{event.file_path}` → `{dest}`")
+
+        elif event.action == EventAction.PROCESS_STARTED:
+            cmdline = event.data.get("cmdline", event.process_name or "")
+            lines.append(f"- Ran command: `{cmdline}`")
+
+        elif event.action == EventAction.PROCESS_ENDED:
+            lines.append(f"- Process ended: {event.process_name}")
+
+        elif event.action == EventAction.CLIPBOARD_CHANGE:
+            preview = event.data.get("preview", "")
+            content_type = event.data.get("content_type", "text")
+            if content_type == "command":
+                lines.append(f"- Copied command: `{preview}`")
+            elif content_type == "code":
+                lines.append(f"- Copied code snippet: `{preview[:100]}`")
+            elif content_type == "url":
+                lines.append(f"- Copied URL: `{preview}`")
+            else:
+                lines.append(f"- Copied to clipboard: {preview[:100]}")
+
+        elif event.action == EventAction.STEP_MARKER:
+            label = event.data.get("label", "")
+            key_name = event.data.get("key", "")
+            if key_name:
+                lines.append(f"- Pressed key: **{key_name}**")
+            elif label:
+                lines.append(f"- User note: {label}")
+
+        elif event.action == EventAction.MOUSE_CLICK:
+            app = event.application or "Unknown"
+            el_name = event.data.get("element_name", "")
+            ctrl_type = event.data.get("control_type", "")
+            xpath = event.data.get("element_xpath", "")
+            url = event.data.get("url", "")
+            el_text = event.data.get("element_text", "")
+            value = event.data.get("value", "")
+            repeat = event.data.get("repeat_count", 1)
+
+            # Build a clear, semantic description
+            desc_parts = []
+            if el_name and el_name != "Unknown":
+                desc_parts.append(f"**{el_name}**")
+            elif el_text:
+                desc_parts.append(f"**{el_text}**")
+
+            if ctrl_type and ctrl_type != "Unknown":
+                desc_parts.append(f"({ctrl_type})")
+
+            if url:
+                desc_parts.append(f"on page `{url}`")
+
+            if value:
+                desc_parts.append(f"[value: `{value}`]")
+
+            desc = " ".join(desc_parts) if desc_parts else "an element"
+
+            if repeat and repeat > 1:
+                lines.append(f"- Clicked {desc} **{repeat} times** in **{app}**")
+            else:
+                lines.append(f"- Clicked {desc} in **{app}**")
+
+        elif event.action == EventAction.KEY_PRESS:
+            el_text = event.data.get("element_text", "")
+            value = event.data.get("value", "")
+            url = event.data.get("url", "")
+            if value:
+                lines.append(f"- Typed `{value}` into a field")
+                if url:
+                    lines.append(f"  on page `{url}`")
+            elif el_text:
+                lines.append(f"- Interacted with input: {el_text}")
+
+    lines.append("")
+    return "\n".join(lines)
+
+
+def _generate_fallback_instructions(steps: List[Step], session_name: str) -> str:
+    """Generate basic instructions without LLM (fallback if API fails)."""
+    lines = [
+        f"# {session_name}",
+        "",
+        "_Note: LLM generation failed. Showing raw captured steps._",
+        "",
+    ]
+
+    for step in steps:
+        lines.append(f"## Step {step.step_number}")
+        if step.label:
+            lines.append(f"_{step.label}_")
+        if step.primary_app:
+            lines.append(f"**Application:** {step.primary_app}")
+        lines.append("")
+
+        for event in step.events:
+            if event.category == EventCategory.SCREEN:
+                continue
+            lines.append(f"- {event.summary}")
+
+        lines.append("")
+
+    return "\n".join(lines)

sharing_on/analyzer/intent_extractor.py

@@ -0,0 +1,292 @@
+"""Intent extractor (v0.6.0-a, Stage 1).
+
+Pre-pass that runs BEFORE the narrative generator (`generator.py`).  Reads
+the raw events + detected steps and emits a structured ``intent.json``
+artifact at the session root.
+
+The point: today the downstream pipeline (Scroll → Activity → Tools →
+Shadow) infers the user's intent from a click-by-click narrative.  When
+the user's captured workflow uses one app to achieve an outcome that
+could be achieved better another way (e.g., Snipping Tool + Word to
+"document weather" — actually just wants weather data documented), the
+downstream LLMs faithfully reproduce the means and miss the end.
+
+This extractor decouples intent from means.  Output schema::
+
+    {
+      "intent":           "<outcome, one line, no app/GUI names>",
+      "expected_outcome": "<concrete success description>",
+      "success_signal":   "<observable proof of completion>",
+      "abstracted_steps": ["<outcome-described step>", ...],
+      "confidence":       "high" | "medium" | "low"
+    }
+
+Best-effort throughout — when the extractor fails or returns
+``confidence == "low"``, callers fall back to today's narrative-only
+behaviour (no operator card; this stage is read-only background work).
+"""
+from __future__ import annotations
+
+import json
+import logging
+from collections import Counter
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from openai import OpenAI
+
+from sharing_on.analyzer.step_detector import Step
+from sharing_on.events.models import EventAction, EventCategory
+
+logger = logging.getLogger(__name__)
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+
+@dataclass
+class IntentExtraction:
+    """Structured intent inferred from a capture session."""
+
+    intent:           str = ""
+    expected_outcome: str = ""
+    success_signal:   str = ""
+    abstracted_steps: List[str] = field(default_factory=list)
+    confidence:       str = "low"   # high | medium | low
+    error:            Optional[str] = None
+
+    @property
+    def is_usable(self) -> bool:
+        """True when downstream pipeline should prefer this over narrative."""
+        return self.confidence in ("high", "medium") and bool(self.intent.strip())
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Public API
+
+def extract_intent(
+    *,
+    steps: List[Step],
+    events: List[Any],
+    session_name: str,
+    platform_info: str,
+    api_key: str,
+    base_url: str = "https://openrouter.ai/api/v1",
+    model: str = "google/gemini-2.0-flash-exp:free",
+) -> IntentExtraction:
+    """Run the intent-extraction LLM pass.
+
+    Returns a structured ``IntentExtraction``.  Never raises — failures
+    are returned as ``confidence="low"`` with ``error`` populated so the
+    caller can fall back gracefully.
+    """
+    if not steps and not events:
+        return IntentExtraction(
+            confidence="low",
+            error="no steps or events to analyse",
+        )
+
+    summary = _summarise_events(events, steps)
+    abstracted = _abstract_step_titles(steps)
+
+    payload = {
+        "session_name": session_name,
+        "platform":     platform_info,
+        "event_summary": summary,
+        "abstracted_step_descriptions": abstracted,
+    }
+
+    try:
+        prompt = _load_prompt()
+    except Exception as exc:
+        logger.warning("[IntentExtractor] could not load prompt: %s", exc)
+        return IntentExtraction(confidence="low", error=str(exc))
+
+    try:
+        client = OpenAI(api_key=api_key, base_url=base_url)
+        response = client.chat.completions.create(
+            model=model,
+            messages=[
+                {"role": "system", "content": prompt},
+                {"role": "user",   "content": json.dumps(payload, default=str)},
+            ],
+            temperature=0.1,
+            max_tokens=1024,
+            response_format={"type": "json_object"},
+        )
+        raw = response.choices[0].message.content or "{}"
+    except Exception as exc:
+        logger.warning("[IntentExtractor] LLM call failed: %s", exc)
+        return IntentExtraction(confidence="low", error=str(exc))
+
+    return _parse_response(raw)
+
+
+def write_intent_json(intent: IntentExtraction, session_dir: Path) -> Path:
+    """Persist the extraction to ``<session_dir>/intent.json``."""
+    target = Path(session_dir) / "intent.json"
+    try:
+        data = asdict(intent)
+        # Drop the transient error field on usable extractions — operators
+        # looking at the file want signal, not noise.  Failed/low-confidence
+        # extractions keep the error so the failure mode is visible.
+        if intent.is_usable:
+            data.pop("error", None)
+        target.write_text(json.dumps(data, indent=2), encoding="utf-8")
+        logger.info(
+            "[IntentExtractor] wrote %s (confidence=%s)",
+            target, intent.confidence,
+        )
+    except Exception:
+        logger.exception("[IntentExtractor] failed to write intent.json")
+    return target
+
+
+def read_intent_json(session_dir: Path) -> Optional[IntentExtraction]:
+    """Load a previously-written intent.json; returns None if absent or
+    unparseable."""
+    target = Path(session_dir) / "intent.json"
+    if not target.exists():
+        return None
+    try:
+        data = json.loads(target.read_text(encoding="utf-8"))
+        if not isinstance(data, dict):
+            return None
+        return IntentExtraction(
+            intent           = str(data.get("intent", ""))[:500],
+            expected_outcome = str(data.get("expected_outcome", ""))[:500],
+            success_signal   = str(data.get("success_signal", ""))[:500],
+            abstracted_steps = [str(s)[:200] for s in (data.get("abstracted_steps") or [])][:12],
+            confidence       = str(data.get("confidence", "low")),
+            error            = data.get("error"),
+        )
+    except Exception:
+        logger.debug("[IntentExtractor] read failed", exc_info=True)
+        return None
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Internals
+
+def _load_prompt() -> str:
+    """Read extract_intent.md from the colocated prompts/ folder."""
+    here = Path(__file__).resolve().parent
+    return (here / "prompts" / "extract_intent.md").read_text(encoding="utf-8")
+
+
+def _summarise_events(events: List[Any], steps: List[Step]) -> Dict[str, Any]:
+    """Compact event statistics for the LLM payload — keeps token cost
+    bounded while preserving signal."""
+    apps:    Counter = Counter()
+    files_created:   List[str] = []
+    files_modified:  List[str] = []
+    urls:    List[str] = []
+    clipboard_count = 0
+
+    for ev in events or []:
+        app = getattr(ev, "application", None)
+        if app:
+            apps[app] += 1
+
+        action = getattr(ev, "action", None)
+        if action == EventAction.FILE_CREATED:
+            p = getattr(ev, "file_path", None)
+            if p:
+                files_created.append(str(p))
+        elif action == EventAction.FILE_MODIFIED:
+            p = getattr(ev, "file_path", None)
+            if p:
+                files_modified.append(str(p))
+
+        if getattr(ev, "category", None) == EventCategory.CLIPBOARD:
+            clipboard_count += 1
+
+        url = getattr(ev, "url", None) or (getattr(ev, "data", {}) or {}).get("url")
+        if url:
+            urls.append(str(url))
+
+    # Keep only the most-used apps and dedup file/URL lists; cap sizes.
+    top_apps = [a for a, _ in apps.most_common(8)]
+
+    return {
+        "applications_used": top_apps,
+        "files_created":  _dedup_cap(files_created, cap=10),
+        "files_modified": _dedup_cap(files_modified, cap=10),
+        "urls_visited":   _dedup_cap(urls, cap=10),
+        "clipboard_actions": clipboard_count,
+        "step_count":  len(steps or []),
+        "total_events": len(events or []),
+    }
+
+
+def _abstract_step_titles(steps: List[Step]) -> List[str]:
+    """Produce one short line per detected step.  We deliberately keep app
+    hints out where possible — the prompt will further abstract them."""
+    out: List[str] = []
+    for s in (steps or [])[:20]:
+        # Prefer user-provided label, else fall back to primary_app + brief
+        # event-type breakdown.  Capped per step.
+        if getattr(s, "label", None):
+            out.append(f"Step {s.step_number}: {str(s.label)[:140]}")
+            continue
+
+        counts = getattr(s, "event_summary", None) or {}
+        parts: List[str] = []
+        if counts.get("file"):
+            parts.append(f"{counts['file']} file ops")
+        if counts.get("clipboard"):
+            parts.append(f"{counts['clipboard']} clipboard ops")
+        if counts.get("process"):
+            parts.append(f"{counts['process']} process ops")
+        if counts.get("window"):
+            parts.append(f"{counts['window']} window switches")
+
+        out.append(
+            f"Step {s.step_number}: "
+            + (", ".join(parts) if parts else "activity observed")
+        )
+
+    return out
+
+
+def _parse_response(raw: str) -> IntentExtraction:
+    """Tolerant JSON parser — strips code fences if the model added them."""
+    text = (raw or "").strip()
+    if text.startswith("```"):
+        # Strip code fence
+        lines = text.split("\n")
+        # Drop opening fence
+        if lines and lines[0].startswith("```"):
+            lines = lines[1:]
+        if lines and lines[-1].startswith("```"):
+            lines = lines[:-1]
+        text = "\n".join(lines).strip()
+
+    try:
+        data = json.loads(text)
+    except json.JSONDecodeError as exc:
+        logger.warning("[IntentExtractor] could not parse model output: %s", exc)
+        return IntentExtraction(confidence="low", error=f"parse_error: {exc}")
+
+    if not isinstance(data, dict):
+        return IntentExtraction(confidence="low", error="response was not a JSON object")
+
+    return IntentExtraction(
+        intent           = str(data.get("intent", ""))[:500],
+        expected_outcome = str(data.get("expected_outcome", ""))[:500],
+        success_signal   = str(data.get("success_signal", ""))[:500],
+        abstracted_steps = [str(s)[:200] for s in (data.get("abstracted_steps") or [])][:12],
+        confidence       = str(data.get("confidence", "low")).lower(),
+    )
+
+
+def _dedup_cap(items: List[str], *, cap: int) -> List[str]:
+    seen, out = set(), []
+    for x in items:
+        if x in seen:
+            continue
+        seen.add(x)
+        out.append(x)
+        if len(out) >= cap:
+            break
+    return out