manigent-server 0.1.0__py3-none-any.whl

manigent/models/model_defaults.py

@@ -0,0 +1,238 @@
+# SPDX-License-Identifier: MIT
+"""
+manigent/models/model_defaults.py
+
+A user's DEFAULT model config — what every new agent starts with.
+
+The record is deliberately CARD-SHAPED::
+
+    {
+        "model_configs": [ {name, provider, model, base_url, source, created_at}, ... ],
+        "default_model_config_name": "<name>" | None,
+        "local_settings": {"smart_max_attempts": int, "smart_cooldown_seconds": int},
+        "updated_at": "<iso>",
+    }
+
+so every operation in :mod:`manigent.models.model_config` (add, update,
+remove, set_default, reorder, set_routing_settings, list_configs) works on it
+unchanged. There is one definition of a valid config; this module only adds
+the v1 rule on top: **no API keys at the user level** (provider, model and
+base URL only — a keyed provider gets its key on the agent).
+
+Agents get a COPY at registration (:func:`seed_card_from_default`); nothing
+follows the default live. "Apply to all my agents" (:func:`apply_default_to_card`)
+re-copies it onto an existing card on request.
+
+Persisted one file per user at ``{server_dir}/model-defaults/<user_id>.json``.
+"""
+from __future__ import annotations
+
+import copy
+import re
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Optional
+
+from manigent.models import model_config as mc
+from manigent.utils.file_io import FileUtil
+
+# A record's on-disk directory, relative to the server data dir.
+MODEL_DEFAULTS_DIR = "model-defaults"
+
+# Agents in this team exist to be one specific model; "apply to all" skips them
+# unless the caller names them. Mirrors ``provider_agents.PROVIDER_TEAM``.
+DEFAULT_EXCLUDED_TEAMS: tuple[str, ...] = ("Model agents",)
+
+# The name the installer and the web UI give the router config.
+SMART_CONFIG_NAME = "Smart routing"
+
+_USER_ID_RE = re.compile(r"^[A-Za-z0-9_-]{1,128}$")
+_ROUTING_KEYS = ("smart_max_attempts", "smart_cooldown_seconds")
+
+
+# ---------------------------------------------------------------------------
+# Validation
+# ---------------------------------------------------------------------------
+
+def empty_record() -> dict:
+    return {"model_configs": [], "default_model_config_name": None, "local_settings": {}}
+
+
+def check_config(cfg: dict) -> None:
+    """Raise ValueError if one config breaks the v1 rule: no ``api_key``, and
+    no keyed provider (it could not run without one)."""
+    if cfg.get("api_key"):
+        raise ValueError("the default model config cannot store an API key")
+    if cfg.get("provider") in mc.KEYED_PROVIDERS:
+        raise ValueError(
+            f"provider '{cfg.get('provider')}' needs an API key, which the "
+            "default model config cannot store; add it on the agent instead"
+        )
+
+
+def validate_record(record: dict) -> dict:
+    """Raise ValueError if any config in ``record`` breaks the v1 rule.
+    Returns ``record`` so callers can chain."""
+    for cfg in mc._get_list(record):
+        check_config(cfg)
+    return record
+
+
+def build_record(
+    configs: list[dict],
+    default: Optional[str] = None,
+    *,
+    max_attempts: Optional[int] = None,
+    cooldown_seconds: Optional[int] = None,
+) -> dict:
+    """A validated record from wire-shape configs (the PUT body / installer).
+
+    Goes through ``model_config.add_config`` so names, providers and
+    duplicates are checked by the same code agents use."""
+    record = empty_record()
+    for cfg in configs:
+        check_config(cfg)
+        mc.add_config(record, cfg, source="default")
+    if default:
+        mc.set_default(record, default)
+    mc.set_routing_settings(
+        record, max_attempts=max_attempts, cooldown_seconds=cooldown_seconds,
+    )
+    return validate_record(record)
+
+
+def is_configured(record: Optional[dict]) -> bool:
+    return bool(record and mc._get_list(record))
+
+
+# ---------------------------------------------------------------------------
+# Persistence
+# ---------------------------------------------------------------------------
+
+def _path(base_dir: Path, user_id: str) -> Path:
+    if not _USER_ID_RE.match(user_id or ""):
+        raise ValueError(f"invalid user id {user_id!r}")
+    return Path(base_dir) / MODEL_DEFAULTS_DIR / f"{user_id}.json"
+
+
+def load(base_dir: Path, user_id: str) -> Optional[dict]:
+    """The user's record, or None when they never set one."""
+    data = FileUtil.read(_path(base_dir, user_id), "json")
+    return data if isinstance(data, dict) else None
+
+
+def save(base_dir: Path, user_id: str, record: dict) -> dict:
+    validate_record(record)
+    record["updated_at"] = datetime.now(UTC).isoformat()
+    FileUtil.write(_path(base_dir, user_id), record, "json")
+    return record
+
+
+def delete(base_dir: Path, user_id: str) -> bool:
+    path = _path(base_dir, user_id)
+    if not path.exists():
+        return False
+    FileUtil.delete(path)
+    return True
+
+
+# ---------------------------------------------------------------------------
+# Copying onto agents
+# ---------------------------------------------------------------------------
+
+def _copied_configs(record: dict) -> list[dict]:
+    out = []
+    for cfg in mc._get_list(record):
+        entry = copy.deepcopy(cfg)
+        entry.pop("api_key", None)
+        entry["source"] = "default"
+        out.append(entry)
+    return out
+
+
+def _copy_routing(card: dict, record: dict) -> None:
+    src = record.get("local_settings") or {}
+    ls = dict(card.get("local_settings") or {})
+    for key in _ROUTING_KEYS:
+        if src.get(key) is not None:
+            ls[key] = src[key]
+        else:
+            ls.pop(key, None)
+    card["local_settings"] = ls
+
+
+def seed_card_from_default(card: dict, record: dict) -> dict:
+    """Copy the record onto a FRESH card (registration only): its configs in
+    order, its default and its routing knobs, then re-mirror the runner-facing
+    ``local_settings.llm_*`` / ``smart_routes``."""
+    card["model_configs"] = _copied_configs(record)
+    card["default_model_config_name"] = record.get("default_model_config_name")
+    _copy_routing(card, record)
+    mc.apply_mirror(card)
+    return card
+
+
+def _is_keyed(cfg: dict) -> bool:
+    return bool(cfg.get("api_key")) or cfg.get("provider") in mc.KEYED_PROVIDERS
+
+
+def _signature(card: dict) -> tuple:
+    ls = card.get("local_settings") or {}
+    return (
+        tuple(
+            (c.get("name"), c.get("provider"), c.get("model") or None,
+             c.get("base_url") or None, bool(c.get("api_key")))
+            for c in mc._get_list(card)
+        ),
+        card.get("default_model_config_name"),
+        tuple(ls.get(k) for k in _ROUTING_KEYS),
+    )
+
+
+def apply_default_to_card(card: dict, record: dict) -> dict:
+    """Re-copy the record onto an existing card ("apply to all my agents").
+
+    The card's keyless configs are replaced by the record's. Its KEYED
+    configs (a pasted API key) are kept, placed after the record's, so a key
+    the user pasted is never deleted — it becomes the last smart-routing
+    fallback. A kept config whose name collides with one of the record's is
+    renamed (``name-2``). Mutates ``card``; returns
+    ``{"changed": bool, "removed": [...], "kept": [...]}`` so the caller can
+    say exactly what moved.
+    """
+    before = _signature(card)
+    old = mc._get_list(card)
+    kept = [dict(c) for c in old if _is_keyed(c)]
+    removed = [c.get("name") for c in old if not _is_keyed(c)]
+
+    card["model_configs"] = _copied_configs(record)
+    for cfg in kept:
+        cfg["name"] = mc._unique_name(card, cfg.get("name") or cfg.get("provider"))
+        card["model_configs"].append(cfg)
+    card["default_model_config_name"] = record.get("default_model_config_name")
+    _copy_routing(card, record)
+    mc.apply_mirror(card)
+
+    new_names = {(c.get("name") or "").lower() for c in mc._get_list(card)}
+    return {
+        "changed": _signature(card) != before,
+        "removed": [n for n in removed if (n or "").lower() not in new_names],
+        "kept": [c["name"] for c in kept],
+    }
+
+
+# ---------------------------------------------------------------------------
+# Installer
+# ---------------------------------------------------------------------------
+
+def build_installer_default(providers: list[str], *, smart: bool) -> dict:
+    """The record the installer writes: one config per provider, named after
+    it, in the given (priority) order. With ``smart`` and two or more
+    providers, a router config is added in front and made the default; with
+    one provider, that provider is the default."""
+    configs: list[dict] = []
+    if smart and len(providers) >= 2:
+        configs.append({"name": SMART_CONFIG_NAME, "provider": "smart"})
+    configs.extend({"name": p, "provider": p} for p in providers)
+    default = configs[0]["name"] if configs else None
+    return build_record(configs, default)

manigent/models/onboarding_plan.py

@@ -0,0 +1,161 @@
+# SPDX-License-Identifier: MIT
+"""
+manigent/models/onboarding_plan.py
+
+The PLAN.md v1 that the "Get to know me & staff my priorities" starter to-do
+creates its project with (``manigent project create --plan-file``). The
+assistant fills in the three ``<…>`` roster lines under Goal and passes the
+rest through word for word, so the project opens with its plan already written
+and the owner's one click — dismissing the start gate — starts it.
+
+Kept apart from ``models/desk_todo.py`` because it is a project document, not
+a to-do: the plan skill's rules govern it. Goal, Not Authorized and Acceptance
+Criteria are the spec layer and lock once the owner accepts; ``## Milestones``
+carries ``<!-- layer: detail -->`` so the coordinator can tick and re-cut them
+freely. Every criterion is claimed by a milestone's ``advances:`` marker, which
+is what keeps the coverage check satisfied when the milestones move.
+
+Two orderings in here are product decisions, pinned in
+tests/test_desk_todo_seed.py:
+
+* Next tasks are proposed with all the confirmed priorities in view at once —
+  1 to 3 of them in total, not 1 to 3 per priority.
+* A new agent deep-researches its field BEFORE the assistant mentors it.
+  Research turns a fresh model into an industry veteran; the brain dump then
+  turns that veteran into one who knows this owner's institution, and the agent
+  can only recognise where the house departs from the field once it knows the
+  field.
+"""
+from __future__ import annotations
+
+# Marker lines around the template inside the to-do prompt, so tests (and
+# anyone editing it) can address the plan without parsing prose.
+PLAN_TEMPLATE_START = "--- ONBOARDING PLAN TEMPLATE ---"
+PLAN_TEMPLATE_END = "--- END TEMPLATE ---"
+
+ONBOARDING_PLAN_TEMPLATE = """\
+# Get to know me & staff my priorities
+
+## Goal
+
+My assistant knows me well enough to write my USER.md, my top priorities are
+ranked, my next tasks are on my plate, and every task is addressed to the agent
+(or the assistant-coordinated team) that will do it, ready for me to fire.
+Nothing is started on my behalf.
+
+Model agents on my roster: <names, or "none">
+Existing agents: <name - one-line job, one per line>
+Max new agents: 3
+
+## Not Authorized
+
+- Firing any to-do. I start each one myself.
+- Writing USER.md before I confirm it.
+- Registering an agent I have not approved, or more than the max above.
+
+## Acceptance Criteria
+
+### G1: My assistant knows me
+
+- [ ] **AC-1.1** — My USER.md covers my role, company, industry, how I like to
+      work and my top priorities, ranked, and I confirmed it.
+
+### G2: My next tasks are on my plate
+
+- [ ] **AC-2.1** — Every next task I confirmed is an open to-do on my plate,
+      none duplicated.
+
+### G3: Every task has someone to do it
+
+- [ ] **AC-3.1** — Every new agent I approved is registered, mentored by my
+      assistant, and can say what it knows about its field and about me, and
+      what it flagged.
+- [ ] **AC-3.2** — Every task from this project has a recipient and a first
+      assignment I could fire without editing. A task that needs several agents
+      is addressed to my assistant and says it will coordinate them in a
+      project.
+
+## Milestones <!-- layer: detail -->
+
+### M1: Brain dump from my model agents  <!-- advances: AC-1.1 -->
+
+- [ ] **M1** — every model agent, in parallel, one workroom each
+- Send each the same brief: "Brief my assistant on me as a mentor would, from
+  what your model has seen of my work on this computer: instruction files and
+  saved memories, projects and repos, conventions and stack, decisions and
+  why, what failed, recurring topics. Then give your read of (a) my top
+  priorities right now, ranked, with the evidence for each, and (b) the
+  USER.md basics: role, company, industry, how I like to work. Mark each item
+  observed or inferred. Summaries only; leave out secrets."
+- With no model agents, skip this; M2 interviews me directly.
+
+### M2: Reconcile and confirm who I am  <!-- advances: AC-1.1 -->
+
+- [ ] **M2** — assistant
+- Merge the answers into one ledger (fact, which agents said it, agreed or
+  conflicting or single-source) and commit it to your memory, noting which
+  model agent said what.
+- In user-communication, show me the draft USER.md and my ranked priorities,
+  with every conflict side by side. Ask only what is still missing and
+  important, easiest input first (a resume, a bio, a link). Never ask me for
+  due dates. If USER.md already exists, fill only the gaps.
+- Once I confirm, write USER.md with your personalize skill.
+
+### M3: Propose my next tasks  <!-- advances: AC-2.1 -->
+
+- [ ] **M3** — assistant
+- With all my confirmed priorities in mind, propose 1-3 next concrete tasks
+  and let me correct, add or cut them.
+
+### M4: Put the tasks on my plate  <!-- advances: AC-2.1 -->
+
+- [ ] **M4** — assistant
+- Run `manigent todo list --no-archived` and reuse a to-do that already
+  covers a task. Publish only when none does:
+  `manigent todo publish --text "<title>" --draft-prompt "<the task>"`.
+- List the to-do ids here.
+
+### M5: Propose, register and onboard my team  <!-- advances: AC-3.1 -->
+
+- [ ] **M5** — assistant, then each new agent
+- Propose a team table: agent, new or existing, industry domain, expertise
+  ("B2B SaaS pricing analyst", not "Researcher"), to-dos it owns. Reuse my
+  existing agents first; propose a new one only where nothing fits, and no
+  more than the max. Every new agent's mentor is my assistant.
+- Interview me on it and change the table to what I approve.
+- Register each approved agent, top priority first, with your register-agent
+  skill and a role description built from its domain and expertise. Make sure
+  it is running, then add it here:
+  `manigent project allowlist <project> --agent <name>`.
+- Onboard each new agent in its own workroom, in parallel, in this order:
+  a. Deep research. The agent researches its domain to practitioner depth:
+     the state of the art, standard tools and their trade-offs, common failure
+     modes, where the field is heading. This makes it an industry veteran.
+  b. Brain dump. My assistant mentors it with everything proprietary or
+     non-obvious it now knows that touches this agent's domain and to-dos: me
+     and my priorities, our conventions, decisions already made and why, what
+     failed, the people and systems involved. This makes it a veteran of how
+     WE work. The agent flags every place our practice departs from what its
+     research found.
+  c. Memorize. The agent reflects, commits both to memory, and posts an
+     inventory of what it knows plus every gap or conflict it flagged.
+
+### M6: Address every to-do  <!-- advances: AC-3.2 -->
+
+- [ ] **M6** — assistant
+- Update each to-do from M4 in place (skip any no longer open; never publish
+  a duplicate):
+  - One agent can do it:
+    `manigent todo update <id> --recipient <agent> --draft-prompt "<first assignment>"`
+  - It needs several agents: `--recipient` is my assistant, and the draft
+    opens "Create a project you coordinate with @a, @b ...", says what each
+    agent owns, and ends with the first deliverable.
+  - It stays with my assistant: recipient is my assistant.
+- A first assignment states the goal, current status, the very next
+  deliverable and what makes it good enough. Keep any existing draft below it.
+- Hand off each to-do as soon as its agent finishes onboarding.
+- Wrap up with a completion report: the team (name, job, what it knows, what
+  it flagged), a USER.md summary, and my to-dos in priority order (title,
+  recipient, first deliverable). Don't archive the starter to-do; it follows
+  this project.
+"""