AI Assistant

// 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 (
	"slices"
	"time"

	"github.com/worldiety/option"
	"go.wdy.de/nago/application"
	cfgai "go.wdy.de/nago/application/ai/cfg"
	"go.wdy.de/nago/application/ai/completion"
	uicompletion "go.wdy.de/nago/application/ai/completion/ui"
	_ "go.wdy.de/nago/application/ai/provider/anthropic"
	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 scaffold(wnd, modAI.Assistant.Decorate(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,
				MaxTurns: 32,
				Agents: []uicompletion.Agent{{
					ID:   "librarian",
					Name: "Bibliotheks-Assistent",
					// The screen tool is the only one built per window, because it looks at this window. It is
					// the feedback channel of the assistant: after lending a book, the model can check what the
					// user actually sees instead of assuming it worked. slices.Concat copies, so the shared
					// slice is never appended to from several windows at once.
					Tools: slices.Concat(tools, []completion.Tool{
						uicompletion.ScreenTool(wnd, uicompletion.ScreenToolOptions{}),
					}),
					// 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()
}

// 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,
	}
}

// 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 the confirmation of the assistant, 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.

Bezieht sich jemand auf etwas, das er gerade sieht, oder hast du etwas geändert, sieh mit inspect_screen nach,
was tatsächlich angezeigt wird, statt es anzunehmen.`

// 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"`
}

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")
)

package library

import (
	"go.wdy.de/nago/pkg/data"
)

// BookRepository stores the books. The context declares what it needs and never how it is stored; which
// store this is, is decided once in cfg/.
type BookRepository = data.Repository[Book, BookID]

// Seed puts something on the shelf so the example has something to talk about. It does nothing when the
// shelf is not empty, so a restart does not duplicate the stock.
func Seed(repo BookRepository) error {
	count, err := repo.Count()
	if err != nil {
		return err
	}

	if count > 0 {
		return nil
	}

	books := []Book{
		{ID: "b1", Title: "Der Prozess", Author: "Franz Kafka", Copies: 2},
		{ID: "b2", Title: "Die Verwandlung", Author: "Franz Kafka", Copies: 1},
		{ID: "b3", Title: "Effective Go", Author: "The Go Authors", Copies: 3},
		{ID: "b4", Title: "Der Steppenwolf", Author: "Hermann Hesse", Copies: 1, LentTo: []string{"Anna"}},
	}

	for _, b := range books {
		if err := repo.Save(b); err != nil {
			return err
		}
	}

	return nil
}

// This file sits next to uc_find_all_books.go and is part of the normal build. That coupling is the point:
// delete the use case and this file stops compiling, so the binding cannot rot unnoticed.
//
// Satisfies is the one statement no static analysis can infer — which requirement a construct was written
// for. Help is what an assistant reads back through read_capabilities.
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[FindAllBooks](
	spec.Satisfies(fun.RLibStock, dec.RDecAvailability),
	spec.Help("Zeigt den Bestand mit Titel, Autor, Gesamtzahl der Exemplare und den aktuellen Ausleihern. Die Zahl der freien Exemplare ergibt sich aus den ersten beiden."),
)

package library

import (
	"iter"
	"strings"

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

// FindAllBooks reads the stock, narrowed by a filter.
//
// Reading is a promise too - that someone may see a thing - so a query is no different from any other use
// case: its own file, its own constructor, its own permission, its own place in the bundle.
type FindAllBooks func(subject auth.Subject, filter BookFilter) iter.Seq2[Book, error]

// NewFindAllBooks builds the listing query over the book repository.
func NewFindAllBooks(repo BookRepository) FindAllBooks {
	return func(subject auth.Subject, filter BookFilter) iter.Seq2[Book, error] {
		return func(yield func(Book, error) bool) {
			if err := subject.Audit(PermFindAllBooks); err != nil {
				yield(Book{}, err)
				return
			}

			for book, err := range repo.All() {
				if err != nil {
					yield(Book{}, err)
					return
				}

				if !filter.Matches(book) {
					continue
				}

				if !yield(book, nil) {
					return
				}
			}
		}
	}
}

// Matches reports whether a book falls into the filter.
func (f BookFilter) Matches(b Book) bool {
	if f.OnlyAvailable && b.Available() <= 0 {
		return false
	}

	if q := strings.ToLower(strings.TrimSpace(f.Query)); q != "" {
		if !strings.Contains(strings.ToLower(b.Title), q) && !strings.Contains(strings.ToLower(b.Author), q) {
			return false
		}
	}

	if f.Borrower != "" {
		if !b.isLentTo(f.Borrower) {
			return false
		}
	}

	return true
}

// isLentTo reports whether this person currently holds a copy. The comparison ignores case because the name
// is typed by a human - or, increasingly, produced by one from a sentence.
func (b Book) isLentTo(borrower string) bool {
	for _, who := range b.LentTo {
		if strings.EqualFold(who, borrower) {
			return true
		}
	}

	return false
}

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."),
)

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
	}
}

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[ReturnBook](
	spec.Satisfies(fun.RLibReturn, dec.RDecReturnMatch),
	spec.Help("Nimmt ein Exemplar von einer Person zurück. Hat die Person kein Exemplar dieses Titels, wird die Rücknahme abgelehnt."),
)

package library

import (
	"fmt"
	"strings"

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

// ReturnBook takes a lent copy back from a person.
type ReturnBook func(subject auth.Subject, req LendRequest) (LendResult, error)

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

		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()

		idx := -1
		for i, who := range book.LentTo {
			if strings.EqualFold(who, req.Borrower) {
				idx = i
				break
			}
		}

		if idx < 0 {
			return LendResult{}, fmt.Errorf("%s hat kein Exemplar von %q", req.Borrower, book.Title)
		}

		book.LentTo = append(book.LentTo[:idx], book.LentTo[idx+1:]...)
		if err := repo.Save(book); err != nil {
			return LendResult{}, err
		}

		return LendResult{
			Summary:   fmt.Sprintf("%q von %s zurückerhalten.", book.Title, req.Borrower),
			Available: book.Available(),
		}, nil
	}
}

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),
	}
}

// Package uilibrary renders the library for a human.
//
// The directory is always ui/, so the package name is what tells a reader whose interface this is. It imports
// the context; the context must never import it, because that would invert the ordering and make the domain
// untestable without a renderer.
package uilibrary

import (
	"strconv"

	"go.wdy.de/nago/example/cmd/tutorial-113-ai-assistant/app/library"
	"go.wdy.de/nago/presentation/core"
	"go.wdy.de/nago/presentation/ui"
)

// Pages are the routes of this context.
type Pages struct {
	Books core.NavigationPath
}

// PageBooks lists the stock.
//
// It is here so the assistant has a screen to be aware of, and so the application.Purpose registered in cfg/
// describes something real. It is deliberately plain: the subject of this example is next door in ai/.
func PageBooks(wnd core.Window, uc library.UseCases) core.View {
	var rows []core.View
	for book, err := range uc.FindAllBooks(wnd.Subject(), library.BookFilter{}) {
		if err != nil {
			return ui.Text(err.Error())
		}

		rows = append(rows, ui.HStack(
			ui.Text(book.Title).Font(ui.BodyMedium),
			ui.Text(book.Author),
			ui.Text(availabilityOf(book)),
		).Gap(ui.L16).FullWidth().Alignment(ui.Leading))
	}

	if len(rows) == 0 {
		rows = append(rows, ui.Text("Kein Bestand sichtbar. Fehlt die Rolle „Bibliothekar“?"))
	}

	return ui.VStack(
		ui.H1("Bestand"),
		ui.Text("Frag den Assistenten unten rechts, was verfügbar ist, oder lass ihn ein Exemplar ausleihen. Vor jeder Änderung wird nachgefragt."),
		ui.VStack(rows...).Gap(ui.L8).FullWidth(),
	).Gap(ui.L16).Alignment(ui.Leading).FullWidth().
		Padding(ui.Padding{}.All(ui.L16))
}

// availabilityOf says in words what a bare number would leave the reader to work out.
func availabilityOf(b library.Book) string {
	switch {
	case b.Available() <= 0:
		return "alle Exemplare ausgeliehen"
	case b.Available() == 1:
		return "1 Exemplar frei"
	default:
		return strconv.Itoa(b.Available()) + " Exemplare frei"
	}
}

// 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.",
})

package dec

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

var RDecBorrower = spec.Declare(spec.Requirement{
	ID:           "R-DEC-BORROWER",
	Kind:         spec.Decision,
	Discipline:   spec.Business,
	Status:       spec.Normative,
	Title:        "Ausleiher werden als Name geführt, nicht als Benutzerkonto",
	Text:         "LentTo enthält Klartextnamen; es gibt keine Verknüpfung zur Benutzerverwaltung.",
	Rationale:    "Eine Bibliothek leiht auch an Menschen aus, die kein Konto in diesem System haben — Gäste, Praktikanten, die Kollegin aus dem Nachbarhaus. Ein Fremdschlüssel auf die Benutzertabelle hätte genau diese Fälle ausgeschlossen.",
	Consequences: "Zwei Personen gleichen Namens sind nicht unterscheidbar, und es gibt keine automatische Erinnerung, weil das System keine Adresse kennt. Wer das braucht, muss diese Entscheidung zuerst umdrehen.",
})

package dec

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

var RDecReturnMatch = spec.Declare(spec.Requirement{
	ID:           "R-DEC-RETURN-MATCH",
	Kind:         spec.Decision,
	Discipline:   spec.Technical,
	Status:       spec.Normative,
	Title:        "Die Rücknahme vergleicht Namen ohne Rücksicht auf Groß- und Kleinschreibung",
	Text:         "ReturnBook findet den Ausleiher über einen Vergleich, der Groß- und Kleinschreibung ignoriert.",
	Rationale:    "Der Name wird von einem Menschen getippt — und zunehmend von einem Sprachmodell aus einem Satz gebildet. Ein exakter Vergleich hätte zur Folge, dass „anna“ ein Exemplar nicht zurückgeben kann, das „Anna“ ausgeliehen hat, und der Fehler sähe aus wie ein Datenfehler.",
	Consequences: "„Anna“ und „anna“ können nicht gleichzeitig je ein Exemplar desselben Titels halten, ohne dass die Rücknahme rät. Bei mehr als einer Handvoll Ausleihern braucht es eine echte Kennung statt eines Namens.",
	DerivedFrom:  []spec.Requirement{RDecBorrower},
})

package library

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

var RLibLend = spec.Declare(spec.Requirement{
	ID:         "R-LIB-LEND",
	Kind:       spec.Functional,
	Discipline: spec.Business,
	Status:     spec.Normative,
	Title:      "Exemplar ausleihen",
	Text:       "Ein freies Exemplar MUSS an eine namentlich genannte Person ausgeliehen werden können; ist keines frei, MUSS die Ausleihe abgelehnt werden.",
})

package library

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

// RLibReservation is deliberately Planned and bound to nothing.
//
// It is in this example on purpose. speclink demands a binding only for Normative requirements, so a planned
// one appears in no binding and would be missing from a view built on spec.Entries() alone — and an
// assistant reading that view would answer "so etwas gibt es nicht", which is a different and much worse
// statement than "das ist noch nicht umgesetzt". Reading the catalogue keeps the two apart.
var RLibReservation = spec.Declare(spec.Requirement{
	ID:         "R-LIB-RESERVATION",
	Kind:       spec.Functional,
	Discipline: spec.Business,
	Status:     spec.Planned,
	Title:      "Vormerkung auf ein ausgeliehenes Exemplar",
	Text:       "Ist kein Exemplar frei, SOLL sich eine Person vormerken lassen können und benachrichtigt werden, sobald eines zurückkommt.",
})

package library

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

var RLibReturn = spec.Declare(spec.Requirement{
	ID:         "R-LIB-RETURN",
	Kind:       spec.Functional,
	Discipline: spec.Business,
	Status:     spec.Normative,
	Title:      "Exemplar zurücknehmen",
	Text:       "Ein ausgeliehenes Exemplar MUSS von der Person zurückgenommen werden können, die es hält.",
})

// Package library holds the functional requirements of the library domain.
package library

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

var RLibStock = spec.Declare(spec.Requirement{
	ID:         "R-LIB-STOCK",
	Kind:       spec.Functional,
	Discipline: spec.Business,
	Status:     spec.Normative,
	Title:      "Bestand einsehen",
	Text:       "Der Bestand MUSS mit Titel, Autor, Gesamtzahl der Exemplare und den aktuellen Ausleihern eingesehen werden können.",
})