Implement block action registry and analysis panel with in-place component edits

Author: owenisas

backend/lambda_handler.py

@@ -171,6 +171,8 @@ def _allowed_model_hints() -> List[str]:
 _MAX_COMPONENT_EDIT_FULL_BLOCK_CONTENT_CHARS = 16000
 _MAX_COMPONENT_EDIT_FULL_BLOCK_STRUCTURED_CHARS = 12000
 _MAX_COMPONENT_EDIT_LOCAL_CONTEXT_CHARS = 600
+_MAX_COMPONENT_ANALYSIS_INSTRUCTION_CHARS = 2000
+_MAX_COMPONENT_ANALYSIS_DATA_CHARS = 12000
 
 # Module-level CORS origin for the current request (safe: Lambda = 1 request per instance)
 _current_cors_origin = ""
@@ -4890,6 +4892,254 @@ def _resolve_session_id(event):
     return ""
 
 
+def _build_component_analysis_id(
+    source_block_id: str,
+    component_type: str,
+    action: str,
+    instruction: str,
+    component_data_json: str,
+) -> str:
+    digest = hashlib.sha1(
+        f"{source_block_id}|{component_type}|{action}|{instruction}|{component_data_json}".encode("utf-8")
+    ).hexdigest()
+    return f"analysis_{digest[:20]}"
+
+
+def _normalize_component_analysis_payload(raw_body: Any) -> Dict[str, Any]:
+    if not isinstance(raw_body, dict):
+        return {}
+
+    session_id = _normalize_text(raw_body.get("session_id"), _MAX_COMPONENT_EDIT_FIELD_CHARS)
+    source_block_id = _normalize_text(raw_body.get("source_block_id"), _MAX_COMPONENT_EDIT_FIELD_CHARS)
+    component_type = _normalize_text(
+        raw_body.get("component_type"),
+        _MAX_COMPONENT_EDIT_FIELD_CHARS,
+    ).lower()
+    action = _normalize_text(raw_body.get("action") or "analyze", 40).lower()
+    instruction = _normalize_text(
+        raw_body.get("instruction") or "Analyze this component in context.",
+        _MAX_COMPONENT_ANALYSIS_INSTRUCTION_CHARS,
+    )
+    component_data = _serialize_component_edit_data(raw_body.get("component_data"))
+    model = _normalize_text(raw_body.get("model"), 80)
+
+    normalized = {
+        "session_id": session_id,
+        "source_block_id": source_block_id,
+        "component_type": component_type,
+        "action": action,
+        "instruction": instruction,
+        "component_data": component_data,
+    }
+    if model:
+        normalized["model"] = model
+    return normalized
+
+
+def handle_session_component_analysis(event):
+    """
+    Analyze a component and persist analysis records in session metadata only.
+
+    POST /session/analysis
+    """
+    try:
+        body = json.loads(event.get("body", "{}"))
+    except (TypeError, json.JSONDecodeError):
+        return create_response(400, {"error": "Invalid JSON body"})
+
+    payload = _normalize_component_analysis_payload(body)
+    session_id = str(payload.get("session_id") or "").strip()
+    source_block_id = str(payload.get("source_block_id") or "").strip()
+    component_type = str(payload.get("component_type") or "").strip().lower()
+    action = str(payload.get("action") or "").strip().lower()
+    instruction = str(payload.get("instruction") or "").strip()
+    component_data_json = str(payload.get("component_data") or "")
+
+    if not session_id:
+        return create_response(400, {"error": "Missing 'session_id'"})
+    if not source_block_id:
+        return create_response(400, {"error": "Missing 'source_block_id'"})
+    if component_type not in {"table", "graph", "image"}:
+        return create_response(400, {"error": "component_type must be one of: table, graph, image"})
+    if action != "analyze":
+        return create_response(400, {"error": "Only 'analyze' action is supported"})
+
+    auth_user = _get_authenticated_user(event)
+    session = session_store.get(session_id)
+    if not session or session.is_hidden:
+        return create_response(404, {"success": False, "error": f"Session not found: {session_id}"})
+
+    ownership_error = _enforce_session_owner(session, auth_user)
+    if ownership_error:
+        return ownership_error
+
+    source_block = find_block_by_id(session.blocks, source_block_id)
+    if not source_block:
+        return create_response(404, {"success": False, "error": f"Source block not found: {source_block_id}"})
+
+    analysis_id = _build_component_analysis_id(
+        source_block_id=source_block_id,
+        component_type=component_type,
+        action=action,
+        instruction=instruction,
+        component_data_json=component_data_json[:_MAX_COMPONENT_ANALYSIS_DATA_CHARS],
+    )
+
+    existing_records = session.analysis_records if isinstance(getattr(session, "analysis_records", None), list) else []
+    for record in existing_records:
+        if not isinstance(record, dict):
+            continue
+        if str(record.get("analysis_id") or "") != analysis_id:
+            continue
+        return create_response(
+            200,
+            {
+                "success": True,
+                "analysis_id": analysis_id,
+                "source_block_id": source_block_id,
+                "component_type": component_type,
+                "action": action,
+                "content": str(record.get("content") or ""),
+                "cached": True,
+                "updated_at": str(record.get("updated_at") or ""),
+            },
+        )
+
+    model = str(payload.get("model") or os.getenv("OPENAI_MODEL", "gpt-5.2")).strip()
+    if not _is_allowed_model(model):
+        return create_response(400, {
+            "error": f"Model '{model}' is not allowed",
+            "allowed_models": _allowed_model_hints(),
+        })
+
+    source_block_content = _trim_to_word_boundary(
+        str(source_block.content or ""),
+        _MAX_COMPONENT_EDIT_FULL_BLOCK_CONTENT_CHARS,
+    )
+    component_data_context = _trim_to_word_boundary(
+        component_data_json,
+        _MAX_COMPONENT_ANALYSIS_DATA_CHARS,
+    )
+
+    messages = [
+        {
+            "role": "system",
+            "content": (
+                "You are an analytical tutor. Explain the component clearly and concisely.\n"
+                "Focus on what the learner should notice, how to interpret it, and practical caveats.\n"
+                "Return plain markdown only."
+            ),
+        },
+        {
+            "role": "user",
+            "content": "\n".join(
+                [
+                    f"Component type: {component_type}",
+                    f"Requested action: {action}",
+                    f"Instruction: {instruction}",
+                    "",
+                    "Source block content:",
+                    source_block_content or "No source content available.",
+                    "",
+                    "Structured component data (JSON/text):",
+                    component_data_context or "No structured component data provided.",
+                ]
+            ),
+        },
+    ]
+
+    try:
+        response = llm_chat(
+            messages=messages,
+            model=model,
+            max_tokens=1200,
+            include_reasoning=False,
+            timeout=45,
+        )
+        content = str((response or {}).get("content") or "").strip() or "No analysis generated."
+    except Exception as exc:
+        logger.error("Component analysis failed: %s", exc)
+        return create_response(500, {"success": False, "error": "Failed to generate component analysis"})
+
+    updated_at = datetime.utcnow().isoformat()
+    analysis_record = {
+        "analysis_id": analysis_id,
+        "source_block_id": source_block_id,
+        "component_type": component_type,
+        "action": action,
+        "content": content,
+        "updated_at": updated_at,
+    }
+
+    session.analysis_records = [r for r in existing_records if isinstance(r, dict) and str(r.get("analysis_id") or "") != analysis_id]
+    session.analysis_records.append(analysis_record)
+    if len(session.analysis_records) > 500:
+        session.analysis_records = session.analysis_records[-500:]
+    session.updated_at = updated_at
+    session_store.save(session)
+
+    return create_response(
+        200,
+        {
+            "success": True,
+            "analysis_id": analysis_id,
+            "source_block_id": source_block_id,
+            "component_type": component_type,
+            "action": action,
+            "content": content,
+            "cached": False,
+            "updated_at": updated_at,
+        },
+    )
+
+
+def handle_list_session_component_analysis(event):
+    """
+    List stored component analysis records from session metadata.
+
+    GET /session/analysis?id=<session_id>&source_block_id=...&component_type=...&action=...
+    """
+    session_id = _resolve_session_id(event)
+    if not session_id:
+        return create_response(400, {"error": "Missing session id. Provide query parameter 'id' or body field 'session_id'."})
+
+    auth_user = _get_authenticated_user(event)
+    session = session_store.get(session_id)
+    if not session or session.is_hidden:
+        return create_response(404, {"success": False, "error": f"Session not found: {session_id}"})
+
+    ownership_error = _enforce_session_owner(session, auth_user)
+    if ownership_error:
+        return ownership_error
+
+    params = event.get("queryStringParameters") or {}
+    source_block_id = _normalize_text((params or {}).get("source_block_id"), _MAX_COMPONENT_EDIT_FIELD_CHARS)
+    component_type = _normalize_text((params or {}).get("component_type"), _MAX_COMPONENT_EDIT_FIELD_CHARS).lower()
+    action = _normalize_text((params or {}).get("action"), 40).lower()
+
+    records = session.analysis_records if isinstance(getattr(session, "analysis_records", None), list) else []
+    filtered: List[Dict[str, Any]] = []
+    for record in records:
+        if not isinstance(record, dict):
+            continue
+        if source_block_id and str(record.get("source_block_id") or "") != source_block_id:
+            continue
+        if component_type and str(record.get("component_type") or "").lower() != component_type:
+            continue
+        if action and str(record.get("action") or "").lower() != action:
+            continue
+        filtered.append(record)
+
+    return create_response(
+        200,
+        {
+            "success": True,
+            "session_id": session_id,
+            "analysis_records": filtered,
+        },
+    )
+
+
 def handle_update_session(event):
     """
     Update session metadata.
@@ -6797,6 +7047,10 @@ def handler(event, context):
         return handle_get_document_download_url(event)
     elif path == "/session" and method == "GET":
         return handle_session(event)
+    elif path == "/session/analysis" and method == "POST":
+        return handle_session_component_analysis(event)
+    elif path == "/session/analysis" and method == "GET":
+        return handle_list_session_component_analysis(event)
     elif path == "/session" and method == "PUT":
         return handle_update_session(event)
     elif path == "/session" and method == "DELETE":

backend/models.py

@@ -98,6 +98,8 @@ class Session:
     is_hidden: bool = False
     # OpenAI File Search vector store reference
     openai_vector_store_id: Optional[str] = None
+    # Non-block component analyses (panel data)
+    analysis_records: List[Dict[str, Any]] = field(default_factory=list)
 
     def add_user_message(self, content: str, attachments: Optional[List[Dict[str, Any]]] = None) -> None:
         msg: Dict[str, Any] = {"role": "user", "content": content}
@@ -200,6 +202,7 @@ def to_dict(self) -> Dict[str, Any]:
             "usage": self.usage if isinstance(self.usage, dict) else _default_usage_payload(),
             "is_hidden": self.is_hidden,
             "openai_vector_store_id": self.openai_vector_store_id,
+            "analysis_records": self.analysis_records if isinstance(self.analysis_records, list) else [],
         }
 
     @classmethod
@@ -237,6 +240,14 @@ def from_dict(cls, data: Dict[str, Any]) -> "Session":
                 usage = _default_usage_payload()
         if not isinstance(usage, dict):
             usage = _default_usage_payload()
+        analysis_records = data.get("analysis_records", [])
+        if isinstance(analysis_records, str):
+            try:
+                analysis_records = json.loads(analysis_records)
+            except Exception:
+                analysis_records = []
+        if not isinstance(analysis_records, list):
+            analysis_records = []
 
         return cls(
             id=data.get("id", str(uuid.uuid4())),
@@ -250,6 +261,7 @@ def from_dict(cls, data: Dict[str, Any]) -> "Session":
             usage=usage,
             is_hidden=bool(data.get("is_hidden", False)),
             openai_vector_store_id=data.get("openai_vector_store_id"),
+            analysis_records=analysis_records,
         )
 
 
@@ -529,6 +541,9 @@ def get(self, session_id: str) -> Optional[Session]:
                 usage_payload = self._json_loads_or_default(item.get("usage"), _default_usage_payload())
                 if not isinstance(usage_payload, dict):
                     usage_payload = _default_usage_payload()
+                analysis_records_payload = self._json_loads_or_default(item.get("analysis_records"), [])
+                if not isinstance(analysis_records_payload, list):
+                    analysis_records_payload = []
                 session = Session(
                     id=item.get("id", session_id),
                     messages=[],
@@ -542,6 +557,7 @@ def get(self, session_id: str) -> Optional[Session]:
                     usage=usage_payload,
                     is_hidden=item.get("is_hidden", False),
                     openai_vector_store_id=(item.get("openai_vector_store_id") or None),
+                    analysis_records=analysis_records_payload,
                 )
 
                 # Re-hydrate system prompt as first system message (if present).
@@ -628,6 +644,7 @@ def save(self, session: Session) -> None:
                     "usage": json.dumps(session.usage if isinstance(session.usage, dict) else _default_usage_payload()),
                     "is_hidden": session.is_hidden,
                     "openai_vector_store_id": session.openai_vector_store_id or "",
+                    "analysis_records": json.dumps(session.analysis_records if isinstance(session.analysis_records, list) else []),
                 }
 
                 self.table.put_item(Item=db_item)

backend/template.yaml

@@ -212,6 +212,18 @@ Resources:
             Path: /session
             Method: DELETE
             RestApiId: !Ref FPAIApi
+        AnalyzeSessionComponent:
+          Type: Api
+          Properties:
+            Path: /session/analysis
+            Method: POST
+            RestApiId: !Ref FPAIApi
+        ListSessionComponentAnalysis:
+          Type: Api
+          Properties:
+            Path: /session/analysis
+            Method: GET
+            RestApiId: !Ref FPAIApi
         CreateSessionShare:
           Type: Api
           Properties: