streamlit-coco 0.1.0__py3-none-any.whl

streamlit_coco/__init__.py

@@ -0,0 +1,115 @@
+"""Streamlit component and Python library for Snowflake CoCo.
+
+Core / headless symbols import without loading Streamlit. UI helpers
+(``panel``, ``chat``, …) are resolved lazily on first access.
+"""
+
+from __future__ import annotations
+
+from importlib import import_module
+from typing import Any
+
+from streamlit_coco.ask_user import is_ask_user_question
+from streamlit_coco.debug import is_debug_mode
+from streamlit_coco.diagnostics import CocoEnvironment, check_environment, require_environment
+from streamlit_coco.errors import (
+    ApprovalTimeoutError,
+    CLINotFoundError,
+    CLIProbeError,
+    CocoConnectionError,
+    CocoError,
+    QueryError,
+    SDKNotInstalledError,
+    SessionNotReadyError,
+    SessionStartError,
+    SnowflakeConfigNotFoundError,
+)
+from streamlit_coco.messages import CocoEvent, events_to_dataframe
+from streamlit_coco.options import CocoOptions
+from streamlit_coco.permissions import approve_pending, deny_pending
+from streamlit_coco.query import query
+from streamlit_coco.session import CocoChatResult, CocoRunStatus, CocoSession, get_session
+from streamlit_coco.tool_names import is_exit_plan_mode, is_sql_tool, tool_family
+
+__version__ = "0.1.0"
+
+# UI / Streamlit-backed exports — loaded on first attribute access.
+_LAZY_ATTRS: dict[str, tuple[str, str]] = {
+    "chat": ("streamlit_coco.component", "chat"),
+    "request_input": ("streamlit_coco.ui", "request_input"),
+    "chat_input_bar": ("streamlit_coco.bootstrap", "chat_input_bar"),
+    "get_or_create_session": ("streamlit_coco.bootstrap", "get_or_create_session"),
+    "render_environment_status": ("streamlit_coco.bootstrap", "render_environment_status"),
+    "render_start_gate": ("streamlit_coco.bootstrap", "render_start_gate"),
+    "reset_session": ("streamlit_coco.bootstrap", "reset_session"),
+    "stop_session": ("streamlit_coco.bootstrap", "stop_session"),
+    "get_latest_assistant_text": ("streamlit_coco.display", "get_latest_assistant_text"),
+    "render_output_field": ("streamlit_coco.display", "render_output_field"),
+    "render_session_status": ("streamlit_coco.display", "render_session_status"),
+    "render_transcript": ("streamlit_coco.display", "render_transcript"),
+    "panel": ("streamlit_coco.ui", "panel"),
+    "render_approvals": ("streamlit_coco.ui", "render_approvals"),
+    "render_plan_banner": ("streamlit_coco.ui", "render_plan_banner"),
+    "send_prompt": ("streamlit_coco.ui", "send_prompt"),
+}
+
+__all__ = [
+    "ApprovalTimeoutError",
+    "CLIProbeError",
+    "CLINotFoundError",
+    "CocoChatResult",
+    "CocoConnectionError",
+    "CocoEnvironment",
+    "CocoError",
+    "CocoEvent",
+    "CocoOptions",
+    "CocoRunStatus",
+    "CocoSession",
+    "QueryError",
+    "SDKNotInstalledError",
+    "SessionNotReadyError",
+    "SessionStartError",
+    "SnowflakeConfigNotFoundError",
+    "approve_pending",
+    "chat",
+    "chat_input_bar",
+    "check_environment",
+    "deny_pending",
+    "events_to_dataframe",
+    "get_or_create_session",
+    "get_session",
+    "get_latest_assistant_text",
+    "is_ask_user_question",
+    "is_debug_mode",
+    "is_exit_plan_mode",
+    "is_sql_tool",
+    "panel",
+    "query",
+    "render_approvals",
+    "render_plan_banner",
+    "require_environment",
+    "render_environment_status",
+    "render_output_field",
+    "render_session_status",
+    "render_start_gate",
+    "render_transcript",
+    "request_input",
+    "reset_session",
+    "send_prompt",
+    "stop_session",
+    "tool_family",
+]
+
+
+def __getattr__(name: str) -> Any:
+    target = _LAZY_ATTRS.get(name)
+    if target is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    module_name, attr = target
+    value = getattr(import_module(module_name), attr)
+    globals()[name] = value
+    return value
+
+
+def __dir__() -> list[str]:
+    return sorted(set(__all__) | set(globals()) | {"__version__"})

streamlit_coco/ask_user.py

@@ -0,0 +1,120 @@
+"""Helpers for CoCo AskUserQuestion tool interactions."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from streamlit_coco.tool_names import is_ask_user_question, normalize_tool_name
+
+OTHER_OPTION_LABEL = "Other..."
+
+__all__ = [
+    "OTHER_OPTION_LABEL",
+    "build_answers_payload",
+    "choice_labels_with_other",
+    "extract_questions",
+    "format_option_label",
+    "is_ask_user_question",
+    "is_other_choice",
+    "normalize_tool_name",
+    "option_is_free_form",
+    "options_already_include_other",
+    "resolve_selected_labels",
+]
+
+
+def extract_questions(tool_input: dict[str, Any] | None) -> list[dict[str, Any]]:
+    """Return the questions list from an AskUserQuestion tool input."""
+    if not isinstance(tool_input, dict):
+        return []
+    questions = tool_input.get("questions")
+    if not isinstance(questions, list):
+        return []
+    return [q for q in questions if isinstance(q, dict)]
+
+
+def build_answers_payload(
+    questions: list[dict[str, Any]],
+    answers: dict[str, str],
+) -> dict[str, Any]:
+    """Build the ``updated_input`` payload expected by the CoCo SDK."""
+    return {"questions": questions, "answers": answers}
+
+
+def format_option_label(option: dict[str, Any]) -> str:
+    """Human-readable label for a question option."""
+    label = str(option.get("label") or "").strip() or "Option"
+    description = str(option.get("description") or "").strip()
+    if description:
+        return f"{label} — {description}"
+    return label
+
+
+def option_is_free_form(option: dict[str, Any]) -> bool:
+    return bool(option.get("freeForm") or option.get("free_form"))
+
+
+def options_already_include_other(options: list[dict[str, Any]]) -> bool:
+    """True when the agent already provided an Other / free-form style choice."""
+    return any(_is_other_style_option(opt) for opt in options)
+
+
+def _is_other_style_option(option: dict[str, Any]) -> bool:
+    """True for free-form / Other / Something else choices that belong at the end."""
+    if option_is_free_form(option):
+        return True
+    label = str(option.get("label") or "").strip().lower().rstrip(".")
+    return label in {
+        "other",
+        "other...",
+        "something else",
+        "none of the above",
+        "type your own",
+        "type your own feedback",
+    }
+
+
+def choice_labels_with_other(options: list[dict[str, Any]]) -> list[str]:
+    """Display labels for widgets; free-form / Other choices always last."""
+    primary: list[str] = []
+    other_style: list[str] = []
+    for opt in options:
+        label = format_option_label(opt)
+        if _is_other_style_option(opt):
+            other_style.append(label)
+        else:
+            primary.append(label)
+    labels = primary + other_style
+    if options and not other_style:
+        labels.append(OTHER_OPTION_LABEL)
+    return labels
+
+
+def is_other_choice(value: str | None) -> bool:
+    if value is None:
+        return False
+    stripped = value.strip().lower().rstrip(".")
+    return stripped == "other" or value == OTHER_OPTION_LABEL
+
+
+def resolve_selected_labels(
+    options: list[dict[str, Any]],
+    selected: list[str] | str | None,
+) -> list[str]:
+    """Map widget selection(s) back to canonical option labels."""
+    if selected is None:
+        return []
+    values = [selected] if isinstance(selected, str) else list(selected)
+    labels_by_display = {format_option_label(opt): str(opt.get("label") or "") for opt in options}
+    labels_by_label = {str(opt.get("label") or ""): str(opt.get("label") or "") for opt in options}
+    resolved: list[str] = []
+    for value in values:
+        if is_other_choice(value):
+            resolved.append(OTHER_OPTION_LABEL)
+        elif value in labels_by_display:
+            resolved.append(labels_by_display[value])
+        elif value in labels_by_label:
+            resolved.append(labels_by_label[value])
+        elif value:
+            resolved.append(str(value))
+    return [label for label in resolved if label]

streamlit_coco/bootstrap.py

@@ -0,0 +1,198 @@
+"""High-level Streamlit helpers to keep app code small."""
+
+from __future__ import annotations
+
+import inspect
+from typing import Any
+
+import streamlit as st
+
+from streamlit_coco.diagnostics import CocoEnvironment, check_environment
+from streamlit_coco.options import CocoOptions
+from streamlit_coco.session import CocoRunStatus, CocoSession
+from streamlit_coco.ui import send_prompt
+
+
+def render_environment_status(
+    env: CocoEnvironment | None = None,
+    *,
+    connection: str | None = None,
+    stacked: bool = False,
+    show_title: bool = True,
+) -> CocoEnvironment:
+    """Render SDK / CLI / Snowflake readiness. Probes the environment when ``env`` is omitted."""
+    status = env or check_environment(connection=connection)
+    if show_title:
+        st.subheader("CoCo environment")
+
+    def _sdk_block() -> None:
+        if status.sdk_installed:
+            st.success(f"SDK installed · `{status.sdk_version or 'unknown'}`")
+        else:
+            st.error("SDK missing — `pip install cortex-code-agent-sdk`")
+
+    def _cli_block() -> None:
+        if status.cli_ok:
+            st.success(f"CLI · `{status.cli_version}`")
+            if status.cli_path:
+                st.caption(status.cli_path)
+        elif status.cli_path:
+            st.warning("CLI found but `--version` failed")
+            st.caption(status.cli_path)
+        else:
+            st.error("CLI not on PATH (`cortex`)")
+
+    def _snowflake_block() -> None:
+        display = status.snowflake_config_display
+        if display:
+            # Single line with the path (filename appears once inside it).
+            st.success(f"Snowflake config · `{display}`")
+            st.caption(f"Connection: `{status.connection_hint}`")
+        else:
+            st.warning("No `~/.snowflake/connections.toml` (or config.toml)")
+
+    if stacked:
+        _sdk_block()
+        _cli_block()
+        _snowflake_block()
+    else:
+        c1, c2, c3 = st.columns(3)
+        with c1:
+            _sdk_block()
+        with c2:
+            _cli_block()
+        with c3:
+            _snowflake_block()
+
+    return status
+
+
+def get_or_create_session(
+    options: CocoOptions,
+    *,
+    key: str = "coco",
+    sync_options: bool = True,
+) -> CocoSession:
+    """Return a ``CocoSession`` stored in ``st.session_state[key]``."""
+    session = st.session_state.get(key)
+    if session is None or not isinstance(session, CocoSession):
+        session = CocoSession(options=options, key=key)
+        st.session_state[key] = session
+    elif sync_options:
+        session.sync_options(options)
+    return session
+
+
+def render_start_gate(
+    options: CocoOptions,
+    *,
+    session_key: str = "coco",
+    gate_key: str = "coco_started",
+    title: str = "CoCo demo is ready to be instantiated",
+    button_label: str = "Start CoCo Chat",
+    body: str | None = None,
+    warm_up: bool = True,
+    env: CocoEnvironment | None = None,
+) -> bool:
+    """Landing screen with environment probe and a start button.
+
+    Returns ``True`` when the user has started CoCo (caller continues).
+    Returns ``False`` while still on the gate (caller should ``st.stop()``).
+    """
+    if gate_key not in st.session_state:
+        st.session_state[gate_key] = False
+
+    if st.session_state[gate_key]:
+        return True
+
+    status = render_environment_status(env, connection=options.connection)
+    st.divider()
+    _, center, _ = st.columns([1, 2, 1])
+    with center:
+        st.markdown(f"### {title}")
+        st.write(
+            body
+            or (
+                "Click below to create the Streamlit CoCo session, connect the Cortex Code "
+                "CLI, and open the chat panel. Nothing starts until you confirm."
+            )
+        )
+        if not status.ready:
+            st.warning(
+                "Fix the CoCo SDK / CLI issues above before starting — "
+                "the chat may fail to connect."
+            )
+        if st.button(button_label, type="primary", use_container_width=True):
+            st.session_state[gate_key] = True
+            session = CocoSession(options=options, key=session_key)
+            if warm_up:
+                session.start()
+            st.session_state[session_key] = session
+            st.rerun()
+    return False
+
+
+def reset_session(
+    options: CocoOptions,
+    *,
+    session_key: str = "coco",
+    warm_up: bool = False,
+) -> CocoSession:
+    """Replace the stored session with a fresh one."""
+    existing = st.session_state.get(session_key)
+    if isinstance(existing, CocoSession):
+        existing.reset()
+        existing.close()
+    session = CocoSession(options=options, key=session_key)
+    if warm_up:
+        session.start()
+    st.session_state[session_key] = session
+    return session
+
+
+def stop_session(
+    *,
+    session_key: str = "coco",
+    gate_key: str = "coco_started",
+) -> None:
+    """Tear down the session and return to the start gate."""
+    existing = st.session_state.get(session_key)
+    if isinstance(existing, CocoSession):
+        existing.reset()
+        existing.close()
+    st.session_state.pop(session_key, None)
+    st.session_state[gate_key] = False
+
+
+def chat_input_bar(
+    session: CocoSession,
+    *,
+    placeholder: str = "Ask CoCo…",
+    connecting_placeholder: str = "Starting CoCo…",
+    key: str | None = None,
+) -> str | None:
+    """``st.chat_input`` wired for connect/run state; sends on submit.
+
+    Stays enabled while CoCo is connecting (prompts are queued). Only a failed
+    boot disables input. ``panel()`` triggers a full rerun when connect finishes
+    so placeholder/status stay in sync.
+    """
+    connecting = session.status == CocoRunStatus.CONNECTING
+    failed_boot = session.status == CocoRunStatus.ERROR and not session.is_ready
+    kwargs: dict[str, Any] = {}
+    if key is not None:
+        kwargs["key"] = key
+    if "submit_mode" in inspect.signature(st.chat_input).parameters:
+        kwargs["disabled"] = failed_boot
+        kwargs["submit_mode"] = "disable" if session.is_running else "submit"
+    else:
+        # Streamlit < 1.59: no submit_mode — disable input while a turn is running.
+        kwargs["disabled"] = failed_boot or session.is_running
+
+    prompt = st.chat_input(
+        connecting_placeholder if connecting else placeholder,
+        **kwargs,
+    )
+    if prompt:
+        send_prompt(session, prompt)
+    return prompt

streamlit_coco/bridge.py

@@ -0,0 +1,42 @@
+"""Bridge helpers between CocoSession and Streamlit component state."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from streamlit_coco.debug import is_debug_mode
+from streamlit_coco.session import CocoSession
+
+
+def build_component_data(
+    session: CocoSession,
+    *,
+    placeholder: str,
+    show_tool_details: bool,
+    show_thinking: bool,
+    show_structured_inline: bool,
+    height: int | str,
+    include_transcript: bool = True,
+) -> dict[str, Any]:
+    pending = session.permission_manager.active_pending()
+    transcript = session.get_transcript_snapshot() if include_transcript else []
+    return {
+        "transcript": transcript,
+        "status": session.status.value,
+        "pending_approval": pending.to_dict() if pending else None,
+        "last_error": session.last_error,
+        "header": {
+            "title": "CoCo",
+            "model": session.options.model,
+            "connection": session.options.connection,
+            "permission_mode": session.options.permission_mode,
+        },
+        "placeholder": placeholder,
+        "show_tool_details": show_tool_details,
+        "debug_mode": is_debug_mode(),
+        "show_thinking": show_thinking,
+        "show_structured_inline": show_structured_inline,
+        "height": height,
+        "scroll_token": session.get_revision(),
+        "needs_polling": session.needs_polling,
+    }