@adgine/geo-cli 1.2.8

package/skills/adgine-geo-content/scripts/generate_article.py

@@ -0,0 +1,108 @@
+#!/usr/bin/env python3
+"""Generate a full article from an approved outline (async job).
+
+The content item must have status='outline' and a completed outline.
+Polls until the article is done (~5–10 min), then prints a summary.
+
+Usage:
+  python3 scripts/generate_article.py --content-id <cid> [--project-id <id>] [--json]
+"""
+import sys
+import os
+import argparse
+
+sys.path.insert(0, os.path.dirname(__file__))
+from _client import (
+    get_api_config, get_project_id,
+    api_get, api_post,
+    extract_data, poll_job, print_json,
+)
+
+parser = argparse.ArgumentParser(description="Generate a full article from outline")
+parser.add_argument("--content-id", required=True,
+                    help="Content item ID (must have status=outline)")
+parser.add_argument("--project-id", help="Project ID (or set GEO_PROJECT_ID env var)")
+parser.add_argument("--json", action="store_true", help="Output raw job result as JSON")
+parser.add_argument("--show-article", action="store_true",
+                    help="Print the full article text (can be long)")
+args = parser.parse_args()
+
+key, base = get_api_config()
+pid = get_project_id(args.project_id)
+
+# Quick pre-check: verify content exists and has outline status
+content_result = api_get(f"/api/projects/{pid}/content/{args.content_id}", key, base)
+content = extract_data(content_result)
+status = content.get("status", "")
+if status not in ("outline", "article"):
+    print(f"WARNING: Content status is '{status}'. Expected 'outline' to generate an article.")
+    if status == "draft":
+        print("  Generate an outline first: python3 scripts/generate_outline.py --topic-id <tid> --prompt-ids <ids>")
+        sys.exit(1)
+
+title = content.get("article_title") or "(untitled)"
+print(f"Generating article for: {title}")
+print(f"  Content ID : {args.content_id}")
+print()
+
+body = {"content_id": args.content_id}
+result = api_post(f"/api/projects/{pid}/content/generate-article", key, base, body)
+job_data = extract_data(result)
+
+job_id = job_data.get("job_id") or job_data.get("id") or job_data.get("article_job_id")
+if not job_id:
+    print("ERROR: Article generate endpoint did not return a job ID.")
+    print_json(job_data)
+    sys.exit(1)
+
+print(f"Job ID: {job_id}")
+print("Polling for completion (this typically takes 5–10 minutes)...")
+
+# Job status polled via: api_get(f"/api/projects/{pid}/content/jobs/{job_id}", key, base)
+final_job = poll_job(
+    f"/api/projects/{pid}/content/jobs/{job_id}",
+    key, base,
+    interval=10,
+    max_wait=900,
+)
+
+if args.json:
+    print_json(final_job)
+    sys.exit(0)
+
+if final_job.get("status") == "failed":
+    print(f"ERROR: Article generation failed — {final_job.get('error', 'unknown error')}")
+    sys.exit(1)
+
+output = final_job.get("output") or {}
+content_id_out = output.get("content_id") or args.content_id
+
+# Retrieve the final content
+final_content_result = api_get(f"/api/projects/{pid}/content/{content_id_out}", key, base)
+article = extract_data(final_content_result)
+
+    print(f"\nArticle generation completed!")
+    print(f"  Content ID     : {article.get('id')}")
+    print(f"  Title          : {article.get('article_title') or '(untitled)'}")
+    print(f"  Status         : {article.get('status')}")
+    print(f"  Publish status : {article.get('publish_status') or '—'}")
+    print(f"  Word count     : {article.get('word_count', 0)}")
+    print(f"  Meta title     : {(article.get('meta_title') or '—')[:80]}")
+    print(f"  Meta desc      : {(article.get('meta_description') or '—')[:120]}")
+    print(f"  Slug           : {article.get('meta_slug') or '—'}")
+
+if article.get("faq_section"):
+    print(f"\n[FAQ Section — first 500 chars]")
+    faq = article["faq_section"]
+    print(faq[:500] + ("..." if len(faq) > 500 else ""))
+
+if args.show_article:
+    full = article.get("full_content") or article.get("article_body") or ""
+    if full:
+        print(f"\n{'='*60}")
+        print(full)
+    else:
+        print("\nno full_content returned yet")
+else:
+    print(f"\nTo print the full article, re-run with --show-article")
+    print(f"  python3 scripts/generate_article.py --content-id {content_id_out} --show-article")

package/skills/adgine-geo-content/scripts/generate_outline.py

@@ -0,0 +1,113 @@
+#!/usr/bin/env python3
+"""Generate an AI-optimized article outline (async job).
+
+Starts an outline generation job, polls until completed (~10–15 min), then prints
+the outline and the content_id needed for article generation.
+
+Usage:
+  python3 scripts/generate_outline.py \
+    --topic-id <tid> --prompt-ids <id1,id2,...> \
+    [--project-id <id>] [--title "Your Article Title"] \
+    [--reference-urls "https://url1,https://url2"] \
+    [--instructions "Target CMO audience, emphasize ROI"] \
+    [--json]
+"""
+import sys
+import os
+import argparse
+
+sys.path.insert(0, os.path.dirname(__file__))
+from _client import (
+    get_api_config, get_project_id,
+    api_post, extract_data, poll_job, print_json,
+)
+
+parser = argparse.ArgumentParser(description="Generate GEO article outline")
+parser.add_argument("--topic-id",       required=True, help="Topic ID")
+parser.add_argument("--prompt-ids",     required=True, help="Comma-separated prompt IDs")
+parser.add_argument("--project-id",     help="Project ID (or set GEO_PROJECT_ID env var)")
+parser.add_argument("--title",          help="Article title (auto-generated if omitted)")
+parser.add_argument("--reference-urls", help="Comma-separated reference/competitor URLs")
+parser.add_argument("--instructions",   help="Additional AI guidance (audience, tone, focus)")
+parser.add_argument("--json", action="store_true", help="Output raw job result as JSON")
+args = parser.parse_args()
+
+key, base = get_api_config()
+pid = get_project_id(args.project_id)
+
+prompt_ids = [p.strip() for p in args.prompt_ids.split(",") if p.strip()]
+if not prompt_ids:
+    print("ERROR: --prompt-ids must contain at least one ID")
+    sys.exit(1)
+
+body = {
+    "topic_id":  args.topic_id,
+    "prompt_ids": prompt_ids,
+}
+if args.title:
+    body["article_title"] = args.title
+if args.reference_urls:
+    body["reference_urls"] = [u.strip() for u in args.reference_urls.split(",") if u.strip()]
+if args.instructions:
+    body["custom_instructions"] = args.instructions
+
+print(f"Starting outline generation...")
+print(f"  Topic     : {args.topic_id}")
+print(f"  Prompts   : {len(prompt_ids)}")
+if args.title:
+    print(f"  Title     : {args.title}")
+print()
+
+result = api_post(f"/api/projects/{pid}/content/generate-outline", key, base, body)
+job_data = extract_data(result)
+
+# The response may contain the job directly (id = job id) or have separate job_id / content_id fields
+job_id     = job_data.get("job_id") or job_data.get("outline_job_id") or job_data.get("id")
+content_id = job_data.get("content_id")  # may be None; resolved from job output after polling
+
+if not job_id:
+    print("ERROR: Outline endpoint did not return a job ID.")
+    print_json(job_data)
+    sys.exit(1)
+
+print(f"Job ID: {job_id}")
+print("Polling for completion (this typically takes 10–15 minutes)...")
+
+# Job status polled via: api_get(f"/api/projects/{pid}/content/jobs/{job_id}", key, base)
+final_job = poll_job(
+    f"/api/projects/{pid}/content/jobs/{job_id}",
+    key, base,
+    interval=10,
+    max_wait=1200,
+)
+
+if args.json:
+    print_json(final_job)
+    sys.exit(0)
+
+status = final_job.get("status", "")
+if status == "failed":
+    print(f"ERROR: Outline generation failed — {final_job.get('error', 'unknown error')}")
+    sys.exit(1)
+
+output = final_job.get("output") or {}
+content_id = output.get("content_id") or content_id
+title      = output.get("article_title") or args.title or "(auto-generated)"
+outline    = output.get("page_outline") or ""
+
+print(f"\nOutline generation completed!")
+print(f"  Content ID : {content_id}")
+print(f"  Title      : {title}")
+print()
+
+if outline:
+    # Print first 2000 chars of outline
+    if len(outline) > 2000:
+        print(outline[:2000])
+        print(f"\n  [... outline continues — {len(outline)} chars total ...]")
+    else:
+        print(outline)
+
+print()
+print("Next: generate the full article with:")
+print(f"  python3 scripts/generate_article.py --content-id {content_id}")

package/skills/adgine-geo-content/scripts/generate_titles.py

@@ -0,0 +1,51 @@
+#!/usr/bin/env python3
+"""Suggest article titles for a given topic and set of prompts (sync, fast).
+
+Usage:
+  python3 scripts/generate_titles.py --topic-id <tid> --prompt-ids <id1,id2,...>
+                                    [--project-id <id>] [--json]
+"""
+import sys
+import os
+import argparse
+
+sys.path.insert(0, os.path.dirname(__file__))
+from _client import get_api_config, get_project_id, api_post, extract_data, print_json
+
+parser = argparse.ArgumentParser(description="Suggest article titles for a topic")
+parser.add_argument("--topic-id",   required=True, help="Topic ID")
+parser.add_argument("--prompt-ids", required=True, help="Comma-separated prompt IDs")
+parser.add_argument("--project-id", help="Project ID (or set GEO_PROJECT_ID env var)")
+parser.add_argument("--json", action="store_true", help="Output raw JSON")
+args = parser.parse_args()
+
+key, base = get_api_config()
+pid = get_project_id(args.project_id)
+
+prompt_ids = [p.strip() for p in args.prompt_ids.split(",") if p.strip()]
+if not prompt_ids:
+    print("ERROR: --prompt-ids must contain at least one prompt ID")
+    sys.exit(1)
+
+body = {
+    "topic_id":  args.topic_id,
+    "prompt_ids": prompt_ids,
+}
+
+result = api_post(f"/api/projects/{pid}/content/generate-titles", key, base, body)
+data = extract_data(result)
+
+if args.json:
+    print_json(data)
+    sys.exit(0)
+
+titles = data.get("titles") or (data if isinstance(data, list) else [])
+print(f"Suggested titles ({len(titles)}):")
+print()
+for i, title in enumerate(titles, 1):
+    print(f"  {i:>2}. {title}")
+
+print()
+print("Use a title with generate_outline.py:")
+print(f"  python3 scripts/generate_outline.py --topic-id {args.topic_id} \\")
+print(f"    --prompt-ids {args.prompt_ids} --title \"<chosen title>\"")

package/skills/adgine-geo-content/scripts/list_content.py

@@ -0,0 +1,65 @@
+#!/usr/bin/env python3
+"""List GEO content items for a project.
+
+Usage:
+  python3 scripts/list_content.py [--project-id <id>] [--status draft|outline|article]
+                                 [--publish-status unpublished|published]
+                                 [--topic-id <id>] [--page 1] [--limit 20] [--json]
+"""
+import sys
+import os
+import argparse
+
+sys.path.insert(0, os.path.dirname(__file__))
+from _client import get_api_config, get_project_id, api_get, extract_data, print_json
+
+parser = argparse.ArgumentParser(description="List GEO content items")
+parser.add_argument("--project-id", help="Project ID (or set GEO_PROJECT_ID env var)")
+parser.add_argument("--status",   choices=["draft", "outline", "article"],
+                    help="Filter by content status")
+parser.add_argument("--publish-status", choices=["unpublished", "published"],
+                    help="Filter by WordPress publish status")
+parser.add_argument("--topic-id", help="Filter by topic ID")
+parser.add_argument("--page",  type=int, default=1,  help="Page number (default: 1)")
+parser.add_argument("--limit", type=int, default=20, help="Results per page (default: 20)")
+parser.add_argument("--json", action="store_true", help="Output raw JSON")
+args = parser.parse_args()
+
+key, base = get_api_config()
+pid = get_project_id(args.project_id)
+
+params = {"page": args.page, "limit": args.limit}
+if args.status:
+    params["status"] = args.status
+if args.publish_status:
+    params["publish_status"] = args.publish_status
+if args.topic_id:
+    params["topic_id"] = args.topic_id
+
+result = api_get(f"/api/projects/{pid}/content", key, base, params=params)
+data = extract_data(result)
+items = data if isinstance(data, list) else data.get("items") or data.get("content") or []
+
+if args.json:
+    print_json(data)
+    sys.exit(0)
+
+total = data.get("total", len(items)) if isinstance(data, dict) else len(items)
+filter_desc = f"  status={args.status}" if args.status else ""
+filter_desc += f"  publish_status={args.publish_status}" if args.publish_status else ""
+print(f"Content items ({len(items)} of {total}){filter_desc}  |  project: {pid}")
+print()
+
+if not items:
+    print("  No content found. Generate an outline with: python3 scripts/generate_outline.py")
+    sys.exit(0)
+
+print(f"  {'ID':<38}  {'Status':<10}  {'Words':>5}  {'Pub.Status':<10}  Title")
+print(f"  {'-'*38}  {'-'*10}  {'-'*5}  {'-'*10}  {'-'*50}")
+for item in items:
+    cid    = item.get("id", "")[:36]
+    status = item.get("status", "draft")
+    words  = item.get("word_count", 0) or 0
+    pub_st = item.get("publish_status") or "—"
+    title  = (item.get("article_title") or "(untitled)")[:60]
+    print(f"  {cid:<38}  {status:<10}  {words:>5}  {pub_st:<10}  {title}")

package/skills/adgine-geo-content/scripts/manage_content.py

@@ -0,0 +1,90 @@
+#!/usr/bin/env python3
+"""Inspect, edit, or delete a single GEO content item.
+
+Usage:
+  python3 scripts/manage_content.py get    --content-id <id> [--project-id <id>] [--json]
+  python3 scripts/manage_content.py edit   --content-id <id> [--title "..."] [--body-file path.md]
+  python3 scripts/manage_content.py delete --content-id <id>
+
+The `get` action returns the full content detail (title, status, word count,
+body, outline, metadata) for one record. Use `list_content.py` to discover IDs.
+"""
+import sys
+import os
+import argparse
+
+sys.path.insert(0, os.path.dirname(__file__))
+from _client import (
+    get_api_config, get_project_id,
+    api_get, api_patch, api_delete,
+    extract_data, print_json,
+)
+
+parser = argparse.ArgumentParser(description="Manage a single GEO content item")
+parser.add_argument("action", choices=["get", "edit", "delete"])
+parser.add_argument("--project-id", help="Project ID (or set GEO_PROJECT_ID env var)")
+parser.add_argument("--content-id", required=True, help="Content ID")
+parser.add_argument("--title",      help="(edit) New article title")
+parser.add_argument("--body-file",  help="(edit) Path to a markdown file with the new body")
+parser.add_argument("--status",     help="(edit) New status (draft|outline|article|published)")
+parser.add_argument("--json", action="store_true", help="Output raw JSON")
+args = parser.parse_args()
+
+key, base = get_api_config()
+pid = get_project_id(args.project_id)
+
+# ── GET ───────────────────────────────────────────────────────────────────────
+if args.action == "get":
+    result = api_get(f"/api/projects/{pid}/content/{args.content_id}", key, base)
+    item = extract_data(result) or {}
+    if args.json:
+        print_json(item)
+        sys.exit(0)
+    print(f"Content {args.content_id}")
+    print()
+    print(f"  Title         : {item.get('article_title') or item.get('title') or '(untitled)'}")
+    print(f"  Status        : {item.get('status', '--')}")
+    print(f"  Publish status: {item.get('publish_status') or '—'}")
+    print(f"  Words         : {item.get('word_count', 0)}")
+    print(f"  Topic ID      : {item.get('topic_id', '--')}")
+    print(f"  Created       : {item.get('created_at', '--')}")
+    print(f"  Updated       : {item.get('updated_at', '--')}")
+    body = item.get("article_body") or item.get("body") or ""
+    if body:
+        preview = body[:600]
+        print()
+        print("  --- body preview ---")
+        for line in preview.splitlines():
+            print(f"  {line}")
+        if len(body) > 600:
+            print(f"  [... truncated, {len(body)} chars total ...]")
+    sys.exit(0)
+
+# ── EDIT ──────────────────────────────────────────────────────────────────────
+if args.action == "edit":
+    body = {}
+    if args.title:
+        body["article_title"] = args.title
+    if args.body_file:
+        with open(args.body_file, "r", encoding="utf-8") as fh:
+            body["article_body"] = fh.read()
+    if args.status:
+        body["status"] = args.status
+    if not body:
+        print("ERROR: provide at least one of --title, --body-file or --status")
+        sys.exit(1)
+    result = api_patch(f"/api/projects/{pid}/content/{args.content_id}", key, base, body)
+    updated = extract_data(result) or {}
+    if args.json:
+        print_json(updated)
+        sys.exit(0)
+    print(f"✓  Updated content {args.content_id}")
+    print(f"   Title  : {updated.get('article_title') or updated.get('title', '')}")
+    print(f"   Status : {updated.get('status', '--')}")
+    sys.exit(0)
+
+# ── DELETE ────────────────────────────────────────────────────────────────────
+if args.action == "delete":
+    api_delete(f"/api/projects/{pid}/content/{args.content_id}", key, base)
+    print(f"✓  Deleted content {args.content_id}")
+    sys.exit(0)

package/skills/adgine-geo-content/scripts/manage_jobs.py

@@ -0,0 +1,184 @@
+#!/usr/bin/env python3
+"""List, inspect and retry content generation jobs (outline + article workflows).
+
+Subcommands:
+  list-outline                          — list outline-generation jobs
+  list-article                          — list article-generation jobs
+  list-workflow                         — list combined workflow jobs (jobs)
+  get-outline   --job-id <id>           — outline-jobs/{id}
+  get-article   --job-id <id>           — article-jobs/{id}
+  get-workflow  --job-id <id>           — jobs/{id}  (overall workflow)
+  retry         --job-id <id>           — retry a failed workflow job
+
+Usage examples:
+  python3 scripts/manage_jobs.py list-outline
+  python3 scripts/manage_jobs.py get-article --job-id <id>
+  python3 scripts/manage_jobs.py retry --job-id <id>
+"""
+import sys
+import os
+import argparse
+
+sys.path.insert(0, os.path.dirname(__file__))
+from _client import (
+    get_api_config, get_project_id,
+    api_get, api_post,
+    extract_data, print_json, truncate,
+    pad,
+)
+
+
+def _norm_status(s):
+    s = (s or "").lower()
+    if s in ("completed", "complete", "success", "done"):
+        return "Completed"
+    if s in ("failed", "error"):
+        return "Failed"
+    if s in ("running", "generating", "in_progress"):
+        return "Generating"
+    if s in ("pending", "queued", "created"):
+        return "Pending"
+    return s.title() if s else "--"
+
+
+def _print_list(items, args, title):
+    if args.json:
+        print_json(items)
+        return
+    print(f"{title}  (page {args.page}, limit {args.limit})")
+    print()
+    if not items:
+        print("No jobs found.")
+        return
+    print("```")
+    print("┌──────────────────────────────────────┬──────────────┬──────────────────────┐")
+    print("│ Job ID                               │ Status       │ Created at           │")
+    print("├──────────────────────────────────────┼──────────────┼──────────────────────┤")
+    for j in items:
+        jid = truncate(j.get("id") or j.get("job_id"), 36)
+        st = _norm_status(j.get("status"))
+        created = truncate(j.get("created_at") or "--", 20)
+        print(f"│ {pad(jid, 36)} │ {pad(st, 12)} │ {pad(created, 20)} │")
+    print("└──────────────────────────────────────┴──────────────┴──────────────────────┘")
+    print("```")
+
+
+def _print_detail(data, args, title):
+    if args.json:
+        print_json(data)
+        return
+    print(f"{title}: {args.job_id}")
+    print()
+    print("```")
+    print("┌────────────────────┬──────────────────────────────────────┐")
+    print("│ Field              │ Value                                │")
+    print("├────────────────────┼──────────────────────────────────────┤")
+    for k in ("status", "current_phase", "progress", "content_id",
+              "topic_id", "created_at", "started_at", "completed_at",
+              "error_message"):
+        if k in data:
+            val = data.get(k)
+            if k == "status":
+                val = _norm_status(val)
+            print(f"│ {pad(k, 18)} │ {pad(truncate(val, 36), 36)} │")
+    print("└────────────────────┴──────────────────────────────────────┘")
+    print("```")
+
+
+def cmd_list_outline(args, key, base, pid):
+    result = api_get(f"/api/projects/{pid}/content/outline-jobs", key, base,
+                     params={"page": args.page, "limit": args.limit})
+    data = extract_data(result)
+    items = data if isinstance(data, list) else (data or {}).get("jobs") or (data or {}).get("items", [])
+    _print_list(items, args, "Outline jobs")
+
+
+def cmd_list_article(args, key, base, pid):
+    result = api_get(f"/api/projects/{pid}/content/article-jobs", key, base,
+                     params={"page": args.page, "limit": args.limit})
+    data = extract_data(result)
+    items = data if isinstance(data, list) else (data or {}).get("jobs") or (data or {}).get("items", [])
+    _print_list(items, args, "Article jobs")
+
+
+def cmd_list_workflow(args, key, base, pid):
+    result = api_get(f"/api/projects/{pid}/content/jobs", key, base,
+                     params={"page": args.page, "limit": args.limit})
+    data = extract_data(result)
+    items = data if isinstance(data, list) else (data or {}).get("jobs") or (data or {}).get("items", [])
+    _print_list(items, args, "Workflow jobs")
+
+
+def cmd_get_outline(args, key, base, pid):
+    result = api_get(f"/api/projects/{pid}/content/outline-jobs/{args.job_id}", key, base)
+    data = extract_data(result) or {}
+    _print_detail(data, args, "Outline job")
+
+
+def cmd_get_article(args, key, base, pid):
+    result = api_get(f"/api/projects/{pid}/content/article-jobs/{args.job_id}", key, base)
+    data = extract_data(result) or {}
+    _print_detail(data, args, "Article job")
+
+
+def cmd_get_workflow(args, key, base, pid):
+    result = api_get(f"/api/projects/{pid}/content/jobs/{args.job_id}", key, base)
+    data = extract_data(result) or {}
+    _print_detail(data, args, "Workflow job")
+
+
+def cmd_retry(args, key, base, pid):
+    result = api_post(f"/api/projects/{pid}/content/jobs/{args.job_id}/retry", key, base)
+    data = extract_data(result)
+    if args.json:
+        print_json(data if data is not None else {"ok": True})
+        return
+    print(f"Retried job: {args.job_id}")
+    if isinstance(data, dict) and data.get("status"):
+        print(f"  Status: {_norm_status(data.get('status'))}")
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Manage content generation jobs")
+    parser.add_argument("--project-id", help="Project ID (or set GEO_PROJECT_ID env var)")
+    parser.add_argument("--json", action="store_true", help="Output raw JSON")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    for sub_name, _path, _title in [
+        ("list-outline",  "/content/outline-jobs", "Outline jobs"),
+        ("list-article",  "/content/article-jobs", "Article jobs"),
+        ("list-workflow", "/content/jobs",         "Workflow jobs"),
+    ]:
+        p = sub.add_parser(sub_name)
+        p.add_argument("--page", type=int, default=1)
+        p.add_argument("--limit", type=int, default=20)
+
+    for sub_name, _path, _title in [
+        ("get-outline",  "/content/outline-jobs", "Outline job"),
+        ("get-article",  "/content/article-jobs", "Article job"),
+        ("get-workflow", "/content/jobs",         "Workflow job"),
+    ]:
+        p = sub.add_parser(sub_name)
+        p.add_argument("--job-id", required=True)
+
+    p_retry = sub.add_parser("retry", help="Retry a failed workflow job")
+    p_retry.add_argument("--job-id", required=True)
+
+    args = parser.parse_args()
+    key, base = get_api_config()
+    pid = get_project_id(args.project_id)
+
+    handlers = {
+        "list-outline": cmd_list_outline,
+        "list-article": cmd_list_article,
+        "list-workflow": cmd_list_workflow,
+        "get-outline": cmd_get_outline,
+        "get-article": cmd_get_article,
+        "get-workflow": cmd_get_workflow,
+        "retry": cmd_retry,
+    }
+    handlers[args.command](args, key, base, pid)
+
+
+if __name__ == "__main__":
+    main()