@zenalexa/unicli 0.220.0 → 0.221.0

package/src/adapters/pqai/prior-art.yaml

@@ -0,0 +1,59 @@
+# Project PQAI — semantic prior-art retrieval.
+#
+# verification_status: blocked-by-key
+#
+# PQAI publishes a permanent free tier for non-commercial use, but rate limits
+# beyond ~100 queries / day require their USD 20 / month plan. The token is a
+# single string passed as a `token=` query param (the only auth scheme PQAI
+# offers today). Set $PQAI_API_TOKEN.
+site: pqai
+name: prior-art
+description: Semantic prior-art retrieval via PQAI's embedding-based ranker
+domain: api.projectpq.ai
+type: web-api
+strategy: public
+
+args:
+  abstract:
+    type: str
+    required: true
+    description: Candidate abstract or claim text
+  limit:
+    type: int
+    default: 20
+
+pipeline:
+  - fetch:
+      url: https://api.projectpq.ai/search/102
+      params:
+        q: "${{ args.abstract }}"
+        n: "${{ args.limit }}"
+        type: patent
+        token: "${{ env.PQAI_API_TOKEN || '' }}"
+
+  - select: results
+
+  # PQAI ships per-result `score` (semantic embedding cosine, ∈ [0, 1]).
+  # Forward as relevance_score so the meta-command's RRF stage can fuse it.
+  - map:
+      publication_number: "${{ item.id }}"
+      title: "${{ item.title }}"
+      abstract: "${{ item.abstract }}"
+      publication_date: "${{ item.publication_date || '' }}"
+      filing_date: "${{ item.filing_date || '' }}"
+      kind_code: "${{ item.kind_code || '' }}"
+      relevance_score: "${{ item.score !== undefined ? item.score : '' }}"
+      source_adapter: pqai
+      source_url: "https://search.projectpq.ai/patent/${{ item.id }}"
+      retrieved_at: "${{ now }}"
+
+  - limit: ${{ args.limit }}
+
+columns: [publication_number, title, abstract]
+
+capabilities: ["http.fetch", "patent.prior-art"]
+minimum_capability: http.fetch
+trust: public
+confidentiality: public
+quarantine: false
+schema_version: v2

package/src/adapters/pqai/search.yaml

@@ -0,0 +1,60 @@
+# Project PQAI — free-text keyword search.
+#
+# verification_status: blocked-by-key
+#
+# PQAI ships a `/search/102` endpoint that accepts both natural-language and
+# Boolean queries. This adapter exposes it as the standard patent.search
+# capability; the prior-art-specific tuning lives in pqai/prior-art.yaml.
+site: pqai
+name: search
+description: Keyword + semantic patent search through PQAI's hybrid index
+domain: api.projectpq.ai
+type: web-api
+strategy: public
+lint_listing_detail: skip
+
+args:
+  query:
+    type: str
+    required: true
+    positional: true
+  limit:
+    type: int
+    default: 20
+
+pipeline:
+  - fetch:
+      url: https://api.projectpq.ai/search/102
+      params:
+        q: "${{ args.query }}"
+        n: "${{ args.limit }}"
+        type: patent
+        token: "${{ env.PQAI_API_TOKEN || '' }}"
+
+  - select: results
+
+  # PQAI returns `score` (∈ [0, 1] semantic relevance) alongside the patent
+  # record. Surface it as relevance_score so the downstream RRF stage can
+  # consult the per-engine ranking.
+  - map:
+      publication_number: "${{ item.id }}"
+      title: "${{ item.title }}"
+      abstract: "${{ item.abstract }}"
+      publication_date: "${{ item.publication_date || '' }}"
+      filing_date: "${{ item.filing_date || '' }}"
+      kind_code: "${{ item.kind_code || '' }}"
+      relevance_score: "${{ item.score !== undefined ? item.score : '' }}"
+      source_adapter: pqai
+      source_url: "https://search.projectpq.ai/patent/${{ item.id }}"
+      retrieved_at: "${{ now }}"
+
+  - limit: ${{ args.limit }}
+
+columns: [publication_number, title, publication_date]
+
+capabilities: ["http.fetch", "patent.search"]
+minimum_capability: http.fetch
+trust: public
+confidentiality: public
+quarantine: false
+schema_version: v2

package/src/adapters/reddit/comments-tree.test.ts

@@ -0,0 +1,79 @@
+import { describe, expect, it } from "vitest";
+
+import { extractRedditCommentRows } from "./comments.js";
+import { normalizeCommentRows } from "../../social/comments.js";
+
+describe("reddit comments tree extraction", () => {
+  it("preserves nested reply hierarchy from Reddit JSON listings", () => {
+    const rawRows = extractRedditCommentRows(
+      [
+        { data: { children: [] } },
+        {
+          data: {
+            children: [
+              {
+                kind: "t1",
+                data: {
+                  id: "root",
+                  name: "t1_root",
+                  parent_id: "t3_post",
+                  author: "alice",
+                  body: "root body",
+                  score: 10,
+                  created_utc: 1,
+                  replies: {
+                    data: {
+                      children: [
+                        {
+                          kind: "t1",
+                          data: {
+                            id: "child",
+                            name: "t1_child",
+                            parent_id: "t1_root",
+                            author: "bob",
+                            body: "child body",
+                            score: 3,
+                            created_utc: 2,
+                            replies: "",
+                          },
+                        },
+                      ],
+                    },
+                  },
+                },
+              },
+            ],
+          },
+        },
+      ],
+      "r/test/comments/post/title",
+    );
+
+    const rows = normalizeCommentRows(rawRows, {
+      platform: "reddit",
+      contentId: "r/test/comments/post/title",
+    });
+
+    expect(rows).toEqual([
+      expect.objectContaining({
+        comment_id: "t1_root",
+        parent_id: "",
+        depth: 0,
+        path: "0001",
+        author: "alice",
+        text: "root body",
+        likes: 10,
+        replies: 1,
+      }),
+      expect.objectContaining({
+        comment_id: "t1_child",
+        parent_id: "t1_root",
+        depth: 1,
+        path: "0001.0001",
+        author: "bob",
+        text: "child body",
+        likes: 3,
+      }),
+    ]);
+  });
+});

package/src/adapters/reddit/comments.ts

@@ -0,0 +1,159 @@
+/**
+ * @owner   Reddit comments adapter.
+ * @does    Fetches a Reddit post comment listing and emits normalized nested comment rows.
+ * @needs   Public reddit JSON listing endpoint and a normal web User-Agent.
+ * @feeds   Social comment tree analysis and Reddit read workflows.
+ * @breaks  Reddit JSON schema or public endpoint access changes can block unauthenticated reads.
+ */
+
+import { USER_AGENT } from "../../constants.js";
+import { cli, Strategy } from "../../registry.js";
+import { normalizeCommentRows } from "../../social/comments.js";
+
+interface RedditListing {
+  data?: {
+    children?: RedditThing[];
+  };
+}
+
+interface RedditThing {
+  kind?: string;
+  data?: RedditCommentData;
+}
+
+interface RedditCommentData {
+  id?: string;
+  name?: string;
+  parent_id?: string;
+  author?: string;
+  body?: string;
+  score?: number;
+  created_utc?: number;
+  replies?: "" | RedditListing;
+}
+
+function normalizePostPath(input: string): string {
+  const raw = input.trim();
+  if (!raw) throw new Error("Reddit post URL or ID is required");
+  if (/^https?:\/\//i.test(raw)) {
+    const url = new URL(raw);
+    return url.pathname.replace(/^\/+/, "").replace(/\.json$/, "");
+  }
+  return raw.replace(/^\/+/, "").replace(/\.json$/, "");
+}
+
+function collectCommentRows(
+  listing: RedditListing,
+  contentId: string,
+  parentId = "",
+): Array<Record<string, unknown>> {
+  const rows: Array<Record<string, unknown>> = [];
+  for (const thing of listing.data?.children ?? []) {
+    if (thing.kind !== "t1") continue;
+    const data = thing.data;
+    if (!data?.id) continue;
+    const commentId = data.name ?? `t1_${data.id}`;
+    rows.push({
+      id: commentId,
+      parent_id:
+        data.parent_id && data.parent_id.startsWith("t1_")
+          ? data.parent_id
+          : parentId,
+      author: data.author ?? "",
+      body: data.body ?? "",
+      text: data.body ?? "",
+      score: data.score ?? 0,
+      replies:
+        data.replies && typeof data.replies === "object"
+          ? (data.replies.data?.children?.filter((child) => child.kind === "t1")
+              .length ?? 0)
+          : 0,
+      created: data.created_utc
+        ? new Date(data.created_utc * 1000).toISOString()
+        : "",
+      content_id: contentId,
+    });
+    if (data.replies && typeof data.replies === "object") {
+      rows.push(...collectCommentRows(data.replies, contentId, commentId));
+    }
+  }
+  return rows;
+}
+
+export function extractRedditCommentRows(
+  response: unknown,
+  contentId: string,
+): Array<Record<string, unknown>> {
+  if (!Array.isArray(response) || response.length < 2) {
+    throw new Error("Unexpected Reddit comments response");
+  }
+  return collectCommentRows(response[1] as RedditListing, contentId);
+}
+
+cli({
+  site: "reddit",
+  name: "comments",
+  description: "Reddit post comments with nested reply hierarchy",
+  domain: "www.reddit.com",
+  strategy: Strategy.PUBLIC,
+  args: [
+    {
+      name: "url",
+      required: true,
+      positional: true,
+      description: "Reddit post URL, path, or comments ID",
+      "x-unicli-accepts": ["url", "id"],
+    },
+    {
+      name: "sort",
+      default: "top",
+      choices: ["best", "top", "new", "controversial", "old", "qa"],
+      description: "Comment sort order",
+    },
+    {
+      name: "limit",
+      type: "int",
+      default: 20,
+      description: "Number of top-level comments",
+    },
+  ],
+  columns: [
+    "platform",
+    "content_id",
+    "comment_id",
+    "parent_id",
+    "depth",
+    "path",
+    "author",
+    "text",
+    "likes",
+    "replies",
+    "created",
+    "body",
+    "score",
+  ],
+  socialCapabilities: ["read", "comments", "comment_replies"],
+  func: async (_page, kwargs) => {
+    const postPath = normalizePostPath(String(kwargs.url ?? ""));
+    const sort = String(kwargs.sort ?? "top");
+    const limit = Number(kwargs.limit ?? 20);
+    const response = await fetch(
+      `https://www.reddit.com/${postPath}.json?sort=${encodeURIComponent(sort)}&limit=${encodeURIComponent(String(limit))}&raw_json=1`,
+      {
+        headers: {
+          "User-Agent": USER_AGENT,
+          Accept: "application/json",
+        },
+      },
+    );
+    if (!response.ok) {
+      throw new Error(`Reddit comments request failed: ${response.status}`);
+    }
+    const json = await response.json();
+    const rows = extractRedditCommentRows(json, postPath);
+    return normalizeCommentRows(rows, {
+      platform: "reddit",
+      contentId: postPath,
+    });
+  },
+});

package/src/adapters/safebooru/detail.yaml

@@ -0,0 +1,63 @@
+site: safebooru
+name: detail
+description: Get Safebooru post detail by post id
+domain: safebooru.org
+type: web-api
+strategy: public
+
+args:
+  id:
+    type: str
+    required: true
+    positional: true
+
+pipeline:
+  - fetch:
+      url: "https://safebooru.org/index.php"
+      params:
+        page: dapi
+        s: post
+        q: index
+        json: 1
+        id: "${{ args.id }}"
+
+  - assert:
+      condition: "data.length > 0"
+      message: "No Safebooru post found for this id."
+
+  - map:
+      id: "${{ item.id }}"
+      rating: "${{ item.rating }}"
+      score: "${{ item.score }}"
+      owner: "${{ item.owner }}"
+      width: "${{ item.width }}"
+      height: "${{ item.height }}"
+      file_size: "${{ item.file_size }}"
+      tags: "${{ item.tags }}"
+      source: "${{ item.source }}"
+      preview_url: "${{ item.preview_url }}"
+      sample_url: "${{ item.sample_url }}"
+      file_url: "${{ item.file_url }}"
+      url: "${{ 'https://safebooru.org/index.php?page=post&s=view&id=' + item.id }}"
+
+columns:
+  [
+    id,
+    rating,
+    score,
+    owner,
+    width,
+    height,
+    tags,
+    source,
+    sample_url,
+    file_url,
+    url,
+  ]
+
+capabilities: ["http.fetch"]
+minimum_capability: http.fetch
+trust: public
+confidentiality: public
+quarantine: false
+schema_version: v2

package/src/adapters/safebooru/download.yaml

@@ -0,0 +1,58 @@
+site: safebooru
+name: download
+description: Download Safebooru post image by post id
+domain: safebooru.org
+type: web-api
+strategy: public
+
+args:
+  id:
+    type: str
+    required: true
+    positional: true
+  output:
+    type: str
+    default: "./downloads/safebooru"
+    description: Output directory
+    x-unicli-kind: path
+  quality:
+    type: str
+    default: sample
+    description: sample or original
+
+columns: [id, rating, tags, url, _download]
+
+pipeline:
+  - fetch:
+      url: "https://safebooru.org/index.php"
+      params:
+        page: dapi
+        s: post
+        q: index
+        json: 1
+        id: "${{ args.id }}"
+
+  - assert:
+      condition: "data.length > 0"
+      message: "No Safebooru post found for this id."
+
+  - download:
+      url: "${{ args.quality === 'original' ? item.file_url : item.sample_url }}"
+      dir: "${{ args.output }}"
+      filename: "${{ item.id }}.${{ (args.quality === 'original' ? item.file_url : item.sample_url) | ext | default('jpg') }}"
+      type: image
+      concurrency: 1
+
+  - map:
+      id: "${{ item.id }}"
+      rating: "${{ item.rating }}"
+      tags: "${{ item.tags }}"
+      url: "${{ 'https://safebooru.org/index.php?page=post&s=view&id=' + item.id }}"
+      _download: "${{ item._download }}"
+
+capabilities: ["http.fetch", "http.download"]
+minimum_capability: http.fetch
+trust: public
+confidentiality: public
+quarantine: false
+schema_version: v2

package/src/adapters/safebooru/search.yaml

@@ -0,0 +1,69 @@
+site: safebooru
+name: search
+description: Search Safebooru illustration posts by Moebooru tag query such as blue_archive rating:safe
+domain: safebooru.org
+type: web-api
+strategy: public
+
+args:
+  tags:
+    type: str
+    required: true
+    positional: true
+    description: Moebooru tag query, for example "blue_archive rating:safe"
+  limit:
+    type: int
+    default: 20
+  page:
+    type: int
+    default: 0
+
+pipeline:
+  - fetch:
+      url: "https://safebooru.org/index.php"
+      params:
+        page: dapi
+        s: post
+        q: index
+        json: 1
+        tags: "${{ args.tags }}"
+        limit: "${{ args.limit }}"
+        pid: "${{ args.page }}"
+
+  - map:
+      rank: "${{ index + 1 }}"
+      id: "${{ item.id }}"
+      rating: "${{ item.rating }}"
+      score: "${{ item.score }}"
+      owner: "${{ item.owner }}"
+      width: "${{ item.width }}"
+      height: "${{ item.height }}"
+      tags: "${{ item.tags }}"
+      source: "${{ item.source }}"
+      preview_url: "${{ item.preview_url }}"
+      sample_url: "${{ item.sample_url }}"
+      file_url: "${{ item.file_url }}"
+      url: "${{ 'https://safebooru.org/index.php?page=post&s=view&id=' + item.id }}"
+
+columns:
+  [
+    rank,
+    id,
+    rating,
+    score,
+    owner,
+    width,
+    height,
+    tags,
+    source,
+    sample_url,
+    file_url,
+    url,
+  ]
+
+capabilities: ["http.fetch"]
+minimum_capability: http.fetch
+trust: public
+confidentiality: public
+quarantine: false
+schema_version: v2

package/src/adapters/safebooru/web.test.ts

@@ -0,0 +1,60 @@
+import { describe, expect, it } from "vitest";
+import { resolveCommand } from "../../registry.js";
+import { mergeSafebooruTags, parseSafebooruTags } from "./web.js";
+
+describe("safebooru tag command", () => {
+  it("registers tags command", () => {
+    expect(
+      Object.keys(resolveCommand("safebooru", "tags")!.adapter.commands),
+    ).toEqual(expect.arrayContaining(["tags"]));
+  });
+
+  it("parses DAPI tag XML", () => {
+    expect(
+      parseSafebooruTags(
+        '<tags><tag type="3" count="108328" name="blue_archive" ambiguous="false" id="1167631"/></tags>',
+      ),
+    ).toMatchObject([
+      {
+        rank: 1,
+        id: "1167631",
+        name: "blue_archive",
+        count: "108328",
+        type: "3",
+        ambiguous: "false",
+      },
+    ]);
+  });
+
+  it("keeps exact tag rows ahead of prefix matches", () => {
+    expect(
+      mergeSafebooruTags([
+        [
+          {
+            rank: 1,
+            id: "1167631",
+            name: "blue_archive",
+            count: "108328",
+            type: "3",
+            ambiguous: "false",
+            url: "https://safebooru.org/index.php?page=post&s=list&tags=blue_archive",
+          },
+        ],
+        [
+          {
+            rank: 1,
+            id: "33300201",
+            name: "blue_archive_2025_hack",
+            count: "22",
+            type: "0",
+            ambiguous: "false",
+            url: "https://safebooru.org/index.php?page=post&s=list&tags=blue_archive_2025_hack",
+          },
+        ],
+      ]),
+    ).toMatchObject([
+      { rank: 1, name: "blue_archive" },
+      { rank: 2, name: "blue_archive_2025_hack" },
+    ]);
+  });
+});