spikuit-cli 0.5.4__py3-none-any.whl

spikuit_cli/__init__.py

@@ -0,0 +1,3 @@
+"""Spikuit CLI — spkt command."""
+
+__version__ = "0.3.0"

spikuit_cli/commands/__init__.py

@@ -0,0 +1,17 @@
+"""Command modules for the spkt CLI."""
+
+from .community import community_app
+from .domain import domain_app
+from .neuron import neuron_app
+from .skills import skills_app
+from .source import source_app
+from .synapse import synapse_app
+
+__all__ = [
+    "community_app",
+    "domain_app",
+    "neuron_app",
+    "skills_app",
+    "source_app",
+    "synapse_app",
+]

spikuit_cli/commands/community.py

@@ -0,0 +1,99 @@
+"""Community management commands: spkt community {detect,list}."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional
+
+import typer
+
+from ..helpers import _extract_title, _get_circuit, _out, _run
+
+community_app = typer.Typer(help="Manage graph communities.")
+
+
+@community_app.command(name="detect")
+def community_detect(
+    resolution: float = typer.Option(1.0, "--resolution", "-r", help="Louvain resolution parameter"),
+    summarize: bool = typer.Option(False, "--summarize", "-s", help="Generate summary neurons for each community"),
+    as_json: bool = typer.Option(False, "--json", help="Output as JSON"),
+    brain: Optional[Path] = typer.Option(None, "--brain", "-b", help="Brain root directory"),
+) -> None:
+    """Run community detection on the knowledge graph."""
+
+    async def _detect():
+        circuit = _get_circuit(brain)
+        await circuit.connect()
+        try:
+            result = await circuit.detect_communities(resolution=resolution)
+            summaries = []
+            if summarize and result:
+                summaries = await circuit.generate_community_summaries()
+            if as_json:
+                out = {
+                    "detected": True,
+                    "count": len(result),
+                    "communities": {str(k): v for k, v in result.items()},
+                }
+                if summaries:
+                    out["summaries"] = summaries
+                _out(out, use_json=True)
+            else:
+                if not result:
+                    typer.echo("No communities detected (empty graph).")
+                    return
+                typer.echo(f"Detected {len(result)} community(ies):")
+                for cid, members in sorted(result.items()):
+                    labels = []
+                    for nid in members[:5]:
+                        n = await circuit.get_neuron(nid)
+                        labels.append(_extract_title(n.content) if n else nid)
+                    suffix = f" (+{len(members) - 5} more)" if len(members) > 5 else ""
+                    typer.echo(f"  [{cid}] {len(members)} neurons: {', '.join(labels)}{suffix}")
+                if summaries:
+                    typer.echo(f"\nGenerated {len(summaries)} community summary neuron(s).")
+        finally:
+            await circuit.close()
+
+    _run(_detect())
+
+
+@community_app.command(name="list")
+def community_list(
+    as_json: bool = typer.Option(False, "--json", help="Output as JSON"),
+    brain: Optional[Path] = typer.Option(None, "--brain", "-b", help="Brain root directory"),
+) -> None:
+    """Show current community assignments."""
+
+    async def _list():
+        circuit = _get_circuit(brain)
+        await circuit.connect()
+        try:
+            cmap = circuit.community_map()
+            if as_json:
+                groups: dict[int, list[str]] = {}
+                for nid, cid in cmap.items():
+                    groups.setdefault(cid, []).append(nid)
+                _out({
+                    "count": len(groups),
+                    "communities": {str(k): v for k, v in groups.items()},
+                }, use_json=True)
+            else:
+                if not cmap:
+                    typer.echo("No communities assigned yet. Run: spkt community detect")
+                    return
+                groups = {}
+                for nid, cid in cmap.items():
+                    groups.setdefault(cid, []).append(nid)
+                typer.echo(f"{len(groups)} community(ies):")
+                for cid, members in sorted(groups.items()):
+                    labels = []
+                    for nid in members[:5]:
+                        n = await circuit.get_neuron(nid)
+                        labels.append(_extract_title(n.content) if n else nid)
+                    suffix = f" (+{len(members) - 5} more)" if len(members) > 5 else ""
+                    typer.echo(f"  [{cid}] {len(members)} neurons: {', '.join(labels)}{suffix}")
+        finally:
+            await circuit.close()
+
+    _run(_list())

spikuit_cli/commands/domain.py

@@ -0,0 +1,151 @@
+"""Domain management commands: spkt domain {list,rename,merge}."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional
+
+import typer
+
+from ..helpers import _get_circuit, _out, _run
+
+domain_app = typer.Typer(help="Manage domains.")
+
+
+@domain_app.command(name="list")
+def domain_list(
+    as_json: bool = typer.Option(False, "--json", help="Output as JSON"),
+    brain: Optional[Path] = typer.Option(None, "--brain", "-b", help="Brain root directory"),
+) -> None:
+    """List domains with neuron counts."""
+
+    async def _list():
+        circuit = _get_circuit(brain)
+        await circuit.connect()
+        try:
+            counts = await circuit.get_domain_counts()
+            if as_json:
+                _out(counts, use_json=True)
+            else:
+                if not counts:
+                    typer.echo("No domains found.")
+                    return
+                typer.echo("Domains:")
+                for c in counts:
+                    typer.echo(f"  {c['domain']:20s}  {c['count']} neurons")
+        finally:
+            await circuit.close()
+
+    _run(_list())
+
+
+@domain_app.command(name="rename")
+def domain_rename(
+    old: str = typer.Argument(..., help="Current domain name"),
+    new: str = typer.Argument(..., help="New domain name"),
+    as_json: bool = typer.Option(False, "--json", help="Output as JSON"),
+    brain: Optional[Path] = typer.Option(None, "--brain", "-b", help="Brain root directory"),
+) -> None:
+    """Rename a domain (batch update all neurons)."""
+
+    async def _rename():
+        circuit = _get_circuit(brain)
+        await circuit.connect()
+        try:
+            count = await circuit.rename_domain(old, new)
+            if as_json:
+                _out({"old": old, "new": new, "updated": count}, use_json=True)
+            else:
+                typer.echo(f"Renamed '{old}' \u2192 '{new}' ({count} neurons updated)")
+        finally:
+            await circuit.close()
+
+    _run(_rename())
+
+
+@domain_app.command(name="merge")
+def domain_merge(
+    domains: list[str] = typer.Argument(..., help="Domains to merge"),
+    into: str = typer.Option(..., "--into", help="Target domain name"),
+    as_json: bool = typer.Option(False, "--json", help="Output as JSON"),
+    brain: Optional[Path] = typer.Option(None, "--brain", "-b", help="Brain root directory"),
+) -> None:
+    """Merge multiple domains into one target domain."""
+
+    async def _merge():
+        circuit = _get_circuit(brain)
+        await circuit.connect()
+        try:
+            count = await circuit.merge_domains(domains, into)
+            if as_json:
+                _out({"merged": domains, "into": into, "updated": count}, use_json=True)
+            else:
+                typer.echo(f"Merged {domains} \u2192 '{into}' ({count} neurons updated)")
+        finally:
+            await circuit.close()
+
+    _run(_merge())
+
+
+@domain_app.command(name="audit")
+def domain_audit(
+    as_json: bool = typer.Option(False, "--json", help="Output as JSON"),
+    brain: Optional[Path] = typer.Option(None, "--brain", "-b", help="Brain root directory"),
+) -> None:
+    """Analyze domain ↔ community alignment and suggest actions."""
+
+    async def _audit():
+        circuit = _get_circuit(brain)
+        await circuit.connect()
+        try:
+            result = await circuit.domain_audit()
+            if as_json:
+                _out(result, use_json=True)
+            else:
+                domains = result["domains"]
+                suggestions = result["suggestions"]
+                keywords = result["community_keywords"]
+
+                if not domains:
+                    typer.echo("No domains found. Run 'spkt community detect' first.")
+                    return
+
+                typer.echo("Domain ↔ Community Alignment\n")
+                for d in domains:
+                    comms = ", ".join(
+                        f"c{c['community_id']} ({c['count']})"
+                        for c in d["communities"]
+                    )
+                    typer.echo(f"  {d['domain']:20s}  {d['neuron_count']} neurons  [{comms}]")
+
+                if keywords:
+                    typer.echo("\nCommunity Keywords:")
+                    for cid, kws in sorted(keywords.items(), key=lambda x: x[0]):
+                        if kws:
+                            typer.echo(f"  c{cid}: {', '.join(kws)}")
+
+                if suggestions:
+                    typer.echo(f"\nSuggestions ({len(suggestions)}):")
+                    for s in suggestions:
+                        if s["action"] == "split":
+                            comms_str = ", ".join(
+                                f"c{c['community_id']} ({c['count']} neurons, keywords: {', '.join(c.get('keywords', []))})"
+                                for c in s["communities"]
+                            )
+                            typer.echo(f"  SPLIT '{s['domain']}': spans {len(s['communities'])} communities")
+                            typer.echo(f"         {comms_str}")
+                        elif s["action"] == "merge":
+                            doms = ", ".join(
+                                f"{d['domain']} ({d['count']})"
+                                for d in s["domains"]
+                            )
+                            typer.echo(f"  MERGE in c{s['community_id']}: {doms}")
+                            kws = s.get("keywords", [])
+                            if kws:
+                                typer.echo(f"         suggested name hint: {', '.join(kws)}")
+                else:
+                    typer.echo("\nNo alignment issues detected.")
+        finally:
+            await circuit.close()
+
+    _run(_audit())

spikuit_cli/commands/neuron.py

@@ -0,0 +1,348 @@
+"""Neuron management commands: spkt neuron {add,list,inspect,remove,merge,due,fire}."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Optional
+
+import typer
+
+from spikuit_core import Grade, Neuron, Source, Spike
+
+from ..helpers import (
+    _GRADE_MAP,
+    _extract_title,
+    _get_circuit,
+    _neuron_dict,
+    _out,
+    _run,
+)
+
+neuron_app = typer.Typer(help="Manage neurons.")
+
+
+@neuron_app.command(name="add")
+def neuron_add(
+    content: str = typer.Argument(..., help="Markdown content for the neuron"),
+    type: Optional[str] = typer.Option(None, "--type", "-t", help="Neuron type"),
+    domain: Optional[str] = typer.Option(None, "--domain", "-d", help="Domain tag"),
+    source_url: Optional[str] = typer.Option(None, "--source-url", help="Source URL for citation"),
+    source_title: Optional[str] = typer.Option(None, "--source-title", help="Source title"),
+    as_json: bool = typer.Option(False, "--json", help="Output as JSON"),
+    brain: Optional[Path] = typer.Option(None, "--brain", "-b", help="Brain root directory"),
+) -> None:
+    """Add a new Neuron to the circuit."""
+
+    async def _add():
+        circuit = _get_circuit(brain)
+        await circuit.connect()
+        try:
+            real_content = content.encode().decode("unicode_escape")
+            neuron = Neuron.create(real_content, type=type, domain=domain)
+            await circuit.add_neuron(neuron)
+
+            # Attach source if URL provided
+            source_attached = None
+            if source_url:
+                existing = await circuit.find_source_by_url(source_url)
+                if existing:
+                    await circuit.attach_source(neuron.id, existing.id)
+                    source_attached = existing
+                else:
+                    src = Source(url=source_url, title=source_title)
+                    await circuit.add_source(src)
+                    await circuit.attach_source(neuron.id, src.id)
+                    source_attached = src
+
+            if as_json:
+                d = _neuron_dict(neuron, circuit)
+                if source_attached:
+                    d["source_id"] = source_attached.id
+                    d["source_url"] = source_attached.url
+                _out(d, use_json=True)
+            else:
+                typer.echo(f"Added neuron {neuron.id}")
+                if source_attached:
+                    typer.echo(f"  source: {source_attached.id} ({source_attached.url})")
+        finally:
+            await circuit.close()
+
+    _run(_add())
+
+
+@neuron_app.command(name="list")
+def neuron_list(
+    type: Optional[str] = typer.Option(None, "--type", "-t", help="Filter by type"),
+    domain: Optional[str] = typer.Option(None, "--domain", "-d", help="Filter by domain"),
+    limit: int = typer.Option(50, "--limit", "-n", help="Max neurons to show"),
+    meta_keys: bool = typer.Option(False, "--meta-keys", help="List filterable/searchable metadata keys"),
+    meta_values: Optional[str] = typer.Option(None, "--meta-values", help="List distinct values for a metadata key"),
+    as_json: bool = typer.Option(False, "--json", help="Output as JSON"),
+    brain: Optional[Path] = typer.Option(None, "--brain", "-b", help="Brain root directory"),
+) -> None:
+    """List neurons, or query metadata keys/values."""
+
+    async def _list():
+        circuit = _get_circuit(brain)
+        await circuit.connect()
+        try:
+            # Meta-key discovery mode
+            if meta_keys:
+                keys = await circuit.get_meta_keys()
+                if as_json:
+                    _out(keys, use_json=True)
+                else:
+                    if not keys:
+                        typer.echo("No metadata keys found.")
+                        return
+                    typer.echo("Metadata keys:")
+                    for k in keys:
+                        samples = ", ".join(k["sample_values"][:3])
+                        typer.echo(f"  {k['key']}  [{k['layer']}]  ({k['count']} sources)  e.g. {samples}")
+                return
+
+            # Meta-values mode
+            if meta_values:
+                values = await circuit.get_meta_values(meta_values)
+                if as_json:
+                    _out(values, use_json=True)
+                else:
+                    if not values:
+                        typer.echo(f"No values found for key '{meta_values}'.")
+                        return
+                    typer.echo(f"Values for '{meta_values}':")
+                    for v in values:
+                        typer.echo(f"  {v['value']}  [{v['layer']}]  ({v['count']})")
+                return
+
+            # Default: list neurons
+            kwargs = {"limit": limit}
+            if type:
+                kwargs["type"] = type
+            if domain:
+                kwargs["domain"] = domain
+            neurons = await circuit.list_neurons(**kwargs)
+            if as_json:
+                _out([_neuron_dict(n, circuit) for n in neurons], use_json=True)
+            else:
+                if not neurons:
+                    typer.echo("No neurons found.")
+                    return
+                typer.echo(f"{len(neurons)} neuron(s):")
+                for n in neurons:
+                    title = _extract_title(n.content)
+                    meta = ""
+                    if n.type:
+                        meta += f"  [{n.type}]"
+                    if n.domain:
+                        meta += f"  @{n.domain}"
+                    typer.echo(f"  {n.id}  {title}{meta}")
+        finally:
+            await circuit.close()
+
+    _run(_list())
+
+
+@neuron_app.command(name="inspect")
+def neuron_inspect(
+    neuron_id: str = typer.Argument(..., help="Neuron ID to inspect"),
+    as_json: bool = typer.Option(False, "--json", help="Output as JSON"),
+    brain: Optional[Path] = typer.Option(None, "--brain", "-b", help="Brain root directory"),
+) -> None:
+    """Inspect a neuron: content, FSRS state, pressure, neighbors."""
+
+    async def _inspect():
+        circuit = _get_circuit(brain)
+        await circuit.connect()
+        try:
+            neuron = await circuit.get_neuron(neuron_id)
+            if neuron is None:
+                typer.echo(f"Neuron {neuron_id} not found", err=True)
+                raise typer.Exit(1)
+
+            sources = await circuit.get_sources_for_neuron(neuron_id)
+            community_id = circuit.get_community(neuron_id)
+
+            if as_json:
+                d = _neuron_dict(neuron, circuit)
+                d["neighbors_out"] = circuit.neighbors(neuron_id)
+                d["neighbors_in"] = circuit.predecessors(neuron_id)
+                d["community_id"] = community_id
+                d["sources"] = [
+                    {"id": s.id, "url": s.url, "title": s.title}
+                    for s in sources
+                ]
+                _out(d, use_json=True)
+            else:
+                typer.echo(f"ID:       {neuron.id}")
+                typer.echo(f"Type:     {neuron.type or '-'}")
+                typer.echo(f"Domain:   {neuron.domain or '-'}")
+                typer.echo(f"Created:  {neuron.created_at}")
+
+                card = circuit.get_card(neuron_id)
+                if card:
+                    stab = f"{card.stability:.2f}" if card.stability is not None else "-"
+                    diff = f"{card.difficulty:.2f}" if card.difficulty is not None else "-"
+                    typer.echo(f"FSRS:     stability={stab}  difficulty={diff}  state={card.state.name}  due={card.due}")
+
+                pressure = circuit.get_pressure(neuron_id)
+                typer.echo(f"Pressure: {pressure:.4f}")
+
+                if community_id is not None:
+                    typer.echo(f"Community: {community_id}")
+
+                if sources:
+                    typer.echo(f"Sources ({len(sources)}):")
+                    for s in sources:
+                        label = s.title or s.url or s.id
+                        typer.echo(f"  {s.id}  {label}")
+
+                neighbors = circuit.neighbors(neuron_id)
+                preds = circuit.predecessors(neuron_id)
+                if neighbors:
+                    typer.echo(f"Out ({len(neighbors)}): {', '.join(neighbors)}")
+                if preds:
+                    typer.echo(f"In  ({len(preds)}):  {', '.join(preds)}")
+
+                typer.echo(f"\n{neuron.content}")
+        finally:
+            await circuit.close()
+
+    _run(_inspect())
+
+
+@neuron_app.command(name="remove")
+def neuron_remove(
+    neuron_id: str = typer.Argument(..., help="Neuron ID to remove"),
+    as_json: bool = typer.Option(False, "--json", help="Output as JSON"),
+    brain: Optional[Path] = typer.Option(None, "--brain", "-b", help="Brain root directory"),
+) -> None:
+    """Remove a neuron and its synapses."""
+
+    async def _remove():
+        circuit = _get_circuit(brain)
+        await circuit.connect()
+        try:
+            neuron = await circuit.get_neuron(neuron_id)
+            if neuron is None:
+                typer.echo(f"Neuron {neuron_id} not found", err=True)
+                raise typer.Exit(1)
+            await circuit.remove_neuron(neuron_id)
+            if as_json:
+                _out({"removed": neuron_id}, use_json=True)
+            else:
+                typer.echo(f"Removed neuron {neuron_id}")
+        finally:
+            await circuit.close()
+
+    _run(_remove())
+
+
+@neuron_app.command(name="merge")
+def neuron_merge(
+    source_ids: list[str] = typer.Argument(..., help="Neuron IDs to merge (absorbed)"),
+    into: str = typer.Option(..., "--into", help="Target neuron ID (kept)"),
+    as_json: bool = typer.Option(False, "--json", help="Output as JSON"),
+    brain: Optional[Path] = typer.Option(None, "--brain", "-b", help="Brain root directory"),
+) -> None:
+    """Merge multiple neurons into one target neuron.
+
+    Source neurons are absorbed: their content is appended,
+    synapses redirected, and source attachments transferred.
+    """
+
+    async def _merge():
+        circuit = _get_circuit(brain)
+        await circuit.connect()
+        try:
+            result = await circuit.merge_neurons(source_ids, into)
+            if as_json:
+                _out(result, use_json=True)
+            else:
+                typer.echo(f"Merged {result['merged']} neuron(s) into {result['into']}")
+                typer.echo(f"  synapses redirected: {result['synapses_redirected']}")
+                typer.echo(f"  sources transferred: {result['sources_transferred']}")
+        finally:
+            await circuit.close()
+
+    _run(_merge())
+
+
+@neuron_app.command(name="due")
+def neuron_due(
+    limit: int = typer.Option(20, "--limit", "-n", help="Max neurons to show"),
+    as_json: bool = typer.Option(False, "--json", help="Output as JSON"),
+    brain: Optional[Path] = typer.Option(None, "--brain", "-b", help="Brain root directory"),
+) -> None:
+    """Show neurons due for review."""
+
+    async def _due():
+        circuit = _get_circuit(brain)
+        await circuit.connect()
+        try:
+            ids = await circuit.due_neurons(limit=limit)
+            if as_json:
+                items = []
+                for nid in ids:
+                    neuron = await circuit.get_neuron(nid)
+                    if neuron:
+                        items.append(_neuron_dict(neuron, circuit))
+                _out(items, use_json=True)
+            else:
+                if not ids:
+                    typer.echo("No neurons due for review.")
+                    return
+                typer.echo(f"{len(ids)} neuron(s) due:")
+                for nid in ids:
+                    neuron = await circuit.get_neuron(nid)
+                    pressure = circuit.get_pressure(nid)
+                    title = _extract_title(neuron.content) if neuron else nid
+                    p_indicator = f"  pressure={pressure:.2f}" if pressure > 0 else ""
+                    typer.echo(f"  {nid}  {title}{p_indicator}")
+        finally:
+            await circuit.close()
+
+    _run(_due())
+
+
+@neuron_app.command(name="fire")
+def neuron_fire(
+    neuron_id: str = typer.Argument(..., help="Neuron ID to fire"),
+    grade: str = typer.Option("fire", "--grade", "-g", help="Grade: miss|weak|fire|strong"),
+    as_json: bool = typer.Option(False, "--json", help="Output as JSON"),
+    brain: Optional[Path] = typer.Option(None, "--brain", "-b", help="Brain root directory"),
+) -> None:
+    """Fire a spike (record a review) on a Neuron."""
+    g = _GRADE_MAP.get(grade.lower())
+    if g is None:
+        typer.echo(f"Invalid grade: {grade}. Use: miss, weak, fire, strong", err=True)
+        raise typer.Exit(1)
+
+    async def _fire():
+        circuit = _get_circuit(brain)
+        await circuit.connect()
+        try:
+            neuron = await circuit.get_neuron(neuron_id)
+            if neuron is None:
+                typer.echo(f"Neuron {neuron_id} not found", err=True)
+                raise typer.Exit(1)
+            now = datetime.now(timezone.utc)
+            spike = Spike(neuron_id=neuron_id, grade=g, fired_at=now)
+            card = await circuit.fire(spike)
+            if as_json:
+                _out({
+                    "neuron_id": neuron_id,
+                    "grade": grade,
+                    "stability": card.stability,
+                    "difficulty": card.difficulty,
+                    "due": str(card.due),
+                    "state": card.state.name,
+                }, use_json=True)
+            else:
+                typer.echo(f"Fired {grade} on {neuron_id}")
+                typer.echo(f"  stability={card.stability:.2f}  difficulty={card.difficulty:.2f}  due={card.due}")
+        finally:
+            await circuit.close()
+
+    _run(_fire())