@wanshi-kg/wanshi 0.1.0

package/dist/core/llm/prompts/templates/partials/examples/communication.md

@@ -0,0 +1,205 @@
+### Example 1: Email with cc + attachment
+
+Input:
+
+## File information
+
+Path: `mail/q4-budget.eml`
+
+## Content to analyze
+```
+From: John Park <john@acme.com>
+To: Sarah Lee <sarah@acme.com>
+Cc: Mike Ross <mike@acme.com>
+Subject: Q4 budget draft — Apollo
+Date: 2022-11-03
+
+Hi Sarah, attached is the Q4 budget draft for the Apollo project. I'll finalize the
+headcount numbers by Friday — can you review the travel section before then?
+Thanks, John
+
+[attachment: q4-budget.xlsx]
+```
+
+Output:
+
+```json
+{
+  "entities": [
+    {
+      "name": "John Park",
+      "entityType": "person",
+      "observations": [
+        "Sent the Q4 budget draft email on 2022-11-03",
+        "Committed to finalize the headcount numbers by Friday"
+      ]
+    },
+    {
+      "name": "Sarah Lee",
+      "entityType": "person",
+      "observations": ["Asked to review the travel section before Friday"]
+    },
+    {
+      "name": "Mike Ross",
+      "entityType": "person",
+      "observations": ["Cc'd on the Q4 budget draft email"]
+    },
+    {
+      "name": "Q4 budget draft — Apollo",
+      "entityType": "thread",
+      "observations": ["Email about the Apollo project budget, dated 2022-11-03"]
+    },
+    {
+      "name": "Apollo project",
+      "entityType": "project",
+      "observations": ["Initiative the Q4 budget covers"]
+    },
+    {
+      "name": "q4-budget.xlsx",
+      "entityType": "attachment",
+      "observations": ["Spreadsheet holding the Q4 budget draft"]
+    }
+  ],
+  "relations": [
+    { "from": "John Park",                "to": "Sarah Lee",                "relationType": ["sends_to"] },
+    { "from": "John Park",                "to": "Mike Ross",                "relationType": ["cc"] },
+    { "from": "Q4 budget draft — Apollo", "to": "Apollo project",           "relationType": ["references"] },
+    { "from": "q4-budget.xlsx",           "to": "Q4 budget draft — Apollo", "relationType": ["part_of"] }
+  ]
+}
+```
+
+Note: the deadline ("by Friday") and the review request are observations on the
+people, not nodes. `sends_to` is sender → recipient; `cc` is its own predicate, not
+stacked onto `sends_to`. The attachment is `part_of` the thread that carried it.
+
+---
+
+### Example 2: Reply in the thread (with prior context — extend)
+
+Input:
+
+## File information
+
+Path: `mail/q4-budget.eml`
+Chunk 2 of 3
+
+## Already extracted (do not re-emit)
+
+- **John Park** (person): Sent the Q4 budget draft email on 2022-11-03
+- **Sarah Lee** (person): Asked to review the travel section before Friday
+
+## Content to analyze
+```
+From: Sarah Lee <sarah@acme.com>
+To: John Park <john@acme.com>
+Subject: Re: Q4 budget draft — Apollo
+Date: 2022-11-04
+
+Reviewed — travel looks fine. Looping in my manager, Dana, who owns the Apollo
+budget sign-off.
+```
+
+Output:
+
+```json
+{
+  "entities": [
+    {
+      "name": "Sarah Lee",
+      "entityType": "person",
+      "observations": ["Reviewed the travel section and approved it (2022-11-04)"]
+    },
+    {
+      "name": "Dana",
+      "entityType": "person",
+      "observations": ["Sarah Lee's manager; owns the Apollo budget sign-off"]
+    }
+  ],
+  "relations": [
+    { "from": "Sarah Lee", "to": "John Park", "relationType": ["replies_to"] },
+    { "from": "Sarah Lee", "to": "Dana",      "relationType": ["reports_to"] }
+  ]
+}
+```
+
+Note: the reply is `replies_to`, not another `sends_to`; `reports_to` captures the
+org hierarchy. `Sarah Lee` is re-emitted under her exact name carrying a *new*
+observation (the approval), which extends the existing node on merge.
+
+---
+
+### Example 3: Group chat (hand-off + scheduling)
+
+Input:
+
+## File information
+
+Path: `chat/apollo-standup.txt`
+
+## Content to analyze
+```
+[09:02] Mike Ross: I'll forward the vendor quote to Sarah for the budget.
+[09:03] Sarah Lee: thanks. Let's set up a sync Thursday to close the numbers.
+[09:03] John Park: works for me, I'll book the room.
+```
+
+Output:
+
+```json
+{
+  "entities": [
+    {
+      "name": "Mike Ross",
+      "entityType": "person",
+      "observations": ["Forwarded the vendor quote to Sarah for the Apollo budget"]
+    },
+    {
+      "name": "Sarah Lee",
+      "entityType": "person",
+      "observations": ["Proposed a Thursday sync to finalize the numbers"]
+    },
+    {
+      "name": "John Park",
+      "entityType": "person",
+      "observations": ["Agreed to book a room for the Thursday sync"]
+    }
+  ],
+  "relations": [
+    { "from": "Mike Ross", "to": "Sarah Lee", "relationType": ["forwards_to"] },
+    { "from": "Sarah Lee", "to": "John Park", "relationType": ["schedules_with"] },
+    { "from": "John Park", "to": "Mike Ross", "relationType": ["collaborates_with"] }
+  ]
+}
+```
+
+Note: each predicate names the one real interaction — `forwards_to` for the hand-off,
+`schedules_with` for the proposed sync, `collaborates_with` for joint work. No
+`["sends_to", "forwards_to"]` synonym stacking; the timestamps stay out of the graph.
+
+---
+
+### Example 4: Encrypted body → empty graph
+
+Input:
+
+## File information
+
+Path: `mail/secure-thread.eml`
+Chunk 2 of 2
+
+## Content to analyze
+```
+-----BEGIN PGP MESSAGE-----
+hQEMA4l3xK2vQp9rAQf/Wd7yK0c1nT8mLpQ2... (encrypted body) ...=Xy7Q
+-----END PGP MESSAGE-----
+```
+
+Output:
+
+```json
+{ "entities": [], "relations": [] }
+```
+
+Note: an encrypted or otherwise undecodable body carries no extractable facts —
+empty graph, not a node minted from the armor headers.

package/dist/core/llm/prompts/templates/partials/examples/documentation.md

@@ -0,0 +1,262 @@
+### Example 1: README install + usage
+
+Input:
+
+## File information
+
+Path: `README.md`
+
+## Content to analyze
+```
+# Wanshi
+Wanshi turns files into knowledge graphs. Requires Node.js 18+.
+
+## Install
+npm install -g wanshi
+
+## Usage
+Run `wanshi --config config.yaml`. Set `output` to choose the destination file.
+```
+
+Output:
+
+```json
+{
+  "entities": [
+    {
+      "name": "Wanshi README",
+      "entityType": "guide",
+      "observations": ["Install and usage documentation for the Wanshi CLI"]
+    },
+    {
+      "name": "Wanshi",
+      "entityType": "product",
+      "observations": ["CLI that turns files into knowledge graphs"]
+    },
+    {
+      "name": "Node.js 18+",
+      "entityType": "requirement",
+      "observations": ["Minimum runtime needed to install Wanshi"]
+    },
+    {
+      "name": "install wanshi",
+      "entityType": "procedure",
+      "observations": ["Run `npm install -g wanshi`"]
+    },
+    {
+      "name": "output",
+      "entityType": "configuration_option",
+      "observations": ["Sets the destination file for the generated graph; configured in config.yaml"]
+    }
+  ],
+  "relations": [
+    { "from": "Wanshi README",  "to": "Wanshi",       "relationType": ["documents"] },
+    { "from": "Wanshi README",  "to": "install wanshi","relationType": ["guides_through"] },
+    { "from": "install wanshi", "to": "Node.js 18+",   "relationType": ["requires"] },
+    { "from": "output",         "to": "Wanshi",        "relationType": ["configures"] }
+  ]
+}
+```
+
+Note: the named option `output` is a `configuration_option` node, but its concrete
+value lives in the observation — a raw value like `graph.jsonl` would not be its own
+node. The install command is the procedure's observation, not a separate entity.
+
+---
+
+### Example 2: API reference (method + parameters)
+
+Input:
+
+## File information
+
+Path: `docs/api.md`
+
+## Content to analyze
+```
+### `createGraph(files, options)`
+Builds a knowledge graph from the given files.
+- `files` (string[]) — paths to ingest. Required.
+- `options.format` — output format, one of json|jsonl. Defaults to json.
+Returns a `KnowledgeGraph`.
+```
+
+Output:
+
+```json
+{
+  "entities": [
+    {
+      "name": "createGraph",
+      "entityType": "api_method",
+      "observations": [
+        "Builds a knowledge graph from the given files",
+        "Returns a KnowledgeGraph"
+      ]
+    },
+    {
+      "name": "files",
+      "entityType": "parameter",
+      "observations": ["string[] of paths to ingest; required"]
+    },
+    {
+      "name": "options.format",
+      "entityType": "parameter",
+      "observations": ["Output format, one of json|jsonl; defaults to json"]
+    }
+  ],
+  "relations": [
+    { "from": "files",          "to": "createGraph", "relationType": ["part_of"] },
+    { "from": "options.format", "to": "createGraph", "relationType": ["part_of"] }
+  ]
+}
+```
+
+Note: `Required` and the default value are observations on the parameter, not nodes.
+Parameters are `part_of` their method; the return type stays an observation rather
+than becoming a dangling `KnowledgeGraph` node with no facts of its own here.
+
+---
+
+### Example 3: Tutorial with ordered steps
+
+Input:
+
+## File information
+
+Path: `docs/tutorial.md`
+
+## Content to analyze
+```
+## Your first graph
+1. Create a `config.yaml` pointing `input` at your project.
+2. Run `wanshi --config config.yaml`.
+3. Open the generated `graph.jsonl`.
+
+Example: the snippet below ingests a TypeScript repo and writes JSONL.
+```
+
+Output:
+
+```json
+{
+  "entities": [
+    {
+      "name": "first graph tutorial",
+      "entityType": "guide",
+      "observations": ["Walks a new user through producing their first knowledge graph"]
+    },
+    {
+      "name": "create config.yaml",
+      "entityType": "tutorial_step",
+      "observations": ["Point `input` at the project to ingest"]
+    },
+    {
+      "name": "run wanshi",
+      "entityType": "tutorial_step",
+      "observations": ["Run `wanshi --config config.yaml`"]
+    },
+    {
+      "name": "open the output graph",
+      "entityType": "tutorial_step",
+      "observations": ["Inspect the generated `graph.jsonl`"]
+    },
+    {
+      "name": "TypeScript repo walkthrough",
+      "entityType": "example",
+      "observations": ["Ingests a TypeScript repo and writes JSONL"]
+    }
+  ],
+  "relations": [
+    { "from": "first graph tutorial", "to": "create config.yaml",          "relationType": ["guides_through"] },
+    { "from": "first graph tutorial", "to": "run wanshi",                  "relationType": ["guides_through"] },
+    { "from": "first graph tutorial", "to": "open the output graph",       "relationType": ["guides_through"] },
+    { "from": "first graph tutorial", "to": "TypeScript repo walkthrough", "relationType": ["demonstrates"] },
+    { "from": "create config.yaml",   "to": "run wanshi",                  "relationType": ["precedes"] },
+    { "from": "run wanshi",           "to": "open the output graph",       "relationType": ["precedes"] }
+  ]
+}
+```
+
+Note: `guides_through` links the tutorial to each step; `precedes` records step order
+without restating it as a synonym; `demonstrates` links the tutorial to the worked
+example. Direction stays consistent (guide → step, earlier step → later step).
+
+---
+
+### Example 4: Feature explanation
+
+Input:
+
+## File information
+
+Path: `docs/features.md`
+
+## Content to analyze
+```
+## Resume
+The `--resume` flag checkpoints every chunk so an interrupted run can continue
+without re-billing. It requires a writable output directory.
+```
+
+Output:
+
+```json
+{
+  "entities": [
+    {
+      "name": "Resume documentation",
+      "entityType": "guide",
+      "observations": ["Explains how the resume feature works"]
+    },
+    {
+      "name": "Resume",
+      "entityType": "feature",
+      "observations": [
+        "Checkpoints every chunk so an interrupted run can continue without re-billing",
+        "Enabled with the `--resume` flag"
+      ]
+    },
+    {
+      "name": "writable output directory",
+      "entityType": "requirement",
+      "observations": ["Needed so resume can persist checkpoints"]
+    }
+  ],
+  "relations": [
+    { "from": "Resume documentation", "to": "Resume",                    "relationType": ["explains"] },
+    { "from": "Resume",               "to": "writable output directory", "relationType": ["requires"] }
+  ]
+}
+```
+
+Note: `explains` links the doc section to the feature it describes; `requires`
+captures the precondition. The `--resume` flag is an observation on the feature, not
+a separate node.
+
+---
+
+### Example 5: Badges / scaffolding → empty graph
+
+Input:
+
+## File information
+
+Path: `README.md`
+Chunk 1 of 4
+
+## Content to analyze
+```
+![build](https://img.shields.io/badge/build-passing-green)
+![npm](https://img.shields.io/npm/v/wanshi)
+<!-- TOC generated, do not edit -->
+```
+
+Output:
+
+```json
+{ "entities": [], "relations": [] }
+```
+
+Note: status badges and generated table-of-contents markup carry no durable facts —
+empty graph, not a node scraped from a shields.io URL.

package/dist/core/llm/prompts/templates/partials/examples/financial.md

@@ -0,0 +1,157 @@
+### Example 1: Service contract
+
+Input:
+
+## File information
+
+Path: `contracts/abc-xyz-services.pdf`
+
+## Content to analyze
+```
+This contract is made between ABC Corporation ("the Company") and XYZ Inc.
+("the Contractor") on January 10, 2022. The Company agrees to pay the Contractor
+a total amount of $100,000 for the services rendered.
+```
+
+Output:
+
+```json
+{
+  "entities": [
+    {
+      "name": "ABC Corporation",
+      "entityType": "organization",
+      "observations": ["Client in the services contract", "Pays $100,000 for services rendered"]
+    },
+    {
+      "name": "XYZ Inc.",
+      "entityType": "organization",
+      "observations": ["Contractor in the services contract", "Receives $100,000 for services rendered"]
+    }
+  ],
+  "relations": [
+    { "from": "ABC Corporation", "to": "XYZ Inc.", "relationType": ["pays"] }
+  ]
+}
+```
+
+Note: `$100,000` is a value, not an entity. It lives in the observations of the
+parties it concerns. The two companies are the real nodes; the payment is the edge.
+
+---
+
+### Example 2: Invoice
+
+Input:
+
+## File information
+
+Path: `invoices/inv-1234.pdf`
+
+## Content to analyze
+```
+Invoice #1234
+Date: January 20, 2022
+Bill To: ABC Corporation
+Amount: $2,000
+```
+
+Output:
+
+```json
+{
+  "entities": [
+    {
+      "name": "Invoice #1234",
+      "entityType": "document",
+      "observations": ["Issued 2022-01-20", "Billed amount $2,000"]
+    },
+    {
+      "name": "ABC Corporation",
+      "entityType": "organization",
+      "observations": ["Billed party on Invoice #1234"]
+    }
+  ],
+  "relations": [
+    { "from": "Invoice #1234", "to": "ABC Corporation", "relationType": ["targets"] }
+  ]
+}
+```
+
+---
+
+### Example 3: Loan agreement
+
+Input:
+
+## File information
+
+Path: `loans/abc-term-loan.docx`
+
+## Content to analyze
+```
+Loan Agreement between ABC Corporation (Borrower) and XYZ Bank (Lender) with a
+loan amount of $500,000 and an interest rate of 5%.
+```
+
+Output:
+
+```json
+{
+  "entities": [
+    {
+      "name": "ABC Corporation",
+      "entityType": "organization",
+      "observations": ["Borrower under the loan agreement", "Principal $500,000 at 5% interest"]
+    },
+    {
+      "name": "XYZ Bank",
+      "entityType": "organization",
+      "observations": ["Lender under the loan agreement"]
+    }
+  ],
+  "relations": [
+    { "from": "ABC Corporation", "to": "XYZ Bank", "relationType": ["owes"] }
+  ]
+}
+```
+
+---
+
+### Example 4: Financial statement
+
+Input:
+
+## File information
+
+Path: `reports/fy2022-revenue.docx`
+
+## Content to analyze
+```
+The company's total revenue for the year 2022 is $1,000,000, comprised of
+sales ($800,000) and interest income ($200,000).
+```
+
+Output:
+
+```json
+{
+  "entities": [
+    {
+      "name": "FY2022 revenue",
+      "entityType": "metric",
+      "observations": [
+        "Total revenue of $1,000,000 for fiscal year 2022",
+        "Composed of $800,000 sales and $200,000 interest income"
+      ]
+    }
+  ],
+  "relations": []
+}
+```
+
+Note: a single reported figure with its breakdown is one `metric` entity, not four
+dollar-amount nodes wired together. Splitting `$1,000,000`, `$800,000`, and
+`$200,000` into separate entities produces meaningless value-nodes and a fan of
+edges that say nothing. When there is only one real entity, an empty `relations`
+array is correct.