@polycode-projects/the-mechanical-code-talker 5.0.12 → 5.0.14

package/README.md

@@ -10,6 +10,82 @@
 > The [GitHub repo](https://github.com/polycode-public/the-mechanical-code-talker) is a
 > read-only mirror, synced hourly. Issues and merge requests go to GitLab.
 
+## 30-second quickstart
+
+Install it:
+
+```bash skip=network
+npm install @polycode-projects/the-mechanical-code-talker
+```
+
+Teach it a fact, then ask about it. This is the whole public API for a
+one-off library call:
+
+```js
+import { runTurn } from "@polycode-projects/the-mechanical-code-talker";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const memoryDir = await mkdtemp(join(tmpdir(), "tmct-quickstart-"));
+await runTurn("a dog is an animal", { memoryDir });
+const { answer } = await runTurn("what is a dog", { memoryDir });
+console.log(answer);
+await rm(memoryDir, { recursive: true, force: true });
+```
+
+Cloned the repo instead? The same engine runs as a chat over stdin:
+
+```bash skip=repo-state
+printf 'hi\n/exit\n' | node bin/tmct.mjs
+```
+
+That greets you and exits 0. It's the project's own smoke test. (This one is
+marked `skip=` so the README suite doesn't run it. It would seed `.tmct/` in
+whatever directory it runs from, and every other example here runs from a
+disposable temp dir instead of your clone.)
+
+## Architecture
+
+Four layers, top to bottom. A **surface** (CLI, HTTP, TUI, or the browser)
+takes input. A **service** (chat, plan, research, ledger, adventure) runs
+the use case. **Domain** logic decides what's true and does no I/O of its
+own. An **adapter** sits at the seam. It is the only layer that touches
+disk, reading and writing the **graph store**, the OWL-labelled `.tmct/`
+graph.
+
+![tmct architecture: surfaces call services, services call domain, adapters sit at the seam between domain and the graph store](docs/architecture.svg)
+
+<details>
+<summary>Mermaid source (GitLab and GitHub render this natively; npm does not, which is why the image above is the diagram of record)</summary>
+
+```mermaid
+flowchart TB
+  subgraph Surfaces
+    CLI
+    HTTP
+    TUI
+    Web[Web browser]
+  end
+  subgraph Services
+    chat
+    plan
+    research
+    ledger
+    adventure
+  end
+  Domain["domain — pure logic<br/>router · planner · codegraph · completions"]
+  Adapters["adapters — the seam<br/>I/O · storage · providers"]
+  Store[(".tmct/ graph store<br/>SQLite or in-memory")]
+
+  Surfaces --> Services
+  Services --> Domain
+  Domain -.->|interface| Adapters
+  Adapters --> Store
+```
+
+</details>
+
 `@polycode-projects/the-mechanical-code-talker`
 
 A pure-JS, **no-LLM**, offline, **$0** chatbot in the ELIZA/PARRY lineage.

package/corpus/conceptnet/quality-filter.mjs

@@ -34,9 +34,16 @@
 //   7. opinion object        — /r/IsA or /r/DefinedAs whose object is one of a
 //                              small, evidence-based OPINION set (adjectives /
 //                              value words that never name a class)
+//   8. denied row             — the exact (rel, start, end) triple is in a
+//                              small, hand-curated DENIED_ROWS set: a claim
+//                              read as demonstrably false in general English
+//                              while reading the committed slice, too
+//                              specific for any shape rule above to catch
+//                              ("beta IsA programming_language")
 //
-// Rules 1-5 apply to every relation (they only ever remove junk); 6-7 are the
-// definitional band the sims flagged. Stats land on stderr; JSONL on stdout.
+// Rules 1-5 and 8 apply to every relation (they only ever remove junk); 6-7
+// are the definitional band the sims flagged. Stats land on stderr; JSONL on
+// stdout.
 
 import { readFile, writeFile } from "node:fs/promises";
 import { createInterface } from "node:readline";
@@ -65,8 +72,18 @@ export const KNOWN_MISSPELLINGS = new Set([
   "vessle",
 ]);
 
+// Rows whose claim is demonstrably false in general English, found by reading
+// the committed slice. Keyed `rel start end` so a row is cut only when all
+// three match — a re-fetch that changes the object leaves the new row alone.
+export const DENIED_ROWS = new Set([
+  "/r/IsA /c/en/beta /c/en/programming_language",
+  "/r/IsA /c/en/psi /c/en/software",
+  "/r/Antonym /c/en/letter /c/en/email",
+]);
+
 /** Why this row is noise, or null to keep it. Pure function of the row shape. */
 export function cutReason(row) {
+  if (DENIED_ROWS.has(`${row.rel} ${row.start} ${row.end}`)) return "denied-row";
   const s = bareTerm(row.start);
   const e = bareTerm(row.end);
   for (const t of [s, e]) {