logion-cli 0.1.0__py3-none-any.whl

cli/commands/courses/report_usage.py

@@ -0,0 +1,131 @@
+# SPDX-License-Identifier: MIT
+"""Agent-driven review convenience command."""
+
+from __future__ import annotations
+
+import argparse
+
+from cli._config import resolve_config_from_args
+from cli._context import make_client
+from cli._errors import handle_error, validate_uuid_id
+from cli._output import emit, emit_json
+from cli._utils import only_not_none
+
+from .reviews import _validate_review_scores
+
+
+def handle_report_usage(args: argparse.Namespace) -> int:
+    """Execute the courses report-usage command.
+
+    Thin convenience wrapper over ``reviews upsert`` for the agent-driven
+    review loop.  Same guardrails (entitlement-required, self-review-blocked)
+    apply because the call is forwarded to the same API endpoint.
+    """
+    bad_id = validate_uuid_id(args.course_id, "COURSE_ID")
+    if bad_id is not None:
+        return bad_id
+    bad_id = validate_uuid_id(args.version_id, "VERSION_ID")
+    if bad_id is not None:
+        return bad_id
+    review_scores_error = _validate_review_scores(args)
+    if review_scores_error is not None:
+        return review_scores_error
+
+    config = resolve_config_from_args(args)
+    client = make_client(config)
+    try:
+        kwargs = only_not_none(
+            {
+                "course_id": args.course_id,
+                "version_id": args.version_id,
+                "rating": args.rating,
+            },
+            body=args.body,
+            completed_task=args.completed_task,
+            reliability=args.reliability,
+            usefulness=args.usefulness,
+            tool_safety=args.tool_safety,
+            token_efficiency=args.token_efficiency,
+        )
+        result = client.v1.courses.review_version(**kwargs)
+        from cli.commands.courses._review_helpers import (
+            data_or_model_dump,
+        )
+
+        data = data_or_model_dump(result)
+        if config.json_output:
+            emit_json("logion.courses.report-usage", data)
+        else:
+            emit(result, json_output=False)
+    except Exception as exc:
+        return handle_error(exc)
+    else:
+        return 0
+    finally:
+        client.close()
+
+
+def register_report_usage(
+    subparsers: argparse._SubParsersAction,
+) -> None:
+    """Register the ``courses report-usage`` subcommand."""
+    from cli._options import COMMON_PARSER
+
+    parser = subparsers.add_parser(
+        "report-usage",
+        help="File a usage review after completing a course-driven task",
+        parents=[COMMON_PARSER],
+    )
+    parser.add_argument("course_id", metavar="COURSE_ID")
+    parser.add_argument("version_id", metavar="VERSION_ID")
+    parser.add_argument(
+        "--rating",
+        type=int,
+        required=True,
+        help="Overall rating 1-5 (required).",
+    )
+    parser.add_argument(
+        "--body",
+        default=None,
+        help="Short narrative: what worked, what didn't.",
+    )
+    completed = parser.add_mutually_exclusive_group()
+    completed.add_argument(
+        "--completed-task",
+        action="store_true",
+        default=None,
+        dest="completed_task",
+        help="The task finished successfully.",
+    )
+    completed.add_argument(
+        "--not-completed-task",
+        action="store_false",
+        default=None,
+        dest="completed_task",
+        help="The task did not finish.",
+    )
+    parser.add_argument(
+        "--reliability",
+        type=float,
+        default=None,
+        help="Did the course work without surprises? 0.0-5.0.",
+    )
+    parser.add_argument(
+        "--usefulness",
+        type=float,
+        default=None,
+        help="Did the course content help with the task? 0.0-5.0.",
+    )
+    parser.add_argument(
+        "--tool-safety",
+        type=float,
+        default=None,
+        help="Did it stay within declared capabilities? 0.0-5.0.",
+    )
+    parser.add_argument(
+        "--token-efficiency",
+        type=float,
+        default=None,
+        help="Subjective token cost impression. 0.0-5.0.",
+    )
+    parser.set_defaults(handler=handle_report_usage)

cli/commands/courses/reviews.py

@@ -0,0 +1,237 @@
+# SPDX-License-Identifier: MIT
+"""Review handlers for courses commands."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from cli._config import resolve_config_from_args
+from cli._context import make_client
+from cli._errors import (
+    handle_error,
+    print_err,
+    validate_uuid_id,
+)
+from cli._output import emit, emit_json, to_data
+from cli._utils import only_not_none
+from cli.commands.courses._capability_render import (
+    append_capability_feedback_lines,
+)
+from cli.commands.courses._review_helpers import (
+    collect_reviews,
+    compact_review,
+    compute_summary,
+    data_or_model_dump,
+)
+
+REVIEW_SCORE_FIELDS = [
+    ("reliability", "--reliability"),
+    ("usefulness", "--usefulness"),
+    ("tool_safety", "--tool-safety"),
+    ("token_efficiency", "--token-efficiency"),
+]
+
+_DEFAULT_LIST_LIMIT = 5
+_MAX_LIST_LIMIT = 50
+
+
+def _validate_review_scores(args: argparse.Namespace) -> int | None:
+    if not (1 <= args.rating <= 5):
+        print_err("Error: --rating must be between 1 and 5.")
+        return 2
+    for attr, label in REVIEW_SCORE_FIELDS:
+        value = getattr(args, attr)
+        if value is not None and not (0.0 <= value <= 5.0):
+            print_err(f"Error: {label} must be between 0.0 and 5.0.")
+            return 2
+    return None
+
+
+def handle_reviews_list(args: argparse.Namespace) -> int:
+    """Execute the courses reviews list command."""
+    bad_id = validate_uuid_id(args.course_id, "COURSE_ID")
+    if bad_id is not None:
+        return bad_id
+    config = resolve_config_from_args(args)
+    client = make_client(config)
+    try:
+        limit = min(
+            max(args.limit or _DEFAULT_LIST_LIMIT, 1),
+            _MAX_LIST_LIMIT,
+        )
+        kwargs = only_not_none(
+            {"course_id": args.course_id},
+            version=args.version,
+            limit=limit,
+            cursor=args.cursor,
+        )
+        result = client.v1.courses.list_reviews(**kwargs)
+        if config.json_output:
+            data = data_or_model_dump(result)
+            reviews = [
+                compact_review(review)
+                for review in data.get("reviews", [])
+                if isinstance(review, dict)
+            ]
+            emit_json(
+                "logion.courses.reviews.list",
+                {
+                    "items": reviews,
+                    "limit": kwargs["limit"],
+                    "next_cursor": data.get("next_cursor"),
+                },
+            )
+        else:
+            emit(result, json_output=False)
+    except Exception as exc:
+        return handle_error(exc)
+    else:
+        return 0
+    finally:
+        client.close()
+
+
+def handle_reviews_mine(args: argparse.Namespace) -> int:
+    """Execute the courses reviews mine command."""
+    bad_id = validate_uuid_id(args.course_id, "COURSE_ID")
+    if bad_id is not None:
+        return bad_id
+    if args.version_id is not None:
+        bad_id = validate_uuid_id(args.version_id, "--version-id")
+        if bad_id is not None:
+            return bad_id
+    config = resolve_config_from_args(args)
+    client = make_client(config)
+    try:
+        kwargs = only_not_none(
+            {"course_id": args.course_id},
+            version_id=args.version_id,
+        )
+        result = client.v1.courses.get_my_review(**kwargs)
+        if config.json_output:
+            data = data_or_model_dump(result)
+            emit_json("logion.courses.reviews.mine", data)
+        else:
+            emit(result, json_output=False)
+    except Exception as exc:
+        return handle_error(exc)
+    else:
+        return 0
+    finally:
+        client.close()
+
+
+def handle_reviews_upsert(args: argparse.Namespace) -> int:
+    """Execute the courses reviews upsert command."""
+    bad_id = validate_uuid_id(args.course_id, "COURSE_ID")
+    if bad_id is not None:
+        return bad_id
+    bad_id = validate_uuid_id(args.version_id, "VERSION_ID")
+    if bad_id is not None:
+        return bad_id
+    review_scores_error = _validate_review_scores(args)
+    if review_scores_error is not None:
+        return review_scores_error
+    config = resolve_config_from_args(args)
+    client = make_client(config)
+    try:
+        kwargs = only_not_none(
+            {
+                "course_id": args.course_id,
+                "version_id": args.version_id,
+                "rating": args.rating,
+            },
+            body=args.body,
+            completed_task=args.completed_task,
+            reliability=args.reliability,
+            usefulness=args.usefulness,
+            tool_safety=args.tool_safety,
+            token_efficiency=args.token_efficiency,
+        )
+        result = client.v1.courses.review_version(**kwargs)
+        if config.json_output:
+            data = data_or_model_dump(result)
+            emit_json("logion.courses.reviews.upsert", data)
+        else:
+            emit(result, json_output=False)
+    except Exception as exc:
+        return handle_error(exc)
+    else:
+        return 0
+    finally:
+        client.close()
+
+
+def handle_reviews_summary(args: argparse.Namespace) -> int:
+    """Compute aggregate review statistics for a course."""
+    bad_id = validate_uuid_id(args.course_id, "COURSE_ID")
+    if bad_id is not None:
+        return bad_id
+    config = resolve_config_from_args(args)
+    client = make_client(config)
+    try:
+        limit = min(
+            max(args.limit or _DEFAULT_LIST_LIMIT, 1),
+            _MAX_LIST_LIMIT,
+        )
+        all_reviews = collect_reviews(
+            client,
+            args.course_id,
+            version=getattr(args, "version", None),
+            limit=limit,
+        )
+        summary = compute_summary(args.course_id, all_reviews)
+        if config.json_output:
+            emit_json("logion.courses.reviews.summary", summary)
+        else:
+            lines: list[str] = [
+                f"course_id: {summary['course_id']}",
+                f"review_count: {summary['review_count']}",
+                f"rating_avg: {summary['rating_avg']}",
+                f"rating_histogram: {summary['rating_histogram']}",
+            ]
+            sys.stdout.write("\n".join(lines))
+            sys.stdout.write("\n")
+    except Exception as exc:
+        return handle_error(exc)
+    else:
+        return 0
+    finally:
+        client.close()
+
+
+def handle_feedback(args: argparse.Namespace) -> int:
+    """Execute the courses feedback command."""
+    bad_id = validate_uuid_id(args.course_id, "COURSE_ID")
+    if bad_id is not None:
+        return bad_id
+    config = resolve_config_from_args(args)
+    client = make_client(config)
+    try:
+        result = client.v1.courses.get_review_feedback(
+            course_id=args.course_id,
+        )
+        if config.json_output:
+            data = data_or_model_dump(result)
+            emit_json("logion.courses.feedback", data)
+        else:
+            data = to_data(result)
+            lines: list[str] = []
+            if data.get("summary"):
+                lines.append(f"summary: {data['summary']}")
+            if data.get("findings"):
+                lines.append("findings:")
+                for f in data["findings"]:
+                    lines.append(f"  - {f}")
+            append_capability_feedback_lines(lines, data)
+            if not lines:
+                lines.append("No feedback available.")
+            sys.stdout.write("\n".join(lines))
+            sys.stdout.write("\n")
+    except Exception as exc:
+        return handle_error(exc)
+    else:
+        return 0
+    finally:
+        client.close()

cli/commands/courses/taxonomy_handler.py

@@ -0,0 +1,61 @@
+# SPDX-License-Identifier: MIT
+"""Handler and parser registration for ``courses taxonomy`` commands."""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from cli._config import resolve_config_from_args
+from cli._options import COMMON_PARSER
+from cli._output import emit_json
+
+from .taxonomy_suggest import suggest_taxonomy
+
+
+def handle_taxonomy_suggest(args: argparse.Namespace) -> int:
+    """Produce deterministic category/tag suggestions for a local bundle."""
+    config = resolve_config_from_args(args)
+    bundle_dir: Path = args.bundle_dir
+    result = suggest_taxonomy(bundle_dir)
+    if config.json_output:
+        emit_json("logion.courses.taxonomy.suggest", result)
+    else:
+        lines: list[str] = []
+        cats = result["category_suggestions"]
+        lines.append(f"category_suggestions: {', '.join(cats)}")
+        tags = result["tag_suggestions"]
+        lines.append(f"tag_suggestions: {', '.join(tags)}")
+        rejected = result["rejected_reserved"]
+        if rejected:
+            lines.append(f"rejected_reserved: {', '.join(rejected)}")
+        lines.append(f"source: {', '.join(result['source'])}")
+        print("\n".join(lines))
+    return 0
+
+
+def register_taxonomy(
+    subparsers: argparse._SubParsersAction,
+) -> None:
+    """Register the ``courses taxonomy`` subcommand group."""
+    taxonomy = subparsers.add_parser(
+        "taxonomy",
+        help="Suggest category and tags from local course bundle text",
+    )
+    taxonomy_sub = taxonomy.add_subparsers(
+        dest="courses_taxonomy_command",
+        required=True,
+    )
+
+    suggest = taxonomy_sub.add_parser(
+        "suggest",
+        help="Suggest category and tags from SKILL.md and capabilities.yaml",
+        parents=[COMMON_PARSER],
+    )
+    suggest.add_argument(
+        "--bundle-dir",
+        type=Path,
+        required=True,
+        help="Path to the course bundle directory",
+    )
+    suggest.set_defaults(handler=handle_taxonomy_suggest)

cli/commands/courses/taxonomy_suggest.py

@@ -0,0 +1,197 @@
+# SPDX-License-Identifier: MIT
+"""Deterministic taxonomy suggestions from local course bundle text.
+
+Reads SKILL.md frontmatter and body plus an optional
+``course/capabilities.yaml`` summary, then maps keywords to category
+slugs and tag slugs. No LLM calls — the mapping is deterministic so
+agents get reproducible suggestions.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from cli._taxonomy import (
+    RESERVED_TAG_SLUGS,
+    TaxonomyValidationError,
+    normalize_tag,
+)
+from cli.commands.courses._taxonomy_data import (
+    CATEGORY_KEYWORDS,
+    STOP_WORDS,
+)
+
+_SKILL_BODY_READ_BYTES = 4096
+_MIN_TOKEN_LENGTH = 3
+
+
+def _read_skill_frontmatter(skill_path: Path) -> dict[str, Any] | None:
+    """Parse YAML frontmatter from SKILL.md, returning None if absent."""
+    if not skill_path.is_file():
+        return None
+    try:
+        text = skill_path.read_text(encoding="utf-8")
+    except OSError:
+        return None
+    if not text.startswith("---"):
+        return None
+    end = text.find("\n---\n", 3)
+    if end < 0:
+        stripped = text.rstrip()
+        if stripped.endswith("---") and text.count("---") >= 2:
+            end = stripped.rfind("---")
+            block = text[3:end].rstrip()
+        else:
+            return None
+    else:
+        block = text[3:end]
+    try:
+        parsed = yaml.safe_load(block)
+    except yaml.YAMLError:
+        return None
+    return parsed if isinstance(parsed, dict) else None
+
+
+def _read_skill_body_head(skill_path: Path) -> str:
+    """Return the first 4 KB of SKILL.md body (after frontmatter)."""
+    if not skill_path.is_file():
+        return ""
+    try:
+        text = skill_path.read_text(encoding="utf-8")
+    except OSError:
+        return ""
+    if text.startswith("---"):
+        end = text.find("\n---\n", 3)
+        body = text[end + 5 :] if end >= 0 else ""
+    else:
+        body = text
+    return body[:_SKILL_BODY_READ_BYTES]
+
+
+def _read_capabilities_summary(bundle_dir: Path) -> str:
+    """Return a text blob from ``course/capabilities.yaml`` if present."""
+    cap_path = bundle_dir / "course" / "capabilities.yaml"
+    if not cap_path.is_file():
+        return ""
+    try:
+        data = yaml.safe_load(cap_path.read_text(encoding="utf-8"))
+    except (OSError, yaml.YAMLError):
+        return ""
+    if not isinstance(data, dict):
+        return ""
+    parts: list[str] = []
+    summary = data.get("summary")
+    if isinstance(summary, str):
+        parts.append(summary)
+    tools = data.get("tools")
+    if isinstance(tools, list):
+        parts.extend(str(t) for t in tools)
+    return " ".join(parts)
+
+
+def _tokenize(text: str) -> list[str]:
+    """Lowercase, split on non-alphanumeric, drop stops and short tokens."""
+    raw = re.findall(r"[a-zA-Z0-9_-]+", text.lower())
+    tokens: list[str] = []
+    for word in raw:
+        for segment in word.split("-"):
+            segment = segment.strip("-")
+            if len(segment) >= _MIN_TOKEN_LENGTH and segment not in STOP_WORDS:
+                tokens.append(segment)
+        if len(word) >= _MIN_TOKEN_LENGTH and word not in STOP_WORDS:
+            tokens.append(word)
+    return tokens
+
+
+def _suggest_categories(tokens: list[str]) -> list[str]:
+    """Map tokens to category slugs by keyword overlap."""
+    token_set = set(tokens)
+    matches: list[str] = []
+    for category, keywords in CATEGORY_KEYWORDS.items():
+        if token_set & keywords:
+            matches.append(category)
+    if not matches:
+        return ["other"]
+    # CATEGORY_SLUGS is a frozenset (unordered); iterate CATEGORY_KEYWORDS
+    # keys instead so the output order is deterministic across processes.
+    match_set = set(matches)
+    return [c for c in CATEGORY_KEYWORDS if c in match_set]
+
+
+def _suggest_tags(tokens: list[str]) -> tuple[list[str], list[str]]:
+    """Convert tokens to valid tag slugs, rejecting reserved labels.
+
+    Returns ``(tags, rejected_reserved)``.
+    """
+    seen: set[str] = set()
+    tags: list[str] = []
+    rejected: list[str] = []
+    for token in tokens:
+        # Check reserved labels before normalize_tag, which raises on
+        # reserved slugs — we want to report them, not silently drop.
+        normalized = token.strip().lower().replace(" ", "-").replace("_", "-")
+        if normalized in RESERVED_TAG_SLUGS:
+            if normalized not in seen:
+                seen.add(normalized)
+                rejected.append(normalized)
+            continue
+        try:
+            tag = normalize_tag(token)
+        except TaxonomyValidationError:
+            continue
+        if tag in seen:
+            continue
+        seen.add(tag)
+        tags.append(tag)
+    return tags[:20], rejected
+
+
+def suggest_taxonomy(
+    bundle_dir: Path,
+) -> dict[str, Any]:
+    """Produce deterministic category and tag suggestions for a bundle.
+
+    Reads ``SKILL.md`` frontmatter (name, description) and body, plus
+    ``course/capabilities.yaml`` summary/tools. No network or LLM calls.
+    """
+    sources: list[str] = []
+    skill_path = bundle_dir / "SKILL.md"
+    text_parts: list[str] = []
+
+    frontmatter = _read_skill_frontmatter(skill_path)
+    if frontmatter is not None:
+        sources.append("SKILL.md")
+        name = frontmatter.get("name")
+        description = frontmatter.get("description")
+        if isinstance(name, str):
+            text_parts.append(name)
+        if isinstance(description, str):
+            text_parts.append(description)
+
+    body_head = _read_skill_body_head(skill_path)
+    if body_head:
+        if "SKILL.md" not in sources:
+            sources.append("SKILL.md")
+        text_parts.append(body_head)
+
+    cap_summary = _read_capabilities_summary(bundle_dir)
+    if cap_summary:
+        sources.append("course/capabilities.yaml")
+        text_parts.append(cap_summary)
+
+    combined = " ".join(text_parts)
+    tokens = _tokenize(combined)
+
+    category_suggestions = _suggest_categories(tokens)
+    tag_suggestions, rejected_reserved = _suggest_tags(tokens)
+
+    return {
+        "category_suggestions": category_suggestions,
+        "tag_suggestions": tag_suggestions,
+        "rejected_reserved": rejected_reserved,
+        "source": sources,
+    }