Embed the engine

from monkeyllm.forest import init_forest

# Creates the A.5 skeleton (master index, dialect, .gitignore) and the
# embedded git repository with its first commit. Idempotent it is not:
# it refuses to overwrite an existing _index.md.
info = init_forest("./brain", title="Product brain")
print(info)
# {'root': '/abs/path/brain', 'title': 'Product brain', 'commit': 'a1b2c3d…'}

from monkeyllm import Vine, VineError

# The context manager is the lifecycle: __exit__ releases the writer lock
# and closes the SQLite handles. A forest left locked by a crashed process
# raises E_LOCKED on the next open, and the fix is to delete .vine.lock.
with Vine("./brain", writable=True, session="setup") as vine:
    vine.warm()          # pays SQLite's wake-up before the first real call
    print(vine.canopy_status)
    # {'state': 'no-embedder', 'active': False, 'index_model': None,
    #  'query_model': None, 'vectors': 0, 'stale': 0}

with Vine("./brain") as vine:
    vine.plant({
        "id": "decisions/_index",
        "type": "branch",
        "parent": "_index",
        "title": "Decisions",
        "summary": "Every architectural decision we committed to, dated.",
    })

    result = vine.plant({
        "id": "decisions/postgres-over-mongo",
        "type": "event",
        "parent": "decisions/_index",
        "title": "We picked Postgres over Mongo",
        "summary": "2026-03: relational won on the reporting workload; "
                   "the write path was never the bottleneck.",
        "tags": ["database", "architecture"],
        "links": [{"rel": "related-to", "target": "decisions/_index"}],
        "body": "# We picked Postgres over Mongo\n\n"
                "## Context\n\nReporting needed joins across six entities.\n\n"
                "## Decision\n\nPostgres 16, one primary, logical replicas.",
    })
    print(result)
    # {'id': 'decisions/postgres-over-mongo',
    #  'commit': '9f4c1ab…',
    #  'trail': ['_index', 'decisions/_index']}

with Vine("./brain", writable=False, session="q-142") as vine:
    hits = vine.locate("why did we choose our database", k=3)
    for hit in hits["results"]:
        print(hit["id"], hit["score"], hit["summary"])

    digest = vine.look("decisions/postgres-over-mongo")
    print(digest["outline"])      # ['Context', 'Decision']
    print(digest["stats"])        # {'body_tokens': …, 'degree': 1, 'heat': …}

    body = vine.pick("decisions/postgres-over-mongo", section="Decision")
    print(body["body"])

    # Closes the hunt: heat on the winning trail, plus the run's metrics.
    print(vine.close_session(True, ["decisions/postgres-over-mongo"]))

with Vine("./brain") as vine:
    vine.plant({
        "id": "finance/ledger",
        "type": "dataset",
        "parent": "finance/_index",
        "title": "2026 ledger",
        "summary": "Every booked invoice of 2026, one row per line item.",
        # The schema is DATA, never DDL. Vine generates the CREATE TABLEs,
        # births the SQLite payload, hashes it into the frontmatter and
        # writes a "## Query manual" section into the body.
        "schema": {
            "invoices": {
                "columns": {
                    "id": "INTEGER",
                    "issued_on": "TEXT",
                    "customer": "TEXT",
                    "amount_cents": "INTEGER",
                },
                "primary_key": ["id"],
            }
        },
        "rows": {
            "invoices": [
                [1, "2026-01-14", "Northwind", 412000],
                [2, "2026-01-27", "Initech", 89900],
            ]
        },
    })

with Vine("./brain") as vine:
    # look() on a dataset carries the manual, three sample rows, and the
    # "## Notes" a person wrote about what the columns mean.
    digest = vine.look("finance/ledger")
    print(digest["query_manual"])
    # {'tables': {'invoices': ['id', 'issued_on', 'customer', 'amount_cents']},
    #  'example_queries': [...]}

    # Read-only SQL. SELECT or WITH only, one statement, LIMIT 200 injected
    # when absent, 2000-token budget on the payload.
    rows = vine.query("finance/ledger", """
        SELECT customer, SUM(amount_cents) / 100.0 AS total
        FROM invoices GROUP BY customer ORDER BY total DESC
    """)
    print(rows)
    # {'columns': ['customer', 'total'], 'rows': [['Northwind', 4120.0], …],
    #  'row_count': 2, 'limited': False, 'elapsed_ms': 0.31}

    # Writes go through tend: one INSERT, UPDATE or DELETE, WHERE mandatory
    # on the last two. It refreshes payload_hash and commits the .md, never
    # the binary.
    print(vine.tend("finance/ledger",
                    "INSERT INTO invoices VALUES (3, '2026-02-02', 'Umbrella', 250000)"))
    # {'id': 'finance/ledger', 'rows_affected': 1,
    #  'payload_hash': '…', 'commit': '…', 'elapsed_ms': 1.9}

{
  "query": "why did we choose our database",
  "terms": ["choose", "database"],
  "results": [
    {
      "id": "decisions/postgres-over-mongo",
      "title": "We picked Postgres over Mongo",
      "type": "event",
      "trail": ["_index", "decisions/_index"],
      "summary": "2026-03: relational won on the reporting workload; …",
      "score": 0.0328,
      "found_by": ["locate", "sniff"],
      "matches": [
        {
          "section": "Decision",
          "line": 9,
          "snippet": "Postgres 16, one primary, logical replicas."
        }
      ],
      "content": [
        { "section": null, "body": "# We picked Postgres…", "body_tokens": 74 }
      ]
    }
  ],
  "truncated": false
}

"""A navigator loop: the model drives, the forest answers.

This is the shape the reference agent in examples/demo/run_demo.py uses.
The point is that the model never receives a dump: it receives a map, and
spends its own turns deciding where to go.
"""
import json

from monkeyllm import Vine, VineError

SYSTEM = """You navigate a knowledge forest. Reply with ONE JSON object:
- {"tool": "locate", "args": {"query": "...", "k": 5}}   entry points
- {"tool": "sniff",  "args": {"terms": ["..."]}}          literal grep on bodies
- {"tool": "look",   "args": {"id": "..."}}               cheap digest of a node
- {"tool": "move",   "args": {"id": "...", "rel": null}}  neighbours
- {"tool": "pick",   "args": {"id": "...", "section": null}}  the body
- {"tool": "query",  "args": {"id": "...", "sql": "SELECT ..."}}  datasets
- {"tool": "answer", "args": {"text": "...", "answer_nodes": ["id"]}}

Rules: "truncated": true means the list was cut by budget, so ask
narrower rather than concluding something is absent. Aggregates over a
dataset exist only through query. Cite the ids you actually opened."""


def navigate(vine: Vine, question: str, llm, max_steps: int = 14) -> dict:
    messages = [
        {"role": "system", "content": SYSTEM},
        {"role": "user", "content": json.dumps(vine.look("_index"))},
        {"role": "user", "content": question},
    ]
    for _ in range(max_steps):
        step = json.loads(llm(messages))
        tool, args = step["tool"], step.get("args", {})

        if tool == "answer":
            # Reinforces the trail that worked, so the next hunt for a
            # neighbouring question starts warmer.
            vine.close_session(True, args.get("answer_nodes", []))
            return step

        try:
            result = getattr(vine, tool)(**args)
        except VineError as e:
            # The engine's envelope is written for the caller: the hint
            # tells the model what to do instead. Hand it back verbatim.
            result = e.to_dict()
        except (AttributeError, TypeError) as e:
            result = {"error": {"code": "E_SCHEMA", "message": str(e)}}

        messages.append({"role": "assistant", "content": json.dumps(step)})
        messages.append({"role": "user", "content": json.dumps(result)})

    vine.close_session(False, [])
    return {"tool": "answer", "args": {"text": "out of steps", "answer_nodes": []}}

"""Agent memory that survives the process.

Session 1 plants what it learned. Session 9, tomorrow, on another machine,
against the same folder, finds it. Nothing is held in RAM between them:
the forest on disk is the state.
"""
import datetime as dt
import re

from monkeyllm import Vine

MEMORY_BRANCH = "memory/_index"


def ensure_memory(vine: Vine) -> None:
    """Idempotent: plant refuses a duplicate id, which is the check."""
    if not vine.forest.exists(MEMORY_BRANCH):
        vine.plant({
            "id": MEMORY_BRANCH, "type": "branch", "parent": "_index",
            "title": "Memory",
            "summary": "What agents learned in earlier sessions, one node each.",
        })


def remember(vine: Vine, title: str, summary: str, body: str,
             tags: list[str] | None = None) -> dict:
    """One durable fact becomes one node. The summary is not decoration:
    it is the text locate() ranks, so it is how this will be found again."""
    slug = re.sub(r"[^a-z0-9]+", "-", title.lower()).strip("-")[:63]
    return vine.plant({
        "id": f"memory/{slug}",
        "type": "note",
        "parent": MEMORY_BRANCH,
        "title": title,
        "summary": summary,
        "tags": tags or [],
        "source": "agent",
        "body": f"# {title}\n\n{body}\n\n_Learned {dt.date.today().isoformat()}._",
    })


def recall(vine: Vine, question: str, k: int = 3) -> list[dict]:
    """Search the whole forest, not only the memory branch: a fact planted
    last week and a document ingested this morning are both just nodes."""
    hits = vine.locate(question, k=k)
    return [vine.pick(hit["id"]) for hit in hits["results"]]

# --- session 1, Tuesday ---------------------------------------------
with Vine("./brain", session="tue-a") as vine:
    ensure_memory(vine)
    remember(
        vine,
        title="Northwind bills on net-45",
        summary="Northwind negotiated net-45 payment terms in March 2026, "
                "against our standard net-30.",
        body="Agreed with their AP lead during the renewal call. "
             "Applies to every invoice issued from 2026-04-01.",
        tags=["billing", "northwind"],
    )

# --- session 9, Thursday, a different process ------------------------
with Vine("./brain", writable=False, session="thu-c") as vine:
    for note in recall(vine, "what payment terms does Northwind have?"):
        print(note["id"], "->", note["body"])
    # memory/northwind-bills-on-net-45 -> # Northwind bills on net-45 …

/**
 * A Station client in ~40 lines. Every primitive is the same route shape:
 * POST /v1/forests/{forest}/{primitive} with the arguments as the JSON body.
 * There is no SDK to install and no privileged side channel: this is the
 * surface the Studio console itself calls.
 */
type VineError = {
  error: { code: string; message: string; hint?: string };
};

export class Station {
  constructor(
    private readonly origin: string,
    private readonly key: string,
    private readonly forest: string,
  ) {}

  private async call<T>(primitive: string, body: unknown): Promise<T> {
    const res = await fetch(
      `${this.origin}/v1/forests/${this.forest}/${primitive}`,
      {
        method: 'POST',
        headers: {
          authorization: `Bearer ${this.key}`,
          'content-type': 'application/json',
        },
        body: JSON.stringify(body),
      },
    );
    const json = (await res.json()) as T | VineError;
    if (!res.ok && 'error' in (json as VineError)) {
      const { code, message, hint } = (json as VineError).error;
      // The hint is written for the caller. Surfacing it is the difference
      // between "403" and "this key holds read, query is what you need".
      throw new Error(hint ? `${code}: ${message} (${hint})` : `${code}: ${message}`);
    }
    return json as T;
  }

  harvest(query: string, k = 3) {
    return this.call<{ results: unknown[] }>('harvest', { query, k });
  }

  answer(question: string, k = 3) {
    return this.call<{ answer: string; evidence: string[] }>('answer', {
      question,
      k,
    });
  }

  look(id: string) {
    return this.call<Record<string, unknown>>('look', { id });
  }

  query(id: string, sql: string) {
    return this.call<{ columns: string[]; rows: unknown[][] }>('query', {
      id,
      sql,
    });
  }
}

{
  "error": {
    "code": "E_FORBIDDEN",
    "message": "'query' requires the 'query' capability",
    "hint": "This principal holds: ['read']."
  }
}

# _meta/gardener.yaml, inside the forest
converters:
  # {input} and {output} are substituted. The command must write markdown
  # to {output} (or print it), and exit 0. A "# Title" first line becomes
  # the node title. Non-zero exit aborts that ONE file, never the batch.
  ".pdf": '"/usr/local/bin/pdf-to-md" "{input}" "{output}"'

curation:
  default_tags: ["internal"]
  directives: |
    Prefer a formal tone. Flag anything mentioning PII.

# your-plugin/pyproject.toml
[project.entry-points."monkeyllm.converters"]
pdf = "my_monkeyllm_plugin:PdfConverter"

[project.entry-points."monkeyllm.hooks"]
on_curate = "my_monkeyllm_plugin:add_compliance_tag"

# my_monkeyllm_plugin/__init__.py
from pathlib import Path


class PdfConverter:
    """The Converter protocol is one method returning a Conversion:
    kind ("markdown" or "dataset"), title, and either markdown, or
    schema + rows for a converter that discovered tabular data."""

    def convert(self, path: Path):
        from monkeyllm.gardener import Conversion

        text = my_extractor(path)
        return Conversion(kind="markdown", title=path.stem, markdown=text)


def add_compliance_tag(draft: dict) -> dict:
    """An on_curate hook: deterministic enrichment that runs after the LLM
    curator (or instead of it, when curation is off) and before plant.
    It receives the frontmatter draft and returns it."""
    draft.setdefault("tags", []).append("compliance")
    return draft

from monkeyllm import Vine
from monkeyllm.gardener import Gardener, discover_hooks

with Vine("./brain") as vine:
    gardener = Gardener(vine, hooks=discover_hooks())

    report = gardener.adopt("./case-files", dest="cases")
    for key in ("planted", "branches", "updated", "unchanged",
                "stale", "unsupported", "errors"):
        if report.get(key):
            print(key, len(report[key]))

    # Later, after the source folder moved on: a hash diff, not a re-import.
    print(gardener.sync("./case-files"))