Teachers Aid Laravel Package

Product Decisions This Supports

• Build vs. buy for the "AI catalog assistant" feature. TAC supplies the hard, unglamorous half — tool schemas, proposal recording, validation, apply semantics — so the decision shifts from "do we staff a 2-quarter agent project?" to "do we wire up a package and write prompts?" That is a materially cheaper bet to validate.
• Where the agent is allowed to act (blast radius). teachers-aid.entities and the new teachers-aid.relations are, in product terms, the permission matrix: which record types the assistant may touch and which links it may create or remove. This is a roadmap artifact, not just config — it defines the v1 scope of the feature you ship to teachers.
• Human-in-the-loop as a non-negotiable. Propose-then-apply is unchanged in v0.3.0: every mutating tool only records a proposal, and PlanApplier remains the sole writer. That lets you ship an AI editing feature without opening a second write path into production data — the single biggest objection in any review.
• Approval UX scope. Because the plan is an inspectable object (ChangePlan) with typed operations (attach()/detach() now included), you can decide whether v1 ships a review screen, an inline diff, or a chat-style "here's what I'd change" confirmation, without changing the backend contract.
• Read-before-write as a product requirement, now satisfiable. catalog_overview, catalog_search, catalog_get mean "rename the Trespass course" resolves to an edit rather than a duplicate record. This moves the feature from demo-grade to actually usable for maintenance work on an existing catalog — a different (and much larger) use case than greenfield creation.
• Autonomy roadmap. v0.3.0 gives you a clean ladder to plan against: read → propose → apply-with-veto (GuardsDeletion) → (future) auto-apply on low-risk operations. You can commit to stages publicly while deferring the risky ones.
• Runtime architecture choice. TeachersAid::tools(ChangePlan), systemPrompt(), prompt(), TOOL_NAMES, plus PrismTools::live(), mean the agent loop can live in your app or in an external harness. That's a decision about where conversation state and orchestration live — relevant if you already have an agent runtime or chat surface.
• Multi-turn editing conversations. Passing the pending plan into tools() lets a teacher refine ("actually make it 6 hours") across turns, which is the difference between a one-shot generator and something people will use repeatedly.
• Delete risk posture. GuardsDeletion is a host-veto hook asked both at proposal time and at apply time. Product-wise this is how you answer "what stops the AI deleting a course?" without forbidding deletes entirely.
• Failure-mode UX. Proposals are now validated when made — bad field, missing id, reused ref, unknown entity — and the model gets "Refused: …" back. Fewer dead proposals reaching the teacher's Apply button; the agent can self-correct in-conversation instead of dumping errors on a human.

When to Consider This Package

Consider it when most of these hold:

• You're on Laravel/PHP with an existing structured catalog — courses, modules, lessons, tests, curricula, and their relations — not freeform documents.
• You want an LLM assistant for maintenance of that catalog (rename, reprice, re-link, add a lesson), not just bulk creation.
• Human approval is mandatory or strongly preferred; you're not ready to let a model write directly.
• Your editable surface is expressible as configured entities and relations. If you can't enumerate the allowlist, the guardrails lose their value.
• You already have, or are willing to add, an agent runtime — Prism, or your own loop driven by tools().
• You accept a pre-1.0 API (v0.3.0) and can absorb breaking changes between minors.

Look elsewhere or wait when:

• You need autonomous writes or background batch mutation — the propose-then-apply design is deliberately in the way.
• You're not on Laravel, or your domain isn't a config-declared entity graph.
• You need semantic/embedding search or rich retrieval; the read tools are catalog lookups, not a RAG layer.
• You need a ready-made admin UI — this ships tools and a plan object, not screens.
• You need API stability guarantees; v0.3.0 already changed refusal behavior in a way that can break configs (see migration note below).
• Your catalog changes are high-volume, high-frequency imports where per-change human approval is the bottleneck.

Migration note for anyone evaluating against a draft config: an entity missing from entities is now refused at proposal time rather than recorded and failing at Apply. If your config omits something (the release calls out question), add it explicitly — otherwise those proposals silently stop being made, which can look like a model regression.

How to Pitch It (Stakeholders)

For executives: This package lets an AI assistant do the tedious parts of catalog maintenance — renaming, repricing, re-linking courses — while a teacher keeps the final say on every change. The agent can only propose; one component applies, and only after approval. Scope is bounded by configuration, and deletes can be vetoed by the host application. It converts an open-ended "add AI to our authoring tool" initiative into a bounded integration with a clear approval gate — worth a scoped pilot rather than a roadmap commitment.

For engineering: Small, opinionated surface. Tools are declared and scoped via teachers-aid.entities / teachers-aid.relations; mutating tools record typed operations into a ChangePlan; PlanApplier is the only writer; GuardsDeletion provides host veto on deletes at both propose and apply time. Proposals are validated at creation (unknown entity, bad field, missing id, dangling $ref) and refusals are returned to the model as text so it can self-correct. The driver is optional and may be a closure — only respondTo() needs one. If you already use Prism, PrismTools::live() adapts tools; if you own the loop, TeachersAid::tools($plan) plus systemPrompt()/prompt()/TOOL_NAMES let you drive it yourself and carry a pending plan across turns. Trade-off to accept: pre-1.0, and refusal semantics changed in this release — audit your entity config before upgrading.