imhcode 1.0.0

package/skills/graphify/wiki.py

@@ -0,0 +1,259 @@
+# Wiki export - Wikipedia-style markdown articles from the knowledge graph
+# Generates an agent-crawlable wiki: index.md + one article per community + god node articles
+from __future__ import annotations
+from collections import Counter
+from pathlib import Path
+import networkx as nx
+
+from graphify.build import edge_data
+
+
+def _safe_filename(name: str) -> str:
+    """Make a label safe for use as a filename across platforms.
+
+    Substitutes characters that Windows reserves in filenames
+    (< > : " / \\ | ? *) and strips trailing dots/spaces, also reserved.
+    Falls back to 'unnamed' for empty results and caps length at 200
+    chars to stay well under common filesystem limits.
+    """
+    import re
+    s = name.replace("/", "-").replace(" ", "_").replace(":", "-")
+    s = re.sub(r'[<>:"/\\|?*]', '_', s)
+    s = s.strip('. ')
+    return s[:200] if s else 'unnamed'
+
+
+def _cross_community_links(G: nx.Graph, nodes: list[str], own_cid: int, labels: dict[int, str], node_community: dict[str, int]) -> list[tuple[str, int]]:
+    """Return (community_label, edge_count) pairs for cross-community connections, sorted descending."""
+    counts: dict[str, int] = Counter()
+    for nid in nodes:
+        for neighbor in G.neighbors(nid):
+            ncid = node_community.get(neighbor)
+            if ncid is not None and ncid != own_cid:
+                counts[labels.get(ncid, f"Community {ncid}")] += 1
+    return sorted(counts.items(), key=lambda x: -x[1])
+
+
+def _community_article(
+    G: nx.Graph,
+    cid: int,
+    nodes: list[str],
+    label: str,
+    labels: dict[int, str],
+    cohesion: float | None,
+    node_community: dict[str, int] | None = None,
+) -> str:
+    top_nodes = sorted(nodes, key=lambda n: G.degree(n), reverse=True)[:25]
+    cross = _cross_community_links(G, nodes, cid, labels, node_community or {})
+
+    # Edge confidence breakdown
+    conf_counts: Counter = Counter()
+    for nid in nodes:
+        for neighbor in G.neighbors(nid):
+            ed = edge_data(G, nid, neighbor)
+            conf_counts[ed.get("confidence", "EXTRACTED")] += 1
+    total_edges = sum(conf_counts.values()) or 1
+
+    sources = sorted({G.nodes[n].get("source_file", "") for n in nodes} - {""})
+
+    lines: list[str] = []
+    lines += [f"# {label}", ""]
+
+    meta_parts = [f"{len(nodes)} nodes"]
+    if cohesion is not None:
+        meta_parts.append(f"cohesion {cohesion:.2f}")
+    lines += [f"> {' · '.join(meta_parts)}", ""]
+
+    lines += ["## Key Concepts", ""]
+    for nid in top_nodes:
+        d = G.nodes[nid]
+        node_label = d.get("label", nid)
+        src = d.get("source_file", "")
+        degree = G.degree(nid)
+        src_str = f" — `{src}`" if src else ""
+        lines.append(f"- **{node_label}** ({degree} connections){src_str}")
+    remaining = len(nodes) - len(top_nodes)
+    if remaining > 0:
+        lines.append(f"- *... and {remaining} more nodes in this community*")
+    lines.append("")
+
+    lines += ["## Relationships", ""]
+    if cross:
+        for other_label, count in cross[:12]:
+            lines.append(f"- [[{other_label}]] ({count} shared connections)")
+    else:
+        lines.append("- No strong cross-community connections detected")
+    lines.append("")
+
+    if sources:
+        lines += ["## Source Files", ""]
+        for src in sources[:20]:
+            lines.append(f"- `{src}`")
+        lines.append("")
+
+    lines += ["## Audit Trail", ""]
+    for conf in ("EXTRACTED", "INFERRED", "AMBIGUOUS"):
+        n = conf_counts.get(conf, 0)
+        pct = round(n / total_edges * 100)
+        lines.append(f"- {conf}: {n} ({pct}%)")
+    lines.append("")
+
+    lines += ["---", "", "*Part of the graphify knowledge wiki. See [[index]] to navigate.*"]
+    return "\n".join(lines)
+
+
+def _god_node_article(G: nx.Graph, nid: str, labels: dict[int, str], node_community: dict[str, int] | None = None) -> str:
+    d = G.nodes[nid]
+    node_label = d.get("label", nid)
+    src = d.get("source_file", "")
+    cid = (node_community or {}).get(nid)
+    community_name = labels.get(cid, f"Community {cid}") if cid is not None else None
+
+    lines: list[str] = []
+    lines += [f"# {node_label}", ""]
+    lines += [f"> God node · {G.degree(nid)} connections · `{src}`", ""]
+
+    if community_name:
+        lines += [f"**Community:** [[{community_name}]]", ""]
+
+    # Group neighbors by relation type
+    by_relation: dict[str, list[str]] = {}
+    for neighbor in sorted(G.neighbors(nid), key=lambda n: G.degree(n), reverse=True):
+        nd = G.nodes[neighbor]
+        ed = edge_data(G, nid, neighbor)
+        rel = ed.get("relation", "related")
+        neighbor_label = nd.get("label", neighbor)
+        conf = ed.get("confidence", "")
+        conf_str = f" `{conf}`" if conf else ""
+        by_relation.setdefault(rel, []).append(f"[[{neighbor_label}]]{conf_str}")
+
+    lines += ["## Connections by Relation", ""]
+    for rel, targets in sorted(by_relation.items()):
+        lines.append(f"### {rel}")
+        for t in targets[:20]:
+            lines.append(f"- {t}")
+        lines.append("")
+
+    lines += ["---", "", "*Part of the graphify knowledge wiki. See [[index]] to navigate.*"]
+    return "\n".join(lines)
+
+
+def _index_md(
+    communities: dict[int, list[str]],
+    labels: dict[int, str],
+    god_nodes_data: list[dict],
+    total_nodes: int,
+    total_edges: int,
+) -> str:
+    lines: list[str] = [
+        "# Knowledge Graph Index",
+        "",
+        "> Auto-generated by graphify. Start here — read community articles for context, then drill into god nodes for detail.",
+        "",
+        f"**{total_nodes} nodes · {total_edges} edges · {len(communities)} communities**",
+        "",
+        "---",
+        "",
+        "## Communities",
+        "(sorted by size, largest first)",
+        "",
+    ]
+
+    for cid, nodes in sorted(communities.items(), key=lambda x: -len(x[1])):
+        label = labels.get(cid, f"Community {cid}")
+        lines.append(f"- [[{label}]] — {len(nodes)} nodes")
+    lines.append("")
+
+    if god_nodes_data:
+        lines += ["## God Nodes", "(most connected concepts — the load-bearing abstractions)", ""]
+        for node in god_nodes_data:
+            lines.append(f"- [[{node['label']}]] — {node['degree']} connections")
+        lines.append("")
+
+    lines += [
+        "---",
+        "",
+        "*Generated by [graphify](https://github.com/safishamsi/graphify)*",
+    ]
+    return "\n".join(lines)
+
+
+def to_wiki(
+    G: nx.Graph,
+    communities: dict[int, list[str]],
+    output_dir: str | Path,
+    community_labels: dict[int, str] | None = None,
+    cohesion: dict[int, float] | None = None,
+    god_nodes_data: list[dict] | None = None,
+) -> int:
+    """Generate a Wikipedia-style wiki from the graph.
+
+    Writes:
+      - index.md            — agent entry point, catalog of all articles
+      - <CommunityName>.md  — one article per community
+      - <GodNodeLabel>.md   — one article per god node
+
+    Returns the number of articles written (excluding index.md).
+    """
+    out = Path(output_dir)
+    out.mkdir(parents=True, exist_ok=True)
+
+    if not communities:
+        raise ValueError(
+            "communities dict is empty — refusing to clear wiki/. "
+            "Run `graphify extract .` or `graphify cluster-only .` first."
+        )
+
+    # Clear stale .md files from previous runs to prevent orphan accumulation.
+    # Community labels are LLM-generated (per skill.md Step 5) and non-deterministic
+    # across runs — the same conceptual community may be named differently each time
+    # (e.g. "AutoAgent Skills" → "AutoAgent Methodology"), leaving the previous file
+    # as an orphan. Since to_wiki() owns wiki/ entirely (always writes the full set),
+    # it can safely clear .md files at the start of each call.
+    for old_article in out.glob("*.md"):
+        old_article.unlink()
+
+    labels = community_labels or {cid: f"Community {cid}" for cid in communities}
+    cohesion = cohesion or {}
+    god_nodes_data = god_nodes_data or []
+
+    # Build node->community lookup once; node attrs never carry community (it lives in
+    # the communities dict), so _cross_community_links and _god_node_article need this.
+    node_community: dict[str, int] = {n: cid for cid, nodes in communities.items() for n in nodes}
+
+    count = 0
+    used_slugs: set[str] = set()
+
+    def _unique_slug(base: str) -> str:
+        slug = base
+        n = 2
+        while slug in used_slugs:
+            slug = f"{base}_{n}"
+            n += 1
+        used_slugs.add(slug)
+        return slug
+
+    # Community articles
+    for cid, nodes in communities.items():
+        label = labels.get(cid, f"Community {cid}")
+        article = _community_article(G, cid, nodes, label, labels, cohesion.get(cid), node_community)
+        slug = _unique_slug(_safe_filename(label))
+        (out / f"{slug}.md").write_text(article, encoding="utf-8")
+        count += 1
+
+    # God node articles
+    for node_data in god_nodes_data:
+        nid = node_data.get("id")
+        if nid and nid in G:
+            article = _god_node_article(G, nid, labels, node_community)
+            slug = _unique_slug(_safe_filename(node_data['label']))
+            (out / f"{slug}.md").write_text(article, encoding="utf-8")
+            count += 1
+
+    # Index
+    (out / "index.md").write_text(
+        _index_md(communities, labels, god_nodes_data, G.number_of_nodes(), G.number_of_edges()),
+        encoding="utf-8",
+    )
+
+    return count

package/skills/growth-marketing/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: growth-marketing
+description: "Growth marketing copywriting and funnel engineering skill. Covers standard copy frameworks, conversion rate optimization (CRO), landing page wireframing, and analytics tracking."
+---
+
+# /growth-marketing — Growth Funnel Engineering & Copywriting
+
+**Growth-Marketing** delivers highly persuasive, conversion-optimized copy and funnel structures designed to maximize product activation, subscription retention, and B2B growth.
+
+---
+
+## 🚀 Copywriting & Funnel Frameworks
+
+### 1. Advanced Copywriting Formulas
+- **AIDA**: Attention ➔ Interest ➔ Desire ➔ Action (ideal for hero sections).
+- **PAS**: Problem ➔ Agitation ➔ Solution (highly effective for landing page feature grids).
+- **BAB**: Before ➔ After ➔ Bridge (designed for customer success stories).
+
+### 2. Conversion Rate Optimization (CRO)
+- **Visual Contrast**: Enforce OKLCH or complementary color pairings for primary Calls to Action (CTAs).
+- **Friction Reduction**: Strip registration forms down to minimal essential fields. Implement OAuth2 social login.
+- **Urgency & Social Proof**: Design high-integrity countdown timers, live metrics, and testimonial carousels.
+
+### 3. Analytics Tracking Setup
+- Wire up Segment, Mixpanel, or Google Analytics 4 event listeners.
+- Track conversion events: sign-ups, checkouts, and funnel drop-offs.

package/skills/gsap-scrolltrigger/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: gsap-scrolltrigger
+description: gsap scrolltrigger — loaded from design-skills plugin
+source: design-skills-plugin
+---
+# Gsap Scrolltrigger
+
+> **Plugin Skill**: This skill is provided by the `design-skills` plugin. When available, read the full skill from the plugin directory. When not available, use the agent's embedded knowledge of gsap scrolltrigger patterns.

package/skills/healthcare-cdss-patterns/SKILL.md

@@ -0,0 +1,245 @@
+---
+name: healthcare-cdss-patterns
+description: Clinical Decision Support System (CDSS) development patterns. Drug interaction checking, dose validation, clinical scoring (NEWS2, qSOFA), alert severity classification, and integration into EMR workflows.
+origin: Health1 Super Speciality Hospitals — contributed by Dr. Keyur Patel
+version: "1.0.0"
+---
+
+# Healthcare CDSS Development Patterns
+
+Patterns for building Clinical Decision Support Systems that integrate into EMR workflows. CDSS modules are patient safety critical — zero tolerance for false negatives.
+
+## When to Use
+
+- Implementing drug interaction checking
+- Building dose validation engines
+- Implementing clinical scoring systems (NEWS2, qSOFA, APACHE, GCS)
+- Designing alert systems for abnormal clinical values
+- Building medication order entry with safety checks
+- Integrating lab result interpretation with clinical context
+
+## How It Works
+
+The CDSS engine is a **pure function library with zero side effects**. Input clinical data, output alerts. This makes it fully testable.
+
+Three primary modules:
+
+1. **`checkInteractions(newDrug, currentMeds, allergies)`** — Checks a new drug against current medications and known allergies. Returns severity-sorted `InteractionAlert[]`. Uses `DrugInteractionPair` data model.
+2. **`validateDose(drug, dose, route, weight, age, renalFunction)`** — Validates a prescribed dose against weight-based, age-adjusted, and renal-adjusted rules. Returns `DoseValidationResult`.
+3. **`calculateNEWS2(vitals)`** — National Early Warning Score 2 from `NEWS2Input`. Returns `NEWS2Result` with total score, risk level, and escalation guidance.
+
+```
+EMR UI
+  ↓ (user enters data)
+CDSS Engine (pure functions, no side effects)
+  ├── Drug Interaction Checker
+  ├── Dose Validator
+  ├── Clinical Scoring (NEWS2, qSOFA, etc.)
+  └── Alert Classifier
+  ↓ (returns alerts)
+EMR UI (displays alerts inline, blocks if critical)
+```
+
+### Drug Interaction Checking
+
+```typescript
+interface DrugInteractionPair {
+  drugA: string;           // generic name
+  drugB: string;           // generic name
+  severity: 'critical' | 'major' | 'minor';
+  mechanism: string;
+  clinicalEffect: string;
+  recommendation: string;
+}
+
+function checkInteractions(
+  newDrug: string,
+  currentMedications: string[],
+  allergyList: string[]
+): InteractionAlert[] {
+  if (!newDrug) return [];
+  const alerts: InteractionAlert[] = [];
+  for (const current of currentMedications) {
+    const interaction = findInteraction(newDrug, current);
+    if (interaction) {
+      alerts.push({ severity: interaction.severity, pair: [newDrug, current],
+        message: interaction.clinicalEffect, recommendation: interaction.recommendation });
+    }
+  }
+  for (const allergy of allergyList) {
+    if (isCrossReactive(newDrug, allergy)) {
+      alerts.push({ severity: 'critical', pair: [newDrug, allergy],
+        message: `Cross-reactivity with documented allergy: ${allergy}`,
+        recommendation: 'Do not prescribe without allergy consultation' });
+    }
+  }
+  return alerts.sort((a, b) => severityOrder(a.severity) - severityOrder(b.severity));
+}
+```
+
+Interaction pairs must be **bidirectional**: if Drug A interacts with Drug B, then Drug B interacts with Drug A.
+
+### Dose Validation
+
+```typescript
+interface DoseValidationResult {
+  valid: boolean;
+  message: string;
+  suggestedRange: { min: number; max: number; unit: string } | null;
+  factors: string[];
+}
+
+function validateDose(
+  drug: string,
+  dose: number,
+  route: 'oral' | 'iv' | 'im' | 'sc' | 'topical',
+  patientWeight?: number,
+  patientAge?: number,
+  renalFunction?: number
+): DoseValidationResult {
+  const rules = getDoseRules(drug, route);
+  if (!rules) return { valid: true, message: 'No validation rules available', suggestedRange: null, factors: [] };
+  const factors: string[] = [];
+
+  // SAFETY: if rules require weight but weight missing, BLOCK (not pass)
+  if (rules.weightBased) {
+    if (!patientWeight || patientWeight <= 0) {
+      return { valid: false, message: `Weight required for ${drug} (mg/kg drug)`,
+        suggestedRange: null, factors: ['weight_missing'] };
+    }
+    factors.push('weight');
+    const maxDose = rules.maxPerKg * patientWeight;
+    if (dose > maxDose) {
+      return { valid: false, message: `Dose exceeds max for ${patientWeight}kg`,
+        suggestedRange: { min: rules.minPerKg * patientWeight, max: maxDose, unit: rules.unit }, factors };
+    }
+  }
+
+  // Age-based adjustment (when rules define age brackets and age is provided)
+  if (rules.ageAdjusted && patientAge !== undefined) {
+    factors.push('age');
+    const ageMax = rules.getAgeAdjustedMax(patientAge);
+    if (dose > ageMax) {
+      return { valid: false, message: `Exceeds age-adjusted max for ${patientAge}yr`,
+        suggestedRange: { min: rules.typicalMin, max: ageMax, unit: rules.unit }, factors };
+    }
+  }
+
+  // Renal adjustment (when rules define eGFR brackets and eGFR is provided)
+  if (rules.renalAdjusted && renalFunction !== undefined) {
+    factors.push('renal');
+    const renalMax = rules.getRenalAdjustedMax(renalFunction);
+    if (dose > renalMax) {
+      return { valid: false, message: `Exceeds renal-adjusted max for eGFR ${renalFunction}`,
+        suggestedRange: { min: rules.typicalMin, max: renalMax, unit: rules.unit }, factors };
+    }
+  }
+
+  // Absolute max
+  if (dose > rules.absoluteMax) {
+    return { valid: false, message: `Exceeds absolute max ${rules.absoluteMax}${rules.unit}`,
+      suggestedRange: { min: rules.typicalMin, max: rules.absoluteMax, unit: rules.unit },
+      factors: [...factors, 'absolute_max'] };
+  }
+  return { valid: true, message: 'Within range',
+    suggestedRange: { min: rules.typicalMin, max: rules.typicalMax, unit: rules.unit }, factors };
+}
+```
+
+### Clinical Scoring: NEWS2
+
+```typescript
+interface NEWS2Input {
+  respiratoryRate: number; oxygenSaturation: number; supplementalOxygen: boolean;
+  temperature: number; systolicBP: number; heartRate: number;
+  consciousness: 'alert' | 'voice' | 'pain' | 'unresponsive';
+}
+interface NEWS2Result {
+  total: number;           // 0-20
+  risk: 'low' | 'low-medium' | 'medium' | 'high';
+  components: Record<string, number>;
+  escalation: string;
+}
+```
+
+Scoring tables must match the Royal College of Physicians specification exactly.
+
+### Alert Severity and UI Behavior
+
+| Severity | UI Behavior | Clinician Action Required |
+|----------|-------------|--------------------------|
+| Critical | Block action. Non-dismissable modal. Red. | Must document override reason to proceed |
+| Major | Warning banner inline. Orange. | Must acknowledge before proceeding |
+| Minor | Info note inline. Yellow. | Awareness only, no action required |
+
+Critical alerts must NEVER be auto-dismissed or implemented as toast notifications. Override reasons must be stored in the audit trail.
+
+### Testing CDSS (Zero Tolerance for False Negatives)
+
+```typescript
+describe('CDSS — Patient Safety', () => {
+  INTERACTION_PAIRS.forEach(({ drugA, drugB, severity }) => {
+    it(`detects ${drugA} + ${drugB} (${severity})`, () => {
+      const alerts = checkInteractions(drugA, [drugB], []);
+      expect(alerts.length).toBeGreaterThan(0);
+      expect(alerts[0].severity).toBe(severity);
+    });
+    it(`detects ${drugB} + ${drugA} (reverse)`, () => {
+      const alerts = checkInteractions(drugB, [drugA], []);
+      expect(alerts.length).toBeGreaterThan(0);
+    });
+  });
+  it('blocks mg/kg drug when weight is missing', () => {
+    const result = validateDose('gentamicin', 300, 'iv');
+    expect(result.valid).toBe(false);
+    expect(result.factors).toContain('weight_missing');
+  });
+  it('handles malformed drug data gracefully', () => {
+    expect(() => checkInteractions('', [], [])).not.toThrow();
+  });
+});
+```
+
+Pass criteria: 100%. A single missed interaction is a patient safety event.
+
+### Anti-Patterns
+
+- Making CDSS checks optional or skippable without documented reason
+- Implementing interaction checks as toast notifications
+- Using `any` types for drug or clinical data
+- Hardcoding interaction pairs instead of using a maintainable data structure
+- Silently catching errors in CDSS engine (must surface failures loudly)
+- Skipping weight-based validation when weight is not available (must block, not pass)
+
+## Examples
+
+### Example 1: Drug Interaction Check
+
+```typescript
+const alerts = checkInteractions('warfarin', ['aspirin', 'metformin'], ['penicillin']);
+// [{ severity: 'critical', pair: ['warfarin', 'aspirin'],
+//    message: 'Increased bleeding risk', recommendation: 'Avoid combination' }]
+```
+
+### Example 2: Dose Validation
+
+```typescript
+const ok = validateDose('paracetamol', 1000, 'oral', 70, 45);
+// { valid: true, suggestedRange: { min: 500, max: 4000, unit: 'mg' } }
+
+const bad = validateDose('paracetamol', 5000, 'oral', 70, 45);
+// { valid: false, message: 'Exceeds absolute max 4000mg' }
+
+const noWeight = validateDose('gentamicin', 300, 'iv');
+// { valid: false, factors: ['weight_missing'] }
+```
+
+### Example 3: NEWS2 Scoring
+
+```typescript
+const result = calculateNEWS2({
+  respiratoryRate: 24, oxygenSaturation: 93, supplementalOxygen: true,
+  temperature: 38.5, systolicBP: 100, heartRate: 110, consciousness: 'voice'
+});
+// { total: 13, risk: 'high', escalation: 'Urgent clinical review. Consider ICU.' }
+```