cu-cli-core 0.1.0b1__py3-none-any.whl

cu_cli_core/errors.py

@@ -0,0 +1,77 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT license.
+
+"""Frontend-neutral CU error types."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any, Mapping
+
+
+class ErrorCategory(str, Enum):
+    USAGE = "usage"
+    VALIDATION = "validation"
+    AUTHENTICATION = "authentication"
+    NOT_FOUND = "not-found"
+    CONFLICT = "conflict"
+    SERVICE = "service"
+    LOCAL_IO = "local-io"
+
+
+@dataclass(frozen=True)
+class ServiceErrorDetail:
+    code: str | None = None
+    message: str | None = None
+    target: str | None = None
+
+
+class CuCoreError(Exception):
+    """Structured failure translated by each command frontend."""
+
+    category = ErrorCategory.SERVICE
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        hint: str | None = None,
+        status_code: int | None = None,
+        details: tuple[ServiceErrorDetail, ...] = (),
+        context: Mapping[str, Any] | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.hint = hint
+        self.status_code = status_code
+        self.details = details
+        self.context = dict(context or {})
+
+
+class UsageError(CuCoreError):
+    category = ErrorCategory.USAGE
+
+
+class ValidationError(CuCoreError):
+    category = ErrorCategory.VALIDATION
+
+
+class AuthenticationError(CuCoreError):
+    category = ErrorCategory.AUTHENTICATION
+
+
+class NotFoundError(CuCoreError):
+    category = ErrorCategory.NOT_FOUND
+
+
+class ConflictError(CuCoreError):
+    category = ErrorCategory.CONFLICT
+
+
+class ServiceError(CuCoreError):
+    category = ErrorCategory.SERVICE
+
+
+class LocalIOError(CuCoreError):
+    category = ErrorCategory.LOCAL_IO

cu_cli_core/input_planning.py

@@ -0,0 +1,322 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT license.
+
+from __future__ import annotations
+
+from collections import Counter
+from fnmatch import fnmatch
+import hashlib
+import os
+from pathlib import Path
+from typing import Iterable, Sequence
+
+from .contracts import (
+    ExecutionPlan,
+    ExistingResultPolicy,
+    InputOrigin,
+    InputPlan,
+    PlannedInput,
+    PlannedOutput,
+    ResultView,
+    SelectionMode,
+    SkippedInput,
+)
+from .errors import UsageError, ValidationError
+
+_WILDCARD_CHARS = frozenset("*?[")
+_RESULT_SUFFIX = {
+    ResultView.LLM_INPUT: ".result.md",
+    ResultView.FULL: ".result.json",
+}
+_GENERATED_RESULT_SUFFIXES = tuple(_RESULT_SUFFIX.values())
+
+
+def _reject_direct_duplicates(values: Sequence[str | Path], option: str) -> None:
+    rendered = [os.fspath(value) for value in values]
+    duplicates = sorted(value for value, count in Counter(rendered).items() if count > 1)
+    if duplicates:
+        joined = ", ".join(duplicates)
+        raise UsageError(f"{option} was provided more than once for: {joined}")
+
+
+def _file_identity(path: Path) -> object:
+    stat = path.stat()
+    if stat.st_ino:
+        return (stat.st_dev, stat.st_ino)
+    return os.path.normcase(os.fspath(path.resolve()))
+
+
+def _validated_file(path: Path, *, option: str) -> tuple[Path, int]:
+    if not path.exists():
+        raise ValidationError(f"{option} does not exist: {path}")
+    if not path.is_file():
+        raise ValidationError(f"{option} must identify a file: {path}")
+    try:
+        stat = path.stat()
+    except OSError as exc:
+        raise ValidationError(f"{option} cannot be read: {path}") from exc
+    return path.resolve(), stat.st_size
+
+
+def _validated_source(path: Path, *, option: str) -> Path:
+    if not path.exists():
+        raise ValidationError(f"{option} does not exist: {path}")
+    if not path.is_dir():
+        raise ValidationError(f"{option} must identify a directory: {path}")
+    return path.resolve()
+
+
+def _directory_files(
+    source: Path,
+    *,
+    recursive: bool,
+    pattern: str,
+    skipped: dict[Path, SkippedInput],
+) -> Iterable[Path]:
+    candidates = source.rglob("*") if recursive else source.iterdir()
+    files = (path for path in candidates if path.is_file())
+    selected: list[Path] = []
+    for path in files:
+        relative_path = path.relative_to(source)
+        if not fnmatch(relative_path.as_posix(), pattern):
+            continue
+        if path.name.endswith(_GENERATED_RESULT_SUFFIXES):
+            continue
+        if any(part.startswith(".") for part in relative_path.parts[:-1]):
+            continue
+        if path.name.startswith("."):
+            skipped.setdefault(
+                path,
+                SkippedInput(path=path, reason="hidden file skipped"),
+            )
+            continue
+        selected.append(path)
+    return sorted(selected, key=lambda path: path.relative_to(source).as_posix())
+
+
+def plan_inputs(
+    *,
+    positional: Sequence[str | Path] = (),
+    files: Sequence[str | Path] = (),
+    sources: Sequence[str | Path] = (),
+    pattern: str | None = None,
+    recursive: bool = False,
+) -> InputPlan:
+    """Validate and expand one invocation's local input selection."""
+    if positional and (files or sources):
+        conflicts = []
+        if files:
+            conflicts.append("--file")
+        if sources:
+            conflicts.append("--source")
+        raise UsageError(
+            "positional inputs cannot be combined with " + " or ".join(conflicts) + "."
+        )
+    if files and sources:
+        raise UsageError("--file and --source cannot be combined.")
+    if pattern is not None and not sources:
+        raise UsageError("--pattern is valid only with --source.")
+    if not positional and not files and not sources:
+        raise UsageError("provide positional inputs, --file, or --source.")
+
+    if positional:
+        mode = SelectionMode.POSITIONAL
+        direct = positional
+        option = "positional input"
+    elif files:
+        mode = SelectionMode.NAMED_FILES
+        direct = files
+        option = "--file"
+    else:
+        mode = SelectionMode.NAMED_SOURCES
+        direct = sources
+        option = "--source"
+    _reject_direct_duplicates(direct, option)
+
+    selected: list[PlannedInput] = []
+    seen: set[object] = set()
+    skipped: dict[Path, SkippedInput] = {}
+    includes_directory = bool(sources)
+
+    def add_file(
+        path: Path,
+        *,
+        source_root: Path,
+        relative_path: Path,
+        origin: InputOrigin,
+    ) -> None:
+        resolved, size = _validated_file(path, option=option)
+        identity = _file_identity(resolved)
+        if identity in seen:
+            return
+        seen.add(identity)
+        selected.append(
+            PlannedInput(
+                path=resolved,
+                source_root=source_root,
+                relative_path=relative_path,
+                origin=origin,
+                size_bytes=size,
+            )
+        )
+
+    if positional:
+        for value in positional:
+            text = os.fspath(value)
+            if any(char in text for char in _WILDCARD_CHARS):
+                raise UsageError(
+                    f"wildcard patterns aren't accepted as positional inputs: {text}",
+                    hint='Use --source with --pattern, for example: --source . --pattern "*.pdf"',
+                )
+            path = Path(value)
+            if not path.exists():
+                raise ValidationError(f"positional input does not exist: {path}")
+            if path.is_dir():
+                includes_directory = True
+                source = _validated_source(path, option=option)
+                for child in _directory_files(
+                    source,
+                    recursive=recursive,
+                    pattern="*",
+                    skipped=skipped,
+                ):
+                    add_file(
+                        child,
+                        source_root=source,
+                        relative_path=child.relative_to(source),
+                        origin=InputOrigin.POSITIONAL_SOURCE,
+                    )
+            else:
+                resolved, _ = _validated_file(path, option=option)
+                add_file(
+                    resolved,
+                    source_root=resolved.parent,
+                    relative_path=Path(resolved.name),
+                    origin=InputOrigin.POSITIONAL_FILE,
+                )
+    elif files:
+        for value in files:
+            path, _ = _validated_file(Path(value), option=option)
+            add_file(
+                path,
+                source_root=path.parent,
+                relative_path=Path(path.name),
+                origin=InputOrigin.NAMED_FILE,
+            )
+    else:
+        effective_pattern = pattern if pattern is not None else "*"
+        if not effective_pattern:
+            raise UsageError("--pattern cannot be empty.")
+        for value in sources:
+            source = _validated_source(Path(value), option=option)
+            for child in _directory_files(
+                source,
+                recursive=recursive,
+                pattern=effective_pattern,
+                skipped=skipped,
+            ):
+                add_file(
+                    child,
+                    source_root=source,
+                    relative_path=child.relative_to(source),
+                    origin=InputOrigin.NAMED_SOURCE,
+                )
+
+    if recursive and not includes_directory:
+        raise UsageError("--recursive is valid only when input selection includes a directory.")
+    if not selected:
+        if skipped:
+            details = ", ".join(
+                f"{item.path} ({item.reason})"
+                for item in skipped.values()
+            )
+            raise ValidationError(
+                "input selection did not find any analyzable files. "
+                f"Skipped during discovery: {details}."
+            )
+        raise ValidationError("input selection did not find any files.")
+
+    extension_counts = Counter(
+        item.path.suffix.lower() or "(none)" for item in selected
+    )
+    return InputPlan(
+        mode=mode,
+        inputs=tuple(selected),
+        recursive=recursive,
+        pattern=pattern,
+        total_bytes=sum(item.size_bytes for item in selected),
+        extension_counts=dict(sorted(extension_counts.items())),
+        skipped=tuple(
+            skipped[path]
+            for path in sorted(skipped, key=lambda path: os.fspath(path))
+        ),
+    )
+
+
+def _result_path(path: Path, view: ResultView) -> Path:
+    return Path(f"{path}{_RESULT_SUFFIX[view]}")
+
+
+def plan_outputs(
+    input_plan: InputPlan,
+    *,
+    view: ResultView,
+    output_file: str | Path | None = None,
+    output_dir: str | Path | None = None,
+    on_existing: ExistingResultPolicy = ExistingResultPolicy.ERROR,
+    stream_single: bool = True,
+    dry_run: bool = False,
+) -> ExecutionPlan:
+    """Resolve result destinations, collisions, and existing-file actions."""
+    if output_file is not None and output_dir is not None:
+        raise UsageError("--output-file and --output-dir cannot be combined.")
+    if output_file is not None and len(input_plan.inputs) != 1:
+        raise UsageError("--output-file is valid only when exactly one file is selected.")
+
+    destinations: list[Path | None] = []
+    for item in input_plan.inputs:
+        if output_file is not None:
+            destination = Path(output_file)
+        elif output_dir is not None:
+            relative = item.relative_path
+            if relative.is_absolute() or ".." in relative.parts:
+                raise ValidationError(
+                    f"source-relative output path is invalid: {relative}"
+                )
+            destination = _result_path(Path(output_dir) / relative, view)
+        elif stream_single and len(input_plan.inputs) == 1:
+            destination = None
+        else:
+            destination = _result_path(item.path, view)
+        destinations.append(destination)
+
+    counts = Counter(path for path in destinations if path is not None)
+    collided = {path for path, count in counts.items() if count > 1}
+    for index, destination in enumerate(destinations):
+        if destination not in collided:
+            continue
+        digest = hashlib.sha1(
+            os.fspath(input_plan.inputs[index].path).encode("utf-8")
+        ).hexdigest()[:8]
+        suffix = _RESULT_SUFFIX[view]
+        assert destination is not None
+        base = destination.name[: -len(suffix)]
+        destinations[index] = destination.with_name(f"{base}.{digest}{suffix}")
+
+    outputs: list[PlannedOutput] = []
+    for item, destination in zip(input_plan.inputs, destinations, strict=True):
+        exists = destination is not None and destination.exists()
+        outputs.append(
+            PlannedOutput(
+                source=item,
+                path=destination,
+                exists=exists,
+                skipped=exists and on_existing is ExistingResultPolicy.SKIP,
+            )
+        )
+    return ExecutionPlan(
+        input_plan=input_plan,
+        outputs=tuple(outputs),
+        on_existing=on_existing,
+        dry_run=dry_run,
+    )

cu_cli_core/operations/__init__.py

@@ -0,0 +1,4 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT license.
+
+"""Client-injected Content Understanding operations."""

cu_cli_core/operations/analysis.py

@@ -0,0 +1,294 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT license.
+
+"""Shared orchestration for analyze and analyzer-test commands."""
+
+from __future__ import annotations
+
+from typing import Any, Callable
+
+from ..analysis import AnalyzeJob, AnalyzeOutcome, BatchResult, analyze_many
+from ..contracts import AnalyzeRequest, AnalyzerTestRequest, InputPlan
+from ..input_planning import plan_inputs
+
+_TEST_DISCLAIMER = (
+    "This is not a real accuracy benchmark. It only checks whether a value was "
+    "extracted or generated, and reports confidence when the service returns it."
+)
+
+
+def _input_plan(request: AnalyzeRequest | AnalyzerTestRequest) -> InputPlan:
+    return plan_inputs(
+        positional=request.positional_inputs,
+        files=request.files,
+        sources=request.sources,
+        pattern=request.pattern,
+        recursive=request.recursive,
+    )
+
+
+def execute_analyze(
+    client: Any,
+    request: AnalyzeRequest,
+    *,
+    input_plan: InputPlan | None = None,
+    jobs: list[AnalyzeJob] | None = None,
+    on_result: Callable[[AnalyzeOutcome], None] | None = None,
+    run: Callable[[Any, AnalyzeJob], Any] | None = None,
+) -> BatchResult:
+    """Execute a normalized analyze request against an injected client."""
+
+    planned = input_plan or _input_plan(request)
+    selected_jobs = jobs or [
+        AnalyzeJob(
+            input_ref=str(item.path),
+            analyzer_id=request.analyzer or "",
+            out_path=None,
+        )
+        for item in planned.inputs
+    ]
+    return analyze_many(
+        client,
+        selected_jobs,
+        concurrency=request.concurrency,
+        on_result=on_result,
+        run=run,
+    )
+
+
+def _field_as_dict(value: Any) -> dict[str, Any] | None:
+    if isinstance(value, dict):
+        return value
+    if hasattr(value, "as_dict"):
+        mapped = value.as_dict()
+        return mapped if isinstance(mapped, dict) else None
+    return None
+
+
+def _coerce_field_value(field: Any) -> Any:
+    if field is None or isinstance(field, (str, int, float, bool)):
+        return field
+    mapped = _field_as_dict(field)
+    if mapped is None:
+        return str(field)
+    for key in (
+        "valueString",
+        "valueNumber",
+        "valueInteger",
+        "valueBoolean",
+        "valueDate",
+        "valueTime",
+        "valueJson",
+    ):
+        if mapped.get(key) is not None:
+            return mapped[key]
+    if mapped.get("valueArray") is not None:
+        return [_coerce_field_value(value) for value in mapped["valueArray"]]
+    if isinstance(mapped.get("valueObject"), dict):
+        return {
+            key: _coerce_field_value(value)
+            for key, value in mapped["valueObject"].items()
+        }
+    for key in ("value", "content"):
+        if mapped.get(key) is not None:
+            return mapped[key]
+    return None
+
+
+def _coerce_field_confidence(field: Any) -> float | None:
+    confidence = (
+        field.get("confidence")
+        if isinstance(field, dict)
+        else getattr(field, "confidence", None)
+    )
+    if confidence is None:
+        mapped = _field_as_dict(field)
+        confidence = mapped.get("confidence") if mapped else None
+    try:
+        return float(confidence) if confidence is not None else None
+    except (TypeError, ValueError):
+        return None
+
+
+def _child_field_entries(
+    field_name: str,
+    field: Any,
+) -> dict[str, dict[str, Any]]:
+    mapped = _field_as_dict(field)
+    if mapped is None:
+        return {}
+    value_object = mapped.get("valueObject")
+    if isinstance(value_object, dict):
+        return {
+            f"{field_name}.{name}": {
+                "value": _coerce_field_value(value),
+                "confidence": _coerce_field_confidence(value),
+            }
+            for name, value in value_object.items()
+        }
+
+    value_array = mapped.get("valueArray")
+    if not isinstance(value_array, list):
+        return {}
+    child_values: dict[str, list[Any]] = {}
+    child_confidences: dict[str, list[float]] = {}
+    for item in value_array:
+        item_mapping = _field_as_dict(item)
+        item_object = item_mapping.get("valueObject") if item_mapping else None
+        if not isinstance(item_object, dict):
+            continue
+        for name, value in item_object.items():
+            child_values.setdefault(name, []).append(_coerce_field_value(value))
+            confidence = _coerce_field_confidence(value)
+            if confidence is not None:
+                child_confidences.setdefault(name, []).append(confidence)
+    return {
+        f"{field_name}[].{name}": {
+            "value": values,
+            "confidence": (
+                round(sum(child_confidences[name]) / len(child_confidences[name]), 3)
+                if child_confidences.get(name)
+                else None
+            ),
+        }
+        for name, values in child_values.items()
+    }
+
+
+def extract_fields_from_result(result: Any) -> dict[str, dict[str, Any]]:
+    """Flatten result fields for analyzer-test coverage reporting."""
+
+    extracted: dict[str, dict[str, Any]] = {}
+    for content in getattr(result, "contents", None) or []:
+        fields = getattr(content, "fields", None)
+        if fields is None:
+            continue
+        if hasattr(fields, "items"):
+            items = fields.items()
+        elif hasattr(fields, "as_dict"):
+            items = fields.as_dict().items()
+        else:
+            continue
+        for name, value in items:
+            if name in extracted and extracted[name].get("value") not in (
+                None,
+                "",
+                [],
+                {},
+            ):
+                continue
+            extracted[name] = {
+                "value": _coerce_field_value(value),
+                "confidence": _coerce_field_confidence(value),
+            }
+            extracted.update(_child_field_entries(name, value))
+    return extracted
+
+
+def _is_populated_value(value: Any) -> bool:
+    if value is None or value == "":
+        return False
+    if isinstance(value, dict):
+        return any(_is_populated_value(item) for item in value.values())
+    if isinstance(value, list):
+        return any(_is_populated_value(item) for item in value)
+    return True
+
+
+def analyzer_test_summary(samples: list[dict[str, Any]]) -> dict[str, Any]:
+    """Build deterministic field-coverage and confidence statistics."""
+
+    low_threshold = 0.6
+    total = len(samples)
+    succeeded = sum(sample.get("status") == "ok" for sample in samples)
+    field_names = {
+        name
+        for sample in samples
+        for name in (sample.get("fields") or {})
+    }
+    per_field: dict[str, dict[str, Any]] = {}
+    for name in sorted(field_names):
+        populated = 0
+        low = 0
+        confidences: list[float] = []
+        for sample in samples:
+            field = (sample.get("fields") or {}).get(name)
+            if field is None or field.get("value") is None:
+                continue
+            if _is_populated_value(field["value"]):
+                populated += 1
+            confidence = field.get("confidence")
+            if isinstance(confidence, (int, float)):
+                confidences.append(float(confidence))
+                if confidence < low_threshold:
+                    low += 1
+        per_field[name] = {
+            "populated": populated,
+            "populatedPct": round(populated / total * 100, 1) if total else 0.0,
+            "meanConfidence": (
+                round(sum(confidences) / len(confidences), 3)
+                if confidences
+                else None
+            ),
+            "lowConfidenceCount": low,
+        }
+    return {
+        "samplesTotal": total,
+        "samplesOk": succeeded,
+        "samplesFailed": total - succeeded,
+        "disclaimer": _TEST_DISCLAIMER,
+        "fields": per_field,
+        "lowConfidenceThreshold": low_threshold,
+    }
+
+
+def execute_analyzer_test(
+    client: Any,
+    request: AnalyzerTestRequest,
+    *,
+    input_plan: InputPlan | None = None,
+    run: Callable[[Any, AnalyzeJob], Any] | None = None,
+) -> dict[str, Any]:
+    """Execute analyzer test samples and return a frontend-neutral report."""
+
+    planned = input_plan or _input_plan(request)
+    refs = [str(item.path) for item in planned.inputs]
+    jobs = [
+        AnalyzeJob(input_ref=ref, analyzer_id=request.name, out_path=None)
+        for ref in refs
+    ]
+    samples: list[dict[str, Any]] = []
+
+    def collect(outcome: AnalyzeOutcome) -> None:
+        if outcome.ok:
+            samples.append(
+                {
+                    "input": outcome.job.input_ref,
+                    "status": "ok",
+                    "fields": extract_fields_from_result(outcome.result),
+                }
+            )
+        else:
+            samples.append(
+                {
+                    "input": outcome.job.input_ref,
+                    "status": "error",
+                    "error": str(outcome.error)[:500],
+                    "fields": {},
+                }
+            )
+
+    analyze_many(
+        client,
+        jobs,
+        concurrency=request.concurrency,
+        on_result=collect,
+        run=run,
+    )
+    order = {ref: index for index, ref in enumerate(refs)}
+    samples.sort(key=lambda sample: order.get(sample["input"], 0))
+    return {
+        "analyzerId": request.name,
+        "summary": analyzer_test_summary(samples),
+        "samples": samples,
+    }