Tutorial 113

// Copyright (c) 2025 worldiety GmbH
//
// This file is part of the NAGO Low-Code Platform.
// Licensed under the terms specified in the LICENSE file.
//
// SPDX-License-Identifier: Custom-License

// Package library is a bounded context: it says what the system does, and nothing about how it is reached.
//
// It knows nothing about the user interface in ui/ and nothing about the AI tools in ai/ - both are ways of
// reaching this context, and the dependency only ever points inwards. That is what lets the assistant be
// built from these use cases without a single adapter: a use case already has the shape a tool needs, and it
// already audits the acting subject.
package library

// BookID identifies a book in the library.
type BookID string

// Book is a title the library owns, in some number of copies.
//
// This aggregate is handed to the model as it is - there is no separate DTO next to it. The `desc` tags are
// what makes that work: they are the documentation the model reads, exactly as `label` tags are what
// form.Auto reads. A second type that had to be kept in sync with this one would buy nothing and would
// eventually drift.
//
// Write a DTO when the model needs something this type does not have: a value formatted for a human, an
// aggregate computed across records, or a subset that deliberately hides a field. Not merely to rename
// things.
type Book struct {
	ID     BookID `json:"id" desc:"stable identifier, used when lending or returning"`
	Title  string `json:"title"`
	Author string `json:"author"`
	// Copies is how many the library owns in total.
	Copies int `json:"copies" desc:"total number of copies owned, lent out ones included"`
	// LentTo lists the borrowers currently holding a copy.
	//
	// The number of free copies is Copies minus the length of this list. It is not a field of its own on
	// purpose: a derived value that is also stored is a value that can disagree with itself.
	LentTo []string `json:"lentTo,omitempty" desc:"names of the people currently holding a copy; a book is fully lent out when this has as many entries as there are copies"`
}

// Identity makes the book an aggregate root.
func (b Book) Identity() BookID { return b.ID }

// WithIdentity is required by the repository.
func (b Book) WithIdentity(id BookID) Book {
	b.ID = id
	return b
}

// String is what a picker displays.
func (b Book) String() string { return b.Title }

// Available is how many copies can still be lent out.
func (b Book) Available() int {
	return b.Copies - len(b.LentTo)
}

// BookFilter narrows a listing.
//
// Every field is optional: a filter narrows a listing, it does not command one. The `optional` tags say so to
// a model that is handed this type as a tool input - without them the schema would demand all three on every
// call, and the model would dutifully invent them.
//
// The `desc` tags are not decoration either: they are the documentation the model reads to decide how to call
// this. Write them for a colleague who has never seen the application.
type BookFilter struct {
	Query         string `json:"query" optional:"true" desc:"case-insensitive substring matched against title and author"`
	OnlyAvailable bool   `json:"onlyAvailable" optional:"true" desc:"when true, only books with at least one free copy are returned"`
	Borrower      string `json:"borrower" optional:"true" desc:"only books currently lent to this borrower"`
}

// LendRequest asks for one copy of a book.
//
// Both fields are mandatory and neither carries `optional`, so the schema tells the model as much before it
// ever calls. That is the difference to [BookFilter]: a filter narrows, a request commands.
type LendRequest struct {
	Book     BookID `json:"book" desc:"the id of the book, as returned by list_books"`
	Borrower string `json:"borrower" desc:"the name of the person receiving the copy"`
}

// LendResult reports in words what happened, because that is what both a human and a model need back.
type LendResult struct {
	Summary   string `json:"summary"`
	Available int    `json:"available" desc:"copies still available after this operation"`
}

// Copyright (c) 2025 worldiety GmbH
//
// This file is part of the NAGO Low-Code Platform.
// Licensed under the terms specified in the LICENSE file.
//
// SPDX-License-Identifier: Custom-License

package library

import (
	"go.wdy.de/nago/application/permission"
)

// Permissions of the library, one per use case and bound to it through the type parameter.
//
// One per use case is what makes authorisation assignable and auditable: an operator hands out the ability to
// lend without also handing out the ability to take back. A permission covering several use cases can only be
// granted or withheld wholesale.
//
// The texts come from the framework's translation catalogue via the Declare<Verb> helpers rather than being
// written here, because these strings appear in the role editor, where a non-developer decides who may do
// what - in their own language.
//
// This is also the entire authorisation model of the assistant. The tools in ai/ call these use cases, the
// use cases audit these permissions against the acting subject, and so the assistant can never do more than
// the person operating it.
var (
	PermFindAllBooks = permission.DeclareFindAll[FindAllBooks]("tutorial.library.book.find_all", "Buch")
	PermLendBook     = permission.DeclareUpdate[LendBook]("tutorial.library.book.lend", "Buch")
	PermReturnBook   = permission.DeclareUpdate[ReturnBook]("tutorial.library.book.return", "Buch")
)

// Copyright (c) 2025 worldiety GmbH
//
// This file is part of the NAGO Low-Code Platform.
// Licensed under the terms specified in the LICENSE file.
//
// SPDX-License-Identifier: Custom-License

package library

import (
	"fmt"
	"strings"

	"go.wdy.de/nago/auth"
)

// LendBook hands one copy of a book to a person.
type LendBook func(subject auth.Subject, req LendRequest) (LendResult, error)

// NewLendBook builds the lending use case.
func NewLendBook(repo BookRepository) LendBook {
	return func(subject auth.Subject, req LendRequest) (LendResult, error) {
		if err := subject.Audit(PermLendBook); err != nil {
			return LendResult{}, err
		}

		borrower := strings.TrimSpace(req.Borrower)
		if borrower == "" {
			return LendResult{}, fmt.Errorf("ohne Namen kann kein Exemplar herausgegeben werden")
		}

		optBook, err := repo.FindByID(req.Book)
		if err != nil {
			return LendResult{}, err
		}

		if optBook.IsNone() {
			return LendResult{}, fmt.Errorf("kein Buch mit der Kennung %q", req.Book)
		}

		book := optBook.Unwrap()
		if book.Available() <= 0 {
			return LendResult{}, fmt.Errorf("von %q ist derzeit kein Exemplar frei", book.Title)
		}

		book.LentTo = append(book.LentTo, borrower)
		if err := repo.Save(book); err != nil {
			return LendResult{}, err
		}

		// The result says what happened in words. A caller that is a model needs that as much as a human
		// does: it has to report back, and it must not have to reconstruct the outcome from the arguments it
		// sent.
		return LendResult{
			Summary:   fmt.Sprintf("%q an %s ausgeliehen.", book.Title, borrower),
			Available: book.Available(),
		}, nil
	}
}

// Copyright (c) 2025 worldiety GmbH
//
// This file is part of the NAGO Low-Code Platform.
// Licensed under the terms specified in the LICENSE file.
//
// SPDX-License-Identifier: Custom-License

package library

// UseCases bundles the capabilities of the library context.
//
// Callers depend on this bundle rather than on the internals, and [NewUseCases] is the single place where the
// repository is threaded through. The screens in ui/ and the tools in ai/ both take it, and neither can reach
// past it into the store.
type UseCases struct {
	FindAllBooks FindAllBooks
	LendBook     LendBook
	ReturnBook   ReturnBook
}

// NewUseCases wires the library use cases.
func NewUseCases(repo BookRepository) UseCases {
	return UseCases{
		FindAllBooks: NewFindAllBooks(repo),
		LendBook:     NewLendBook(repo),
		ReturnBook:   NewReturnBook(repo),
	}
}

// Copyright (c) 2025 worldiety GmbH
//
// This file is part of the NAGO Low-Code Platform.
// Licensed under the terms specified in the LICENSE file.
//
// SPDX-License-Identifier: Custom-License

// Package dec holds the recorded decisions of this example.
//
// One requirement per file, the file named after the identity. spec.Declare puts it into the runtime
// catalogue, which is what lets the running program - and the assistant in it - explain itself. Without that
// call the value exists only for the static tool, and Go offers no reflection over package level variables
// to find it again.
package dec

import "github.com/worldiety/speclink/spec"

var RDecAvailability = spec.Declare(spec.Requirement{
	ID:         "R-DEC-AVAILABILITY",
	Kind:       spec.Decision,
	Discipline: spec.Technical,
	Status:     spec.Normative,
	Title:      "Verfügbarkeit wird berechnet, nicht gespeichert",
	Text:       "Die Zahl der freien Exemplare ergibt sich aus Copies minus der Länge von LentTo und wird nirgends abgelegt.",
	Rationale:  "Ein abgeleiteter Wert, der zusätzlich gespeichert wird, ist ein Wert, der sich mit sich selbst widersprechen kann. Genau das passiert beim ersten Absturz zwischen zwei Schreibvorgängen, und danach glaubt niemand mehr der Zahl.",
	// Mandatory for a decision, and the half nobody writes unprompted: a justification is pleasant to write
	// and gets written at length, while admitting what the ruling makes worse does not.
	Consequences: "Jede Anzeige rechnet neu. Eine Auswertung über zehntausend Titel lässt sich nicht über einen Index beantworten, sondern muss den Bestand lesen.",
})

// Copyright (c) 2025 worldiety GmbH
//
// This file is part of the NAGO Low-Code Platform.
// Licensed under the terms specified in the LICENSE file.
//
// SPDX-License-Identifier: Custom-License

package library

import (
	"github.com/worldiety/speclink/spec"
	"go.wdy.de/nago/example/cmd/tutorial-113-ai-assistant/requirements/dec"
	fun "go.wdy.de/nago/example/cmd/tutorial-113-ai-assistant/requirements/fun/library"
)

var _ = spec.For[LendBook](
	spec.Satisfies(fun.RLibLend, dec.RDecBorrower),
	spec.Help("Gibt ein Exemplar an eine Person heraus. Ist keines frei, wird die Ausleihe abgelehnt — eine Vormerkung gibt es noch nicht."),
)

// Copyright (c) 2025 worldiety GmbH
//
// This file is part of the NAGO Low-Code Platform.
// Licensed under the terms specified in the LICENSE file.
//
// SPDX-License-Identifier: Custom-License

// Package ailibrary exposes the library to a language model.
//
// It sits beside ui/ rather than inside the context on purpose: a model is a way of reaching this context,
// exactly as a screen is, and neither belongs to the domain. The dependency points inwards only - ailibrary
// imports library, and library imports neither.
//
// That placement is also the answer to the question this example exists for. Because the tools call use
// cases, and a use case audits the acting subject, the assistant is bounded by the permissions of whoever is
// operating it. There is no second authorisation model to write, and none to forget.
package ailibrary

import (
	"go.wdy.de/nago/application/ai/completion"
	"go.wdy.de/nago/example/cmd/tutorial-113-ai-assistant/app/library"
)

// Tools exposes the library to the model.
//
// Note what is not here: no wrapper around the use cases, no subject parameter, no per-request rebuild. A
// nago use case has the shape func(auth.Subject, Request) (Response, error), which is exactly the shape a
// tool needs, so [completion.NewUseCaseTool] takes it unchanged and passes the acting subject through on
// every call. The tools are therefore built once, at start-up, and shared by every window and every user.
//
// The rules this file follows are worth stating explicitly, because they are what keeps an assistant safe:
//
//  1. A tool goes through a use case, never through a repository. The use case audits the acting subject, so
//     the assistant can only ever do what the person operating it could do by hand. This is not a
//     convention - it is the entire authorization model.
//  2. A tool that changes something is marked with AsMutating. Not described as writing in prose: marked. A
//     sentence in the system prompt is a request the model may ignore; the mark is a gate it cannot pass.
//  3. A listing goes through NewSeqTool, which bounds the result and tells the model when it was cut short.
//     Handing a model an unbounded list is how a context window gets exhausted.
//  4. Names are lower_snake_case and descriptions are written for someone who has never seen the
//     application. Both are validated at construction, so a mistake is a panic at start-up rather than a
//     confused model at runtime.
//  5. The domain types are handed to the model directly, carrying their own `desc` tags. A DTO is written
//     when the model needs something the aggregate does not have - not to rename fields.
//  6. WithResultDoc is used where the shape of the answer is not obvious from its field names. It costs
//     tokens on every request, so it is spent deliberately: the listing wraps its entries in a truncation
//     flag the model has to react to, while lend_book returns a sentence and a number that speak for
//     themselves.
func Tools(uc library.UseCases) []completion.Tool {
	list := completion.NewSeqTool("list_books",
		"Listet den Bestand der Bibliothek mit Titel, Autor, Gesamtzahl der Exemplare und den aktuellen Ausleihern. "+
			"Nutze die Filter, um die Antwort klein zu halten, statt die ganze Liste zu holen und selbst zu suchen.",
		uc.FindAllBooks).
		WithResultDoc()

	lend := completion.NewUseCaseTool("lend_book",
		"Leiht ein Exemplar eines Buches an eine Person aus. Nenne vorher Titel und Person, damit klar ist, was passiert.",
		uc.LendBook).
		AsMutating("gibt ein Exemplar heraus und trägt die Person als Ausleiher ein")

	ret := completion.NewUseCaseTool("return_book",
		"Nimmt ein ausgeliehenes Exemplar von einer Person zurück.",
		uc.ReturnBook).
		AsMutating("nimmt ein Exemplar zurück und entfernt die Person aus der Ausleihliste")

	return []completion.Tool{list, lend, ret}
}

// SystemPrompt is the domain half of what the model is told.
//
// It carries no requirement index and no list of decisions. Both come from the framework: aispeclink.Index
// renders the catalogue, and uicompletion.WindowContext renders where the user stands. Writing either of
// them here would be a copy of something already recorded, and the copy is the one that rots.
//
// What is deliberately absent is any instruction about asking before writing. That is enforced structurally
// by ConfirmMutations, and repeating it here would suggest it were the prompt's job.
const SystemPrompt = `Du hilfst beim Betrieb einer kleinen Bibliothek.

Arbeitsweise:
- Rate nicht. Alles Fachliche steht hinter Werkzeugen; wenn du etwas nicht weißt, hole es dir.
- Antworte knapp und in ganzen Sätzen. Nenne Bücher mit Titel und Autor, nicht mit ihrer Kennung.
- Wenn ein Werkzeug meldet, dass die Liste gekürzt wurde, sage das dazu und grenze die Suche ein, statt so zu tun, als wäre sie vollständig.
- Ein Berechtigungsfehler ist ein erwartetes Ergebnis, keine Störung. Sage dann, dass dem Nutzer die Berechtigung fehlt.

Fragt jemand, WARUM sich das System so verhält oder warum es etwas ablehnt, lies die zugehörige Anforderung
mit read_requirement und antworte daraus. Erfinde keine Begründung — eine erfundene Regel klingt wie das
System, das über sich selbst spricht, und ist schlimmer als keine Antwort. Bei Entscheidungen nenne auch,
was sie kostet, wenn jemand sie in Frage stellt.

Achte auf den Zustand einer Anforderung: „planned" heißt, dass etwas bewusst noch nicht umgesetzt ist. Das
ist etwas anderes als „gibt es nicht", und der Unterschied ist für den Fragenden der ganze Punkt.

Für Orientierungsfragen („was kann das hier eigentlich") nimm read_capabilities.`

// Copyright (c) 2025 worldiety GmbH
//
// This file is part of the NAGO Low-Code Platform.
// Licensed under the terms specified in the LICENSE file.
//
// SPDX-License-Identifier: Custom-License

// Package cfglibrary wires the library context into a running application.
//
// It is the layer where storage, screens and domain meet, and the only one that is allowed to. The context
// itself knows only its repository interface, so swapping the store never touches a use case, and it knows
// nothing about its own screens.
package cfglibrary

import (
	"fmt"

	"go.wdy.de/nago/application"
	"go.wdy.de/nago/application/permission"
	"go.wdy.de/nago/application/role"
	"go.wdy.de/nago/example/cmd/tutorial-113-ai-assistant/app/library"
	uilibrary "go.wdy.de/nago/example/cmd/tutorial-113-ai-assistant/app/library/ui"
	"go.wdy.de/nago/pkg/data/json"
	"go.wdy.de/nago/presentation/core"
)

// RoleLibrarian is what an operator assigns to give somebody the library.
const RoleLibrarian role.ID = "tutorial.library.librarian"

// Module is what the rest of the application depends on.
type Module struct {
	UseCases library.UseCases
	Pages    uilibrary.Pages
}

// Enable builds the library context, seeds it, ships its role and registers its screens.
func Enable(cfg *application.Configurator) (Module, error) {
	store, err := cfg.EntityStore("tutorial.library.book")
	if err != nil {
		return Module{}, fmt.Errorf("cannot open book store: %w", err)
	}

	repo := library.BookRepository(json.NewSloppyJSONRepository[library.Book, library.BookID](store))
	if err := library.Seed(repo); err != nil {
		return Module{}, fmt.Errorf("cannot seed the shelf: %w", err)
	}

	uc := library.NewUseCases(repo)

	if err := declareLibrarianRole(cfg); err != nil {
		return Module{}, err
	}

	pages := uilibrary.Pages{Books: "."}

	// The purpose is registered with the route rather than with a menu entry, because the registration is the
	// only declaration every screen has: not every screen appears in a menu, and menus are rearranged freely.
	// uicompletion.WindowContext reads it to tell the model where the user is standing.
	cfg.RootViewWithDecoration(pages.Books, func(wnd core.Window) core.View {
		return uilibrary.PageBooks(wnd, uc)
	}, application.Purpose(
		"Den Bestand der Bibliothek durchsehen: welche Titel es gibt, wie viele Exemplare frei sind und wer welches ausgeliehen hat."))

	return Module{UseCases: uc, Pages: pages}, nil
}

// declareLibrarianRole ships the application's own authorization as one assignable role.
//
// Two things are worth noticing here.
//
// First, the assistant permissions are deliberately NOT in this list. cfgai declares its own system role
// (cfgai.RoleAssistantUser) holding exactly the three framework permissions the chat needs, and assigning
// that role is what makes the button appear. Keeping them apart means an operator can decide per user whether
// they get the assistant, without touching what the user may do in the application - and the assistant,
// bounded by the acting subject, still cannot exceed the library permissions granted here.
//
// Second, this is a system role, so it cannot be deleted and its permission set cannot be edited away in the
// admin UI. Both would be undone on the next start anyway; refusing outright is the honest version.
func declareLibrarianRole(cfg *application.Configurator) error {
	return cfg.DeclareSystemRole(role.Role{
		ID:          RoleLibrarian,
		Name:        "Bibliothekar",
		Description: "Darf den Bestand einsehen sowie Exemplare ausleihen und zurücknehmen.",
	}, LibrarianPermissions()...)
}

// LibrarianPermissions is spelled out as its own function so a test can check it without reaching into the
// declaration.
func LibrarianPermissions() []permission.ID {
	return []permission.ID{
		library.PermFindAllBooks,
		library.PermLendBook,
		library.PermReturnBook,
	}
}

// Copyright (c) 2025 worldiety GmbH
//
// This file is part of the NAGO Low-Code Platform.
// Licensed under the terms specified in the LICENSE file.
//
// SPDX-License-Identifier: Custom-License

// Command ai-example puts an AI assistant on top of an ordinary nago application.
//
// The entry point lives under cmd/ and does what an entry point does: it bootstraps the framework, enables
// the contexts and decides how they are reached. Every piece of business meaning is behind app/library.
package main

import (
	"time"

	"github.com/worldiety/option"
	"go.wdy.de/nago/application"
	cfgai "go.wdy.de/nago/application/ai/cfg"
	uicompletion "go.wdy.de/nago/application/ai/completion/ui"
	_ "go.wdy.de/nago/application/ai/provider/anthropic"
	_ "go.wdy.de/nago/application/ai/provider/mistralai"
	_ "go.wdy.de/nago/application/ai/provider/openai"
	aispeclink "go.wdy.de/nago/application/speclink/ai"
	cfgspeclink "go.wdy.de/nago/application/speclink/cfg"
	ailibrary "go.wdy.de/nago/example/cmd/tutorial-113-ai-assistant/app/library/ai"
	cfglibrary "go.wdy.de/nago/example/cmd/tutorial-113-ai-assistant/app/library/cfg"
	"go.wdy.de/nago/presentation/core"
	"go.wdy.de/nago/web/vuejs"
)

func main() {
	application.Configure(func(cfg *application.Configurator) {
		cfg.SetApplicationID("de.worldiety.tutorial_113")
		cfg.Serve(vuejs.Dist())

		option.MustZero(cfg.StandardSystems())
		option.Must(option.Must(cfg.UserManagement()).UseCases.EnableBootstrapAdmin(time.Now().Add(time.Hour), "%6UbRsCuM8N$auy"))

		// The context wires itself: store, use cases, its role and its screens. Nothing about the library
		// leaks into this file.
		lib := option.Must(cfglibrary.Enable(cfg))

		modAI := option.Must(cfgai.Enable(cfg))

		// The requirement catalogue of this binary, with ready-made tools on top. Nothing about the library
		// is repeated here: spec.Declare filled the catalogue during package initialisation, and the tools
		// read it through use cases that audit the acting subject like every other one.
		specMod := option.Must(cfgspeclink.Enable(cfg))

		// Build the tools once. They receive the acting subject per call, so there is nothing per-user about
		// them and nothing to rebuild per turn.
		tools := append(ailibrary.Tools(lib.UseCases), aispeclink.Tools(specMod.UseCases)...)

		scaffold := cfg.NewScaffold().
			Login(true).
			MenuEntry().Title("Bestand").Forward(lib.Pages.Books).Private().
			Decorator()

		// The assistant hangs on the decorator rather than on a page, so it is genuinely on every screen -
		// including the administration pages the framework brings along. When it cannot run (no provider, no
		// model, hidden by the operator, missing role) Decorate returns the view untouched and logs why.
		cfg.SetDecorator(func(wnd core.Window, view core.View) core.View {
			return modAI.Assistant.Decorate(wnd, scaffold(wnd, view), cfgai.AssistantOptions{
				Title: "Bibliotheks-Assistent",
				Label: "Assistent",
				// One tag for the whole application: the assistant follows the user from screen to screen, so
				// a conversation started on one page and continued on another is one conversation.
				Tags:             []string{"tutorial113:assistant"},
				History:          true,
				AskUser:          true,
				ConfirmMutations: true,
				MaxTurns:         32,
				Agents: []uicompletion.Agent{{
					ID:    "librarian",
					Name:  "Bibliotheks-Assistent",
					Tools: tools,
					// Rebuilt on every question, because both derived halves move: the requirement index grows
					// with the project, and the situational half changes with every navigation. Only the
					// domain half is a constant, and it is the only one written by hand.
					SystemPromptFunc: func() string {
						return ailibrary.SystemPrompt + "\n\n" +
							aispeclink.Index(wnd.Subject(), specMod.UseCases) + "\n" +
							uicompletion.WindowContext(wnd)
					},
				}},
			})
		})
	}).Run()
}