weftens 0.0.1 → 0.1.0

package/src/synthesize.js

@@ -0,0 +1,111 @@
+// Synthesis — the reason Weftens exists. Given what Richy found about how an org is
+// represented and what PIO knows about how it operates, produce ONE operator-facing
+// read that joins them, not two blobs side by side. The join is the value: an org's
+// operations (events, people) and its representation (how it looks when someone
+// searches it afterward) are two ends of the same loop, and the useful insight lives
+// in the relationship between them — attention generated vs. conversion captured.
+//
+// Deterministic and explainable on purpose: every sentence traces to a signal the
+// operator can check. No LLM, no invented facts — if a signal is missing, it says so
+// rather than guessing.
+
+function band(score) {
+  if (score === null || score === undefined) return null;
+  if (score >= 75) return "strong";
+  if (score >= 55) return "okay";
+  return "weak";
+}
+
+function repLine(rep) {
+  if (!rep || rep.available === false) return null;
+  if (rep.overallScore === null) {
+    return rep.siteCheckAvailable === false
+      ? "We couldn't reach the website, so how you look online is unknown right now."
+      : "Your online representation was checked but didn't return a score.";
+  }
+  const b = band(rep.overallScore);
+  return `Your online representation scores ${rep.overallScore}/100 (${b}) — this is what a funder or partner sees when they search you.`;
+}
+
+function opsLine(ops) {
+  if (!ops || ops.available === false) return null;
+  const parts = [];
+  if (ops.events) parts.push(`${ops.events} event${ops.events === 1 ? "" : "s"}`);
+  if (ops.participants) parts.push(`${ops.participants} participant${ops.participants === 1 ? "" : "s"}`);
+  if (ops.programs) parts.push(`${ops.programs} program${ops.programs === 1 ? "" : "s"}`);
+  if (parts.length === 0) return "No program or event activity is recorded yet.";
+  return `On the operations side you're running ${parts.join(", ")}${ops.followUps ? ` with ${ops.followUps} follow-up${ops.followUps === 1 ? "" : "s"} in flight` : ", with no follow-ups tracked"}.`;
+}
+
+// The cross-domain insight: this is what neither agent can say alone.
+function joinInsight(rep, ops) {
+  const repScored = rep && rep.available !== false && typeof rep.overallScore === "number";
+  const hasActivity = ops && ops.available !== false && (ops.participants > 0 || ops.events > 0);
+  if (!repScored || !hasActivity) return null;
+
+  const weakRep = rep.overallScore < 55;
+  const thinFollowUp = ops.participants > 0 && (ops.followUps ?? 0) === 0;
+
+  if (weakRep && hasActivity) {
+    return {
+      insight: "You're drawing people in through events, but your online presence is weak — so the funders and partners who look you up afterward land on a page that undersells you. You're generating attention faster than you're capturing it.",
+      recommendation: rep.topFixes?.[0]?.title
+        ? `Fix your representation before the next event — start with: "${rep.topFixes[0].title}".`
+        : "Fix your representation before the next event so the people your events attract find a page that converts them.",
+    };
+  }
+  if (thinFollowUp) {
+    return {
+      insight: `Your representation is holding up (${rep.overallScore}/100), but ${ops.participants} participants have zero follow-ups tracked — the leak is on the operations side, not the online side.`,
+      recommendation: "Turn attendees into next steps: log follow-ups on this event's participants while it's fresh.",
+    };
+  }
+  return {
+    insight: `Representation (${rep.overallScore}/100) and operations are both moving; the two ends of the loop are aligned.`,
+    recommendation: rep.topFixes?.[0]?.title ? `Keep the edge: ${rep.topFixes[0].title}.` : "Keep both sides moving together.",
+  };
+}
+
+// A leg that failed for a nameable reason (org not found, service unreachable)
+// gets its reason into the read — a silently missing line hides exactly the fact
+// the operator needs ("PIO has no org by that name") behind "unavailable".
+function unavailableLine(label, leg) {
+  if (!leg || leg.available !== false || !leg.reason) return null;
+  return `${label} couldn't be checked: ${leg.reason}.`;
+}
+
+export function synthesize({ representation, operations }) {
+  const lines = [
+    repLine(representation),
+    opsLine(operations),
+    unavailableLine("Your online representation", representation),
+    unavailableLine("Your operations", operations),
+  ].filter(Boolean);
+  const joined = joinInsight(representation, operations);
+  // Fixture data must never read as a finding. Sample legs are flagged in the
+  // basis AND the headline — the numbers stay visible as an illustration, but
+  // nothing presents them as facts about the real organization.
+  const sample = Boolean(representation?.sample || operations?.sample);
+
+  let headline;
+  if (joined) headline = joined.insight;
+  else if (lines.length) headline = lines[0];
+  else headline = "Not enough signal from either side to say anything useful yet.";
+  if (sample) headline = `SAMPLE DATA (no live agents connected — an illustration, not a finding): ${headline}`;
+
+  const legBasis = (leg) => {
+    if (!leg || leg.available === false) return "unavailable";
+    return leg.sample ? "sample" : "included";
+  };
+
+  return {
+    headline,
+    read: lines,
+    recommendation: joined?.recommendation ?? representation?.topFixes?.[0]?.title ?? null,
+    sample,
+    basis: {
+      representation: legBasis(representation),
+      operations: legBasis(operations),
+    },
+  };
+}

package/src/weftens.js

@@ -0,0 +1,61 @@
+// Weftens — the orchestration layer. Given a request about an organization, it
+// decides which specialist(s) to consult (Richy for representation, PIO for
+// operations), gathers from them over their existing wire contracts, and — the part
+// that makes it worth existing — SYNTHESIZES their outputs into one operator answer
+// with a recommendation, rather than returning two blobs. Richy and PIO each still
+// run standalone; Weftens is the join. Deterministic and explainable: no invented
+// facts, and the raw per-agent detail is kept alongside the answer so nothing is
+// hidden.
+
+import { classifyIntent } from "./router.js";
+import { synthesize } from "./synthesize.js";
+
+export class WeftensError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "WeftensError";
+  }
+}
+
+async function callLeg(client, method, org, unconfiguredReason) {
+  if (!client) return { available: false, reason: unconfiguredReason };
+  try {
+    return await client[method](org);
+  } catch (error) {
+    return { available: false, reason: error?.message ?? "error" };
+  }
+}
+
+/**
+ * @param request { org: { name, website?, handles?, queries? }, intent?, question? }
+ * @param agents  { richy, pio } — clients (real or fixture); either may be null
+ */
+export async function orchestrate(request, agents = {}) {
+  const org = request?.org;
+  if (!org || typeof org.name !== "string" || org.name.trim() === "") {
+    throw new WeftensError("org.name is required");
+  }
+
+  const classified = classifyIntent(request.question ?? "");
+  const intent = request.intent && ["representation", "operations", "both"].includes(request.intent)
+    ? request.intent
+    : classified.intent;
+
+  const wantRep = intent === "representation" || intent === "both";
+  const wantOps = intent === "operations" || intent === "both";
+
+  const representation = wantRep
+    ? await callLeg(agents.richy, "representationCheck", org, "representation agent (Richy) not configured")
+    : undefined;
+  const operations = wantOps
+    ? await callLeg(agents.pio, "operationsSummary", org, "operations agent (PIO) not configured")
+    : undefined;
+
+  return {
+    org: org.name,
+    intent,
+    routing: request.intent ? "explicit" : classified.confident ? "classified" : "ambiguous — consulted both",
+    answer: synthesize({ representation, operations }),
+    detail: { representation, operations },
+  };
+}