Add Deep Company Research to the Extruct API skill

.claude-plugin/marketplace.json

@@ -6,13 +6,13 @@
   },
   "metadata": {
     "description": "Official Extruct AI skills for company lookup, discovery, Deep Search, AI tables, enrichment, and people workflows",
-    "version": "1.0.6",
+    "version": "1.0.7",
     "repository": "https://github.com/extruct-ai/skills"
   },
   "plugins": [
     {
       "name": "extruct-skills",
-      "version": "1.0.6",
+      "version": "1.0.7",
       "description": "Official Extruct AI skill bundle for company lookup, semantic search, lookalike search, Deep Search, table operations, enrichment, and contact-finding workflows.",
       "source": "./",
       "strict": true,

skills/extruct-api/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: extruct-api
-description: Run explicit Extruct API tasks through the bundled Extruct CLI. Covers Deep Search, semantic search, lookalike search, company and people tables, column operations, enrichment, and contact finding.
+description: Run explicit Extruct API tasks through the bundled Extruct CLI. Covers Deep Search, Deep Research on companies and people, semantic search, lookalike search, company and people tables, column operations, enrichment, and contact finding.
 ---
 
 # Extruct API
@@ -45,6 +45,7 @@ This section covers the default operating intent of the skill: identify the Extr
    - if the user provides an Extruct task URL or a raw task UUID, treat it as an existing Deep Search task first
    - known company lookup: fetch the canonical company profile for one domain or UUID
    - company discovery: semantic search, lookalike search, or Deep Search
+   - research report: Deep Research for a deep, cited report on one target — a company, a person, or a team
    - existing table operation: inspect, add/update rows or columns, run, poll, read
    - company-table workflow: enrich or score companies in a reusable table
    - people workflow: find people at companies or enrich existing people rows
@@ -84,6 +85,7 @@ If none of those conditions is true, stop before running Pro-only commands and t
 Pro-only actions in this skill:
 
 - Deep Search mutations: `deep-search create`, `deep-search resume`, `deep-search pause`
+- Deep Research mutations: `deep-research create`
 - Table mutations: `tables create`, `tables update`, `tables delete`, `tables clone`, `tables run`, `rows create`, `rows update`, `rows delete`, `columns add`, `columns update`, `columns delete`
 
 ## Resolve Extruct Identifiers
@@ -316,6 +318,84 @@ If Deep Search payload fields, task states, or resume behavior are unclear, veri
 
 Read `references/finding-companies.md` when the task is a fuller company-discovery workflow instead of a single search command.
 
+### Deep Research
+
+Use Deep Research when the user wants a deep, cited report on one research target — a company, a person, or a team: account planning, buyer research, researching a lead before outreach, initiative summaries, diligence. For discovering many companies, use Deep Search; for repeatable enrichment across a list, use tables.
+
+`deep-research create` is Pro-gated. Run the plan-access preflight before it.
+
+Typical asks:
+
+- "research Shell for me: buying centers, initiatives, sales angles"
+- "build an account plan brief for Stripe"
+- "research this lead and the team they work with before my call"
+- "do diligence on this company and give me a sourced report"
+
+Write the brief as a detailed paragraph, not a one-liner. Pack in everything you know
+from the conversation: what the user sells or researches, who the target buyer is, what
+decision the report supports, constraints, and time windows. The more context and
+specifics the brief carries, the better the report. If the user's ask is thin, ask one
+or two clarifying questions before creating the task.
+
+Create a task (markdown report):
+
+```bash
+<extruct_api_cli> deep-research create --payload '{"brief":"We sell a cloud cost-optimization platform to large enterprises; typical buyers are VPs of Infrastructure and FinOps leads. I am preparing outreach to Shell. Research how Shell'"'"'s IT and digital organization is structured, who owns cloud infrastructure and FinOps decisions, which cloud, data, or efficiency initiatives they announced in the last 18 months, and which vendors or system integrators they already work with. I want practical conversation angles tied to live initiatives, plus any signals of cost-cutting programs or budget pressure.","depth":"medium"}'
+```
+
+People are first-class targets — include the user's own context and the profile to research:
+
+```bash
+<extruct_api_cli> deep-research create --payload '{"brief":"Here is my company: example.com. We sell AI-powered sales-enablement software to mid-market B2B teams. Research this person and the team they work with: https://www.linkedin.com/in/example-profile. I want their role and scope, what their team owns, recent initiatives or public statements, tools they already use, and the best angle to open a conversation.","depth":"medium"}'
+```
+
+Create a task with structured output (`--payload-file` preferred for schemas):
+
+```bash
+<extruct_api_cli> deep-research create --payload-file research.json
+```
+
+`research.json`:
+
+```json
+{
+  "brief": "We provide fraud-prevention APIs for fintech platforms and are building an account plan for Stripe. Summarize Stripe's enterprise product initiatives from the last 12 months (payments, billing, risk, AI), identify concrete product or partnership angles where a fraud-prevention vendor could plug in, and flag risks that could stall a deal, such as in-house solutions, recent vendor consolidation, or compliance constraints.",
+  "depth": "high",
+  "output_schema": {
+    "type": "object",
+    "properties": {
+      "summary": {"type": "string"},
+      "recommended_angles": {"type": "array", "items": {"type": "string"}},
+      "risks": {"type": "array", "items": {"type": "string"}}
+    },
+    "required": ["summary", "recommended_angles", "risks"]
+  }
+}
+```
+
+Inspect, list, and wait for completion:
+
+```bash
+<extruct_api_cli> deep-research list --limit 20
+<extruct_api_cli> deep-research get <task_id>
+<extruct_api_cli> deep-research poll <task_id>
+```
+
+Depth and billing:
+
+- `depth` sets the research-agent budget: `medium` = 25, `high` = 50, `xhigh` = 75.
+- Creating a task requires the full budget in available credits; the user is billed only for agents that actually run (1 credit each). Failed tasks refund all charges.
+- If create returns `insufficient_credits` with `required_credits`/`available_credits`, a lower depth may still fit — offer it.
+
+Reading the result:
+
+- Tasks take minutes. `deep-research poll` blocks until `status` is `done` or `failed`; progress counters are `iterations`, `agents`, `sources`.
+- `report.kind` is `markdown` (citations like `[1]` resolve against `report.sources`) or `schema` (`fields` conforming to the output schema, `basis` mapping each field to supporting source ids, plus `sources`).
+- **Always surface `report.degradation_reasons` to the user** — plain-language notes when coverage was reduced (early finalization, failed research agents). Empty means a clean run.
+- On `failed`, read `failure_reason` and relay it: a rejected brief includes suggestions for fixing it. Failed tasks are refunded.
+
+Read `references/deep-research.md` for brief-writing, depth choice, and output-schema design guidance.
+
 ## Operate Existing Tables
 
 Use these commands when the user already has a table and wants to inspect it, change rows or columns, run new work, or read results.
@@ -610,6 +690,8 @@ Use broader role families for coverage, such as `sales leadership`, and exact ti
 
 Use this path when the user already has people rows or already has a generated child `people` table and now wants enrichment, contact data, or derived fields.
 
+For a deep one-off report on a single person or team (rather than repeatable table enrichment), use Deep Research instead — see the Deep Research section above.
+
 Typical asks:
 
 - "find work emails for these people"
@@ -780,6 +862,7 @@ Check that:
 
 - `references/column-guide.md`: column design rules plus a comprehensive library of good column configs
 - `references/finding-companies.md`: choose and operate semantic search, lookalike, and Deep Search
+- `references/deep-research.md`: write briefs, choose depth, and design output schemas for Deep Research
 - `references/researching-companies.md`: build or extend company research tables safely
 - `references/finding-people-at-companies.md`: branch from company tables into people workflows
 - `references/researching-people.md`: enrich standalone or generated people tables

skills/extruct-api/agents/openai.yaml

@@ -1,6 +1,6 @@
 interface:
   display_name: "Extruct API"
-  short_description: "Company discovery, Deep Search, AI tables, enrichment, and people workflows"
+  short_description: "Company discovery, Deep Search, Deep Research, AI tables, enrichment, and people workflows"
   icon_small: "./assets/logo.svg"
   icon_large: "./assets/logo.svg"
   brand_color: "#4D56F3"

skills/extruct-api/references/deep-research.md

@@ -0,0 +1,86 @@
+# Deep Research Playbook
+
+Deep Research turns a free-text brief about one research target — a company, a person, or a team — into a cited report.
+A reasoning agent plans the research, fans out research agents that gather evidence,
+and synthesizes the result. This playbook covers writing briefs, choosing depth,
+designing output schemas, and reading reports honestly.
+
+## When this path, when another
+
+- One target, deep sourced report (account plan, buyer research, diligence): Deep Research.
+- A person or team — research a lead before outreach or a meeting: Deep Research.
+- Many companies matching criteria: Deep Search.
+- The same questions across a list of companies, repeatably: a company table.
+- One company's profile facts, instantly: company lookup.
+
+## Write the brief like a request to an analyst
+
+Good briefs are detailed paragraphs that name the target, the requester's own context,
+and the decision the report should support. One-liners produce unfocused reports.
+
+- Good: "We sell a cloud cost-optimization platform to large enterprises; typical
+  buyers are VPs of Infrastructure and FinOps leads. I am preparing outreach to Shell.
+  Research how Shell's IT and digital organization is structured, who owns cloud
+  infrastructure and FinOps decisions, which cloud, data, or efficiency initiatives
+  they announced in the last 18 months, and which vendors or system integrators they
+  already work with. I want practical conversation angles tied to live initiatives,
+  plus any signals of cost-cutting programs or budget pressure."
+- Good: "We are a seed-stage investor evaluating Acme Robotics for a follow-on round.
+  Build a diligence brief: funding history and investors, key customers and revenue
+  signals, the competitive landscape for warehouse automation, recent leadership
+  changes, and open risks we should pressure-test in the partner meeting."
+- Good: "Here is my company: example.com. We sell AI-powered sales-enablement software to mid-market B2B teams. Research this person and the team they work with: https://www.linkedin.com/in/example-profile. I want their role and scope, what their team owns, recent initiatives or public statements, tools they already use, and the best angle to open a conversation."
+- Bad: "Help me break into Shell." (no context about what you sell or who you target)
+- Bad: "Tell me about Stripe." (no decision to support; the report will be unfocused)
+
+Include everything the research agents cannot guess: what you sell, who your buyer is,
+the angle you care about, time windows when freshness matters, what you already know.
+For people targets, include the LinkedIn profile URL (or full name plus company) and
+your own company and offer — the report is only as targeted as the brief.
+The brief can be long (up to 20,000 characters) — pasting context is encouraged, and
+more specific briefs reliably produce better reports.
+
+Vague-but-valid briefs run; truly targetless or unusable briefs are rejected
+asynchronously with suggestions in `failure_reason`, and nothing is charged.
+
+## Choose depth deliberately
+
+- `medium` (25 agents): default. Right for most account plans and single-question research.
+- `high` (50): multi-angle research on a large target, or schema mode with many fields.
+- `xhigh` (75): exhaustive coverage; use when the user explicitly wants maximum depth.
+
+Creating a task requires the full budget in available credits, but billing is per agent
+that actually runs — a focused brief at `high` often finishes well under budget. If
+create fails with `insufficient_credits`, the error includes `required_credits` and
+`available_credits`; offer a lower depth.
+
+## Design output schemas narrowly
+
+Schema mode (`output_schema`) is for machine-readable reports. Rules of thumb:
+
+- A handful of fields, each naming one decision-relevant fact or bounded list.
+- Use arrays of strings for angles, risks, initiatives; strings for summaries; numbers
+  only for genuinely numeric facts.
+- The schema must be a JSON Schema object (`"type": "object"`); it is validated in
+  full at creation time, so a malformed nested schema fails fast.
+- A `done` schema report is guaranteed to conform. Per-field `basis` (source ids) is
+  the audit trail — treat fields with an empty basis as unsupported.
+
+## Run and read
+
+```bash
+<extruct_api_cli> deep-research create --payload-file research.json
+<extruct_api_cli> deep-research poll <task_id>
+```
+
+Reading the report honestly:
+
+- Markdown reports cite sources as `[1]`-style ids resolving against `report.sources`.
+  Do not strip the citations when relaying to the user.
+- **Always check `report.degradation_reasons`** and show them with the report. They say,
+  in plain language, when research stopped early (budget or step limit) or when some
+  research agents failed. An empty list means a clean run.
+- On `failed`, relay `failure_reason`. Rejected briefs include concrete suggestions —
+  offer to retry with a fixed brief. Failed tasks refund all their charges.
+- Progress while running: `iterations` (analysis steps), `agents` (billed research
+  agents), `sources` (unique sources collected).