cited-cli 0.3.2__py3-none-any.whl

cited_cli/commands/recommend.py

@@ -0,0 +1,211 @@
+from __future__ import annotations
+
+from typing import Annotated, Any
+
+import typer
+from rich.console import Console
+
+from cited_cli.output.formatter import OutputContext, print_error, print_result
+from cited_cli.output.tables import render_kv, render_table
+from cited_cli.utils.errors import CitedAPIError, ExitCode, handle_api_error
+from cited_cli.utils.interactive import prompt_if_missing
+from cited_core.api import endpoints
+from cited_core.api.client import LONG_TIMEOUT, CitedClient
+from cited_core.auth.store import TokenStore
+from cited_core.config.manager import ConfigManager
+
+recommend_app = typer.Typer(name="recommend", help="Generate and manage recommendations.")
+
+
+def _get_client(ctx: typer.Context) -> tuple[OutputContext, CitedClient]:
+    obj = ctx.obj or {}
+    out: OutputContext = obj.get("output", OutputContext())
+    cfg: ConfigManager = obj.get("config", ConfigManager())
+    profile = obj.get("profile", "default")
+    env = cfg.get_environment(profile, obj.get("env_override"))
+    api_url = cfg.get_api_url(profile, obj.get("env_override"))
+
+    store = TokenStore()
+    token = store.get_token(env)
+    if not token:
+        print_error(f"Not logged in to {env}. Run: cited login", out)
+        raise typer.Exit(ExitCode.AUTH_ERROR)
+
+    return out, CitedClient(base_url=api_url, token=token)
+
+
+@recommend_app.command("start")
+def recommend_start(
+    ctx: typer.Context,
+    audit_job_id: Annotated[
+        str | None,
+        typer.Argument(help="Audit job ID to generate recommendations from"),
+    ] = None,
+) -> None:
+    """Generate recommendations from an audit."""
+    out, client = _get_client(ctx)
+    audit_job_id = prompt_if_missing(audit_job_id, "AUDIT_JOB_ID", "Audit job ID", out)
+    try:
+        data = client.post(
+            endpoints.RECOMMEND_START,
+            json={"audit_job_id": audit_job_id},
+            timeout=LONG_TIMEOUT,
+        )
+        job_id = data.get("job_id", data.get("id", ""))
+        print_result(
+            data,
+            out,
+            human_formatter=lambda d, c: render_kv("Recommendations Started", d, c),
+        )
+        if not out.json_mode and job_id:
+            out.console.print(f"\nTrack progress: [bold]cited job watch {job_id}[/bold]")
+    except CitedAPIError as e:
+        handle_api_error(e, out.json_mode)
+    finally:
+        client.close()
+
+
+@recommend_app.command("status")
+def recommend_status(
+    ctx: typer.Context,
+    job_id: Annotated[str, typer.Argument(help="Recommendation job ID")],
+) -> None:
+    """Check recommendation job status."""
+    out, client = _get_client(ctx)
+    try:
+        path = endpoints.RECOMMEND_STATUS.format(job_id=job_id)
+        data = client.get(path)
+        print_result(
+            data,
+            out,
+            human_formatter=lambda d, c: render_kv("Recommendation Status", d, c),
+        )
+    except CitedAPIError as e:
+        handle_api_error(e, out.json_mode)
+    finally:
+        client.close()
+
+
+@recommend_app.command("result")
+def recommend_result(
+    ctx: typer.Context,
+    job_id: Annotated[str, typer.Argument(help="Recommendation job ID")],
+) -> None:
+    """Get recommendation results."""
+    out, client = _get_client(ctx)
+    try:
+        path = endpoints.RECOMMEND_RESULT.format(job_id=job_id)
+        data = client.get(path)
+        print_result(data, out)
+    except CitedAPIError as e:
+        handle_api_error(e, out.json_mode)
+    finally:
+        client.close()
+
+
+@recommend_app.command("insights")
+def recommend_insights(
+    ctx: typer.Context,
+    job_id: Annotated[str, typer.Argument(help="Recommendation job ID")],
+) -> None:
+    """List solution-ready insights from a recommendation job."""
+    out, client = _get_client(ctx)
+    try:
+        path = endpoints.RECOMMEND_RESULT.format(job_id=job_id)
+        data = client.get(path)
+
+        def _human(d: object, console: Console) -> None:
+            if not isinstance(d, dict):
+                console.print(d)
+                return
+            data: dict[str, Any] = d
+            rows: list[list[object]] = []
+
+            # question_insights: id=question_id, desc=question_text
+            for item in data.get("question_insights", []):
+                if not isinstance(item, dict):
+                    continue
+                source_id = item.get("question_id", item.get("id", ""))
+                desc = str(item.get("question_text", item.get("question", "")))
+                rows.append([str(len(rows) + 1), "question_insight", source_id, desc[:60]])
+
+            # head_to_head_comparisons: id=competitor_domain
+            for item in data.get("head_to_head_comparisons", data.get("head_to_head", [])):
+                if not isinstance(item, dict):
+                    continue
+                source_id = item.get("competitor_domain", item.get("id", ""))
+                desc = str(item.get("competitor_domain", item.get("description", "")))
+                rows.append([str(len(rows) + 1), "head_to_head", source_id, desc[:60]])
+
+            # strengthening_tips: id=category (no uuid), desc=title
+            for item in data.get("strengthening_tips", []):
+                if not isinstance(item, dict):
+                    continue
+                source_id = item.get("category", item.get("id", item.get("source_id", "")))
+                desc = str(item.get("title", item.get("description", "")))
+                rows.append([str(len(rows) + 1), "strengthening_tip", source_id, desc[:60]])
+
+            # priority_actions: id=id or category
+            for item in data.get("priority_actions", []):
+                if not isinstance(item, dict):
+                    continue
+                source_id = item.get("id", item.get("category", item.get("source_id", "")))
+                desc = str(item.get("title", item.get("description", item.get("action", ""))))
+                rows.append([str(len(rows) + 1), "priority_action", source_id, desc[:60]])
+
+            render_table(
+                "Available Insights",
+                ["#", "Type", "Source ID", "Description"],
+                rows,
+                console,
+            )
+            if rows:
+                console.print(
+                    "\nRun a solution: [bold]cited solution start "
+                    f"{job_id} --type <type> --source <source_id>[/bold]"
+                )
+
+        print_result(data, out, human_formatter=_human)
+    except CitedAPIError as e:
+        handle_api_error(e, out.json_mode)
+    finally:
+        client.close()
+
+
+@recommend_app.command("list")
+def recommend_list(
+    ctx: typer.Context,
+    audit_job_id: Annotated[
+        str | None,
+        typer.Option("--audit", "-a", help="Filter by audit job ID"),
+    ] = None,
+) -> None:
+    """List recommendation history."""
+    out, client = _get_client(ctx)
+    try:
+        if audit_job_id:
+            path = endpoints.RECOMMEND_HISTORY.format(audit_job_id=audit_job_id)
+            data = client.get(path)
+        else:
+            data = client.get("/recommendations/history/bulk")
+        recs = (
+            data if isinstance(data, list)
+            else data.get("recommendations", data.get("items", []))
+        )
+
+        def _human(d: object, console: Console) -> None:
+            items = d if isinstance(d, list) else []
+            rows = []
+            for r in items:
+                rows.append([
+                    r.get("job_id", r.get("id", ""))[:8],
+                    r.get("status", ""),
+                    r.get("created_at", "")[:19] if r.get("created_at") else "",
+                ])
+            render_table("Recommendations", ["Job ID", "Status", "Created"], rows, console)
+
+        print_result(recs, out, human_formatter=_human)
+    except CitedAPIError as e:
+        handle_api_error(e, out.json_mode)
+    finally:
+        client.close()

cited_cli/commands/solution.py

@@ -0,0 +1,154 @@
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+from rich.console import Console
+
+from cited_cli.output.formatter import OutputContext, print_error, print_result
+from cited_cli.output.tables import render_kv, render_table
+from cited_cli.utils.errors import CitedAPIError, ExitCode, handle_api_error
+from cited_cli.utils.interactive import prompt_choice, prompt_if_missing
+from cited_core.api import endpoints
+from cited_core.api.client import LONG_TIMEOUT, CitedClient
+from cited_core.auth.store import TokenStore
+from cited_core.config.constants import VALID_SOURCE_TYPES
+from cited_core.config.manager import ConfigManager
+
+solution_app = typer.Typer(name="solution", help="Generate and manage content solutions.")
+
+
+def _get_client(ctx: typer.Context) -> tuple[OutputContext, CitedClient, str]:
+    obj = ctx.obj or {}
+    out: OutputContext = obj.get("output", OutputContext())
+    cfg: ConfigManager = obj.get("config", ConfigManager())
+    profile = obj.get("profile", "default")
+    env = cfg.get_environment(profile, obj.get("env_override"))
+    api_url = cfg.get_api_url(profile, obj.get("env_override"))
+
+    store = TokenStore()
+    token = store.get_token(env)
+    if not token:
+        print_error(f"Not logged in to {env}. Run: cited login", out)
+        raise typer.Exit(ExitCode.AUTH_ERROR)
+
+    return out, CitedClient(base_url=api_url, token=token), env
+
+
+@solution_app.command("start")
+def solution_start(
+    ctx: typer.Context,
+    recommendation_job_id: Annotated[
+        str | None,
+        typer.Argument(help="Recommendation job ID"),
+    ] = None,
+    source_type: Annotated[
+        str | None,
+        typer.Option(
+            "--type", "-t",
+            help="Source type: question_insight, head_to_head, strengthening_tip, priority_action",
+        ),
+    ] = None,
+    source_id: Annotated[
+        str | None,
+        typer.Option("--source", "-s", help="Source ID from 'cited recommend insights'"),
+    ] = None,
+) -> None:
+    """Generate a content solution from a recommendation insight."""
+    out, client, env = _get_client(ctx)
+    recommendation_job_id = prompt_if_missing(
+        recommendation_job_id, "RECOMMENDATION_JOB_ID", "Recommendation job ID", out
+    )
+    source_type = prompt_choice(
+        source_type, "--type", "Select source type:", VALID_SOURCE_TYPES, out
+    )
+    source_id = prompt_if_missing(source_id, "--source", "Source ID", out)
+    try:
+        data = client.post(
+            endpoints.SOLUTION_REQUEST,
+            json={
+                "recommendation_job_id": recommendation_job_id,
+                "source_type": source_type,
+                "source_id": source_id,
+            },
+            timeout=LONG_TIMEOUT,
+        )
+        job_id = data.get("job_id", data.get("id", ""))
+        print_result(data, out, human_formatter=lambda d, c: render_kv("Solution Started", d, c))
+        if not out.json_mode and job_id:
+            out.console.print(f"\nTrack progress: [bold]cited job watch {job_id}[/bold]")
+            web_base = f"https://{env}.youcited.com" if env != "prod" else "https://youcited.com"
+            out.console.print(f"View artifacts: [bold]{web_base}/solutions/{job_id}[/bold]")
+    except CitedAPIError as e:
+        handle_api_error(e, out.json_mode)
+    finally:
+        client.close()
+
+
+@solution_app.command("status")
+def solution_status(
+    ctx: typer.Context,
+    job_id: Annotated[str, typer.Argument(help="Solution job ID")],
+) -> None:
+    """Check solution job status."""
+    out, client, _ = _get_client(ctx)
+    try:
+        path = endpoints.SOLUTION_STATUS.format(job_id=job_id)
+        data = client.get(path)
+        print_result(data, out, human_formatter=lambda d, c: render_kv("Solution Status", d, c))
+    except CitedAPIError as e:
+        handle_api_error(e, out.json_mode)
+    finally:
+        client.close()
+
+
+@solution_app.command("result")
+def solution_result(
+    ctx: typer.Context,
+    job_id: Annotated[str, typer.Argument(help="Solution job ID")],
+) -> None:
+    """Get solution results."""
+    out, client, _ = _get_client(ctx)
+    try:
+        path = endpoints.SOLUTION_RESULT.format(job_id=job_id)
+        data = client.get(path)
+        print_result(data, out)
+    except CitedAPIError as e:
+        handle_api_error(e, out.json_mode)
+    finally:
+        client.close()
+
+
+@solution_app.command("list")
+def solution_list(
+    ctx: typer.Context,
+    business_id: Annotated[
+        str | None,
+        typer.Option("--business", "-b", help="Filter by business ID"),
+    ] = None,
+) -> None:
+    """List solution history."""
+    out, client, _ = _get_client(ctx)
+    try:
+        params = {}
+        if business_id:
+            params["business_id"] = business_id
+        data = client.get(endpoints.SOLUTION_HISTORY, params=params or None)
+        solutions = data if isinstance(data, list) else data.get("solutions", data.get("items", []))
+
+        def _human(d: object, console: Console) -> None:
+            items = d if isinstance(d, list) else []
+            rows = []
+            for s in items:
+                rows.append([
+                    s.get("job_id", s.get("id", ""))[:8],
+                    s.get("status", ""),
+                    s.get("created_at", "")[:19] if s.get("created_at") else "",
+                ])
+            render_table("Solutions", ["Job ID", "Status", "Created"], rows, console)
+
+        print_result(solutions, out, human_formatter=_human)
+    except CitedAPIError as e:
+        handle_api_error(e, out.json_mode)
+    finally:
+        client.close()

cited_cli/config/constants.py

@@ -0,0 +1,48 @@
+from pathlib import Path
+
+ENVIRONMENTS: dict[str, str] = {
+    "prod": "https://api.youcited.com",
+    "dev": "https://dev.youcited.com",
+    "local": "http://localhost:8000",
+}
+
+FRONTEND_URLS: dict[str, str] = {
+    "prod": "https://app.youcited.com",
+    "dev": "https://dev.youcited.com",
+    "local": "http://localhost:3000",
+}
+
+DEFAULT_ENV = "prod"
+CONFIG_DIR = Path.home() / ".cited"
+CONFIG_FILE = CONFIG_DIR / "config.toml"
+CREDENTIALS_FILE = CONFIG_DIR / "credentials.json"
+KEYRING_SERVICE = "cited-cli"
+
+VALID_INDUSTRIES = [
+    "automotive",
+    "beauty",
+    "consulting",
+    "education",
+    "entertainment",
+    "finance",
+    "fitness",
+    "government",
+    "healthcare",
+    "home_services",
+    "hospitality",
+    "legal",
+    "manufacturing",
+    "non_profit",
+    "real_estate",
+    "restaurant",
+    "retail",
+    "technology",
+    "other",
+]
+
+VALID_SOURCE_TYPES = [
+    "question_insight",
+    "head_to_head",
+    "strengthening_tip",
+    "priority_action",
+]

cited_cli/config/manager.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+import tomllib
+from typing import Any
+
+import tomli_w
+
+from cited_cli.config.constants import CONFIG_DIR, CONFIG_FILE, DEFAULT_ENV, ENVIRONMENTS
+
+VALID_KEYS = {
+    "environment",
+    "default_business_id",
+    "agent_api_key",
+    "output",
+}
+
+VALID_OUTPUT_VALUES = {"json", "text"}
+
+
+class ConfigManager:
+    def __init__(self) -> None:
+        self._ensure_config_dir()
+        self._data: dict[str, Any] = self._load()
+
+    def _ensure_config_dir(self) -> None:
+        CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+
+    def _load(self) -> dict[str, Any]:
+        if not CONFIG_FILE.exists():
+            return {"default": {}}
+        with open(CONFIG_FILE, "rb") as f:
+            return tomllib.load(f)
+
+    def _save(self) -> None:
+        with open(CONFIG_FILE, "wb") as f:
+            tomli_w.dump(self._data, f)
+
+    def get(self, key: str, profile: str = "default") -> Any:
+        section = self._data.get(profile, self._data.get("default", {}))
+        return section.get(key)
+
+    def set(self, key: str, value: str, profile: str = "default") -> None:
+        if profile not in self._data:
+            self._data[profile] = {}
+        self._data[profile][key] = value
+        self._save()
+
+    def delete(self, key: str, profile: str = "default") -> bool:
+        section = self._data.get(profile, {})
+        if key in section:
+            del section[key]
+            self._save()
+            return True
+        return False
+
+    def get_all(self, profile: str = "default") -> dict[str, Any]:
+        return dict(self._data.get(profile, {}))
+
+    def get_environment(self, profile: str = "default", override: str | None = None) -> str:
+        if override:
+            return override
+        return self.get("environment", profile) or DEFAULT_ENV
+
+    def get_api_url(self, profile: str = "default", env_override: str | None = None) -> str:
+        env = self.get_environment(profile, env_override)
+        return ENVIRONMENTS.get(env, ENVIRONMENTS[DEFAULT_ENV])
+
+    def get_profiles(self) -> list[str]:
+        return [k for k in self._data if k != "default" and isinstance(self._data[k], dict)]

cited_cli/mcp/__init__.py

@@ -0,0 +1 @@
+from __future__ import annotations

cited_cli/mcp/context.py

@@ -0,0 +1,12 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from cited_cli.api.client import CitedClient
+
+
+@dataclass
+class CitedContext:
+    client: CitedClient
+    env: str
+    api_url: str

cited_cli/mcp/server.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+import os
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+
+from mcp.server.fastmcp import FastMCP
+
+from cited_cli.api.client import CitedClient
+from cited_cli.auth.store import TokenStore
+from cited_cli.config.manager import ConfigManager
+from cited_cli.mcp.context import CitedContext
+
+
+@asynccontextmanager
+async def cited_lifespan(server: FastMCP) -> AsyncIterator[CitedContext]:
+    """Set up CitedClient for the MCP server lifetime."""
+    config = ConfigManager()
+    env_override = os.environ.get("CITED_ENV")
+    env = config.get_environment(override=env_override)
+    api_url = config.get_api_url(env_override=env_override)
+
+    token = TokenStore().get_token(env)
+    agent_api_key = os.environ.get("CITED_AGENT_API_KEY") or config.get("agent_api_key")
+
+    client = CitedClient(
+        base_url=api_url,
+        token=token,
+        agent_api_key=agent_api_key,
+    )
+    try:
+        yield CitedContext(client=client, env=env, api_url=api_url)
+    finally:
+        client.close()
+
+
+mcp = FastMCP(
+    "cited",
+    instructions="Cited GEO platform — audit, optimize, and monitor AI search presence",
+    lifespan=cited_lifespan,
+)
+
+# Import tool modules to trigger @mcp.tool() registrations
+import cited_cli.mcp.tools.auth  # noqa: I001, E402, F401
+import cited_cli.mcp.tools.audit  # noqa: E402, F401
+import cited_cli.mcp.tools.business  # noqa: E402, F401
+import cited_cli.mcp.tools.job  # noqa: E402, F401
+import cited_cli.mcp.tools.recommend  # noqa: E402, F401
+import cited_cli.mcp.tools.solution  # noqa: E402, F401
+
+
+def run_server() -> None:
+    """Start the MCP server on stdio transport."""
+    mcp.run(transport="stdio")

cited_cli/mcp/tools/__init__.py

@@ -0,0 +1 @@
+from __future__ import annotations

cited_cli/mcp/tools/_helpers.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+from typing import Any
+
+from mcp.server.fastmcp import Context
+
+from cited_cli.mcp.context import CitedContext
+from cited_cli.utils.errors import CitedAPIError
+
+
+def _get_ctx(ctx: Context[Any, CitedContext, Any]) -> CitedContext:
+    """Extract CitedContext from MCP lifespan context."""
+    lc: CitedContext = ctx.request_context.lifespan_context
+    return lc
+
+
+def _auth_check(cited_ctx: CitedContext) -> dict[str, Any] | None:
+    """Return error dict if not authenticated, else None."""
+    if cited_ctx.client.token is None:
+        return {
+            "error": True,
+            "message": "Not authenticated. Run 'cited login' first.",
+        }
+    return None
+
+
+def _api_error_response(e: CitedAPIError) -> dict[str, Any]:
+    """Convert CitedAPIError to a structured error dict."""
+    return {
+        "error": True,
+        "status_code": e.status_code,
+        "message": e.message,
+    }