KRET LANGUAGE ACADEMY · DOKUMENTACJA ZE ŹRÓDEŁ
Deklaracja modelu i narzędzi
Czego się nauczysz
- Prześledź źródła i wyjaśnij opisany kontrakt.
- W Declarations wskaż deklarację modelu oraz funkcję narzędzia KretS. Nie wpisuj klucza usług AI do źródeł.
Wymagania wstępne
- Ukończ Podstawy i wcześniejszy poziom tej ścieżki.
Wyjaśnienie krok po kroku
KretAI opisuje modele, narzędzia i agentów. Kontrakt 1.0 obejmuje deklaracje, walidację i bramki danych. Pomyślny check nie oznacza odpowiedzi modelu. Prawdziwe wykonanie AI pozostaje poza kontraktem 1.0 i jest wyłączone w Core.
Praca z kodem źródłowym
Deklaracje modelu, narzędzi i agentów
Plik `Ai/assistant.kretai` z szablonu SDK: model lokalny z polityką `local-only`, dwa narzędzia (funkcje KretS z zadeklarowaną sygnaturą i uprawnieniami), dwa agenci z limitami i delegacją. **Model nie jest uruchamiany** — kompilator sprawdza deklaracje, zgodność narzędzi z funkcjami KretS i uprawnienia. Plugin startuje bez AI (zwraca liczbę zamówień z KretDB).
kretai "1.0"
// Model lokalny: serwer modeli na tym komputerze (protokół chat/completions — llama.cpp server, Ollama, LM Studio).
// Polityka „local-only”: brama wymusza, żeby połączenie kończyło się na adresie pętli zwrotnej — dane nie opuszczają komputera.
model local.small {
provider "local"
name "qwen2.5:7b"
endpoint "http://127.0.0.1:11434"
dataPolicy "local-only"
maxOutputTokens 1024
timeout 2min
}
tool counter.read {
description "Odczytuje wartość licznika o podanej nazwie."
handler "Tools.readCounter"
parameter name String "Nazwa licznika, np. orders"
returns "Int64"
permissions {
kretdb.open
kretdb.read
}
sideEffects "none"
}
tool counter.add {
description "Zwiększa licznik o podaną wartość i zwraca nowy stan."
handler "Tools.addCounter"
parameter name String "Nazwa licznika"
parameter amount Int64 "O ile zwiększyć"
returns "Int64"
permissions {
kretdb.open
kretdb.read
kretdb.write
}
sideEffects "write"
requiresConfirmation true
}
// Agent tylko do odczytu.
agent reader {
model local.small
system "Odpowiadasz krótko i tylko na podstawie danych z narzędzi."
tools counter.read
permissions {
kretdb.open
kretdb.read
}
limits {
maxSteps 4
maxToolCalls 8
timeout 2min
}
}
// Agent, który może zmieniać dane — każde wywołanie narzędzia zapisującego wymaga potwierdzenia.
agent assistant {
model local.small
system "Pomagasz prowadzić liczniki. Zanim coś zmienisz, sprawdź obecny stan."
tools counter.read counter.add
delegates reader
permissions {
kretdb.open
kretdb.read
kretdb.write
}
limits {
maxSteps 8
maxToolCalls 16
timeout 5min
maxTokens 200000
}
}
Czytanie kodu linia po linii
Objaśnienia struktury nie są walidacją semantyczną. Szczegółowy kontrakt opisują referencje i README przykładu.
kretai "1.0"Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.Pusta linia oddziela fragmenty źródła.// Model lokalny: serwer modeli na tym komputerze (protokół chat/completions — llama.cpp server, Ollama, LM Studio).Komentarz autora; nie jest wykonywany.// Polityka „local-only”: brama wymusza, żeby połączenie kończyło się na adresie pętli zwrotnej — dane nie opuszczają komputera.Komentarz autora; nie jest wykonywany.model local.small {Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.provider "local"Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.name "qwen2.5:7b"Pole tożsamości lub wersji w otaczającym bloku; zachowaj jego kontekst.endpoint "http://127.0.0.1:11434"Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.dataPolicy "local-only"Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.maxOutputTokens 1024Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.timeout 2minOdczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.}Zamknięcie struktury otwartej we wcześniejszych liniach.Pusta linia oddziela fragmenty źródła.tool counter.read {Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.description "Odczytuje wartość licznika o podanej nazwie."Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.handler "Tools.readCounter"Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.parameter name String "Nazwa licznika, np. orders"Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.returns "Int64"Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.permissions {Początek nazwanego bloku; jego pola odczytaj w powiązanej referencji.kretdb.openOdczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.kretdb.readOdczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.}Zamknięcie struktury otwartej we wcześniejszych liniach.sideEffects "none"Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.}Zamknięcie struktury otwartej we wcześniejszych liniach.Pusta linia oddziela fragmenty źródła.tool counter.add {Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.description "Zwiększa licznik o podaną wartość i zwraca nowy stan."Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.handler "Tools.addCounter"Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.parameter name String "Nazwa licznika"Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.parameter amount Int64 "O ile zwiększyć"Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.returns "Int64"Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.permissions {Początek nazwanego bloku; jego pola odczytaj w powiązanej referencji.kretdb.openOdczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.kretdb.readOdczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.kretdb.writeOdczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.}Zamknięcie struktury otwartej we wcześniejszych liniach.sideEffects "write"Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.requiresConfirmation trueOdczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.}Zamknięcie struktury otwartej we wcześniejszych liniach.Pusta linia oddziela fragmenty źródła.// Agent tylko do odczytu.Komentarz autora; nie jest wykonywany.agent reader {Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.model local.smallOdczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.system "Odpowiadasz krótko i tylko na podstawie danych z narzędzi."Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.tools counter.readOdczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.permissions {Początek nazwanego bloku; jego pola odczytaj w powiązanej referencji.kretdb.openOdczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.kretdb.readOdczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.}Zamknięcie struktury otwartej we wcześniejszych liniach.limits {Początek nazwanego bloku; jego pola odczytaj w powiązanej referencji.maxSteps 4Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.maxToolCalls 8Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.timeout 2minOdczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.}Zamknięcie struktury otwartej we wcześniejszych liniach.}Zamknięcie struktury otwartej we wcześniejszych liniach.Pusta linia oddziela fragmenty źródła.// Agent, który może zmieniać dane — każde wywołanie narzędzia zapisującego wymaga potwierdzenia.Komentarz autora; nie jest wykonywany.agent assistant {Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.model local.smallOdczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.system "Pomagasz prowadzić liczniki. Zanim coś zmienisz, sprawdź obecny stan."Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.tools counter.read counter.addOdczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.delegates readerOdczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.permissions {Początek nazwanego bloku; jego pola odczytaj w powiązanej referencji.kretdb.openOdczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.kretdb.readOdczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.kretdb.writeOdczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.}Zamknięcie struktury otwartej we wcześniejszych liniach.limits {Początek nazwanego bloku; jego pola odczytaj w powiązanej referencji.maxSteps 8Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.maxToolCalls 16Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.timeout 5minOdczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.maxTokens 200000Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.}Zamknięcie struktury otwartej we wcześniejszych liniach.}Zamknięcie struktury otwartej we wcześniejszych liniach.
Oczekiwany wynik: `check` = sukces; `run` zwraca „zamówień: 0”. Żaden model nie został wywołany.
Typowy błąd: Traktowanie poprawnej deklaracji jako dowodu działania modelu. Wykonanie z prawdziwym modelem to KretAI 1.1+ (NOT_RUN); w Core KretAI jest DISABLED.
Instrukcja, wersje i zapisane wyniki →Materiały źródłowe do tego tematu
Przeczytaj powiązane rozdziały. Kod i kontrakty zachowano z importu; historia źródeł jest dostępna przy każdym rozdziale.
KretAI — wprowadzenie
KretAI — wprowadzenie
Status 1.0: `FROZEN_SUPPORTED_SUBSET` — zamrożony dokładnie opisany zakres; reszta poza kontraktem 1.0. Gramatyka/wersja: kretai-1.0. Status języka nie nadaje uprawnień KCS ani prawa do działania w Production.Czym jest
KretAI (w SDK KretAi) deklaruje modele, narzędzia (funkcje KretS) i agentów. Zamrożone są deklaracje, walidacja oraz bramki uprawnień i polityki danych. Wykonanie z prawdziwym modelem nie należy do kontraktu 1.0 (KretAI 1.1+, NOT_RUN). W Core KretAI jest DISABLED.
Dla początkujących
Opisujesz, z jakiego modelu agent może korzystać, jakich narzędzi (zwykłych funkcji KretS) i w jakich limitach. Kompilator sprawdza te opisy. W tej wersji nie uruchamiasz prawdziwego modelu — sprawdzasz deklaracje i bramki bezpieczeństwa.
Dla zaawansowanych programistów
Agent nie ma własnych uprawnień (co najwyżej to, co host przyznał podmiotowi). Narzędzie działa z uprawnieniami swojej deklaracji; argumenty od modelu są danymi niezaufanymi (obiekt JSON o dokładnie zadeklarowanych polach). Model zewnętrzny wymaga 6 warunków (polityka danych, polityka hosta, lista hostów, https, zgoda, kretai.external_model.connect); brak któregokolwiek = odmowa przed połączeniem. local-only wymusza połączenie na pętli zwrotnej. Sekrety (klucz API) tylko z KretConfig/Vault.
Jakie problemy rozwiązuje
Bezpieczne, audytowalne deklarowanie użycia AI przed jakimkolwiek wykonaniem modelu.
Kiedy używać
- deklarowanie kontraktów AI (modele, narzędzia, agenci)
- walidacja polityk modeli i uprawnień narzędzi
- testowanie narzędzi jako zwykłego KretS
Kiedy nie używać
- oczekiwanie działania prawdziwego modelu (NOT_RUN; KretAI 1.1/1.2)
- użycie w Core (DISABLED do decyzji KCS)
- wpisywanie kluczy API w plikach (tylko odwołanie do Vault)
Współpraca z innymi technologiami
KretS (ai.ask, narzędzia), KretDB (pamięć agenta), KretConfig/Vault (sekrety), KretL (uprawnienia kretai.*, kretdb.*).
Obecny status
FROZEN_SUPPORTED_SUBSET — zamrożony dokładnie opisany zakres; reszta poza kontraktem 1.0.
Dalej: ARCHITECTURE.md · SYNTAX_REFERENCE.md · ../Tutorials/BASIC/TUTORIAL_PL.md
KretAI — referencja składni
KretAI — referencja składni
Status 1.0: `FROZEN_SUPPORTED_SUBSET` — zamrożony dokładnie opisany zakres; reszta poza kontraktem 1.0. Gramatyka/wersja: kretai-1.0. Status języka nie nadaje uprawnień KCS ani prawa do działania w Production.Opisane są wyłącznie konstrukcje potwierdzone implementacją SDK (i, gdzie zaznaczono, testami tej rundy).
model
Deklaracja modelu.
model local.small {
provider "local"
name "qwen2.5:7b"
endpoint "http://127.0.0.1:11434"
dataPolicy "local-only"
maxOutputTokens 1024
timeout 2min
}
Czytanie kodu linia po linii
Objaśnienia struktury nie są walidacją semantyczną. Szczegółowy kontrakt opisują referencje i README przykładu.
model local.small {Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.provider "local"Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.name "qwen2.5:7b"Pole tożsamości lub wersji w otaczającym bloku; zachowaj jego kontekst.endpoint "http://127.0.0.1:11434"Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.dataPolicy "local-only"Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.maxOutputTokens 1024Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.timeout 2minOdczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.}Zamknięcie struktury otwartej we wcześniejszych liniach.
| Cecha | Wartość |
|---|---|
| Parametry / typy | provider local|anthropic, name, endpoint (local), dataPolicy local-only|external-allowed, secret (klucz ustawienia KretConfig), maxOutputTokens, timeout, effort, refusalFallback |
| Wynik | — |
| Wymagania | — |
| Ograniczenia | inna polityka danych → odrzucenie (sprawdzone) |
| Możliwe błędy | KCS-KAI-* |
| Wprowadzono | 1.0 |
tool
Narzędzie = funkcja KretS o zadeklarowanej sygnaturze.
tool counter.add {
description "…"
handler "Tools.addCounter"
parameter name String "…"
parameter amount Int64 "…"
returns "Int64"
permissions {
kretdb.write
}
sideEffects "write"
requiresConfirmation true
}
Czytanie kodu linia po linii
Objaśnienia struktury nie są walidacją semantyczną. Szczegółowy kontrakt opisują referencje i README przykładu.
tool counter.add {Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.description "…"Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.handler "Tools.addCounter"Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.parameter name String "…"Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.parameter amount Int64 "…"Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.returns "Int64"Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.permissions {Początek nazwanego bloku; jego pola odczytaj w powiązanej referencji.kretdb.writeOdczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.}Zamknięcie struktury otwartej we wcześniejszych liniach.sideEffects "write"Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.requiresConfirmation trueOdczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.}Zamknięcie struktury otwartej we wcześniejszych liniach.
| Cecha | Wartość |
|---|---|
| Parametry / typy | handler, parameter, returns, permissions, sideEffects none|write, requiresConfirmation |
| Wynik | wynik funkcji |
| Wymagania | requiresConfirmation obowiązkowe przy write; sygnatura zgodna z KretS |
| Ograniczenia | funkcje ochronne zakazane |
| Możliwe błędy | KCS-KAI-* |
| Wprowadzono | 1.0 |
agent
Agent z narzędziami, delegacją i limitami.
agent assistant {
model local.small
system "…"
tools counter.read counter.add
delegates reader
permissions { … }
limits {
maxSteps 8
maxToolCalls 16
timeout 5min
}
}
Czytanie kodu linia po linii
Objaśnienia struktury nie są walidacją semantyczną. Szczegółowy kontrakt opisują referencje i README przykładu.
agent assistant {Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.model local.smallOdczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.system "…"Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.tools counter.read counter.addOdczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.delegates readerOdczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.permissions { … }Początek nazwanego bloku; jego pola odczytaj w powiązanej referencji.limits {Początek nazwanego bloku; jego pola odczytaj w powiązanej referencji.maxSteps 8Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.maxToolCalls 16Odczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.timeout 5minOdczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.}Zamknięcie struktury otwartej we wcześniejszych liniach.}Zamknięcie struktury otwartej we wcześniejszych liniach.
| Cecha | Wartość |
|---|---|
| Parametry / typy | model, system, tools, delegates, permissions, limits (obowiązkowe), memory |
| Wynik | — |
| Wymagania | uprawnienia agenta ⊇ uprawnienia narzędzi; delegat ⊆ delegujący; brak cykli |
| Ograniczenia | budżety kroków, wywołań, tokenów, czasu |
| Możliwe błędy | KCS-KAI-* |
| Wprowadzono | 1.0 |
ai.ask (KretS)
Wywołanie agenta z KretS.
use Kret.Ai as ai
let answer = ai.ask("assistant", "Ile jest zamówień?")
Czytanie kodu linia po linii
Objaśnienia struktury nie są walidacją semantyczną. Szczegółowy kontrakt opisują referencje i README przykładu.
use Kret.Ai as aiOdczytaj tę linię w kontekście otaczającego bloku i objaśnień autora poniżej.let answer = ai.ask("assistant", "Ile jest zamówień?")Wiązanie wartości; typ i możliwość zmiany zależą od użytej deklaracji.
| Cecha | Wartość |
|---|---|
| Parametry / typy | agent, polecenie |
| Wynik | String |
| Wymagania | kretai.use, kretai.model.use (SENSITIVE) |
| Ograniczenia | prawdziwy model NOT_RUN |
| Możliwe błędy | KCS-KAI-0301, KCS-KAI-0302 |
| Wprowadzono | 1.0 |
KretAI — samouczek BASIC
KretAI — samouczek BASIC
Status 1.0: `FROZEN_SUPPORTED_SUBSET` — zamrożony dokładnie opisany zakres; reszta poza kontraktem 1.0. Gramatyka/wersja: kretai-1.0. Status języka nie nadaje uprawnień KCS ani prawa do działania w Production.Cel: pierwszy plik, podstawowa struktura, najprostszy działający przykład, najczęstszy błąd, sposób uruchomienia.
Narzędzia: kret = <SDK>\Compiler\kret.exe (SDK 1.0.0-rc.3+kret.local.3), kretui-host = <SDK>\UiHost\kretui-host.exe. {DATA}/{OUT} = nowe, puste katalogi.
1. Deklaracje modelu, narzędzi i agentów (KRETAI-B01-Declarations)
Projekt: ../../Examples/BASIC_Declarations/ · klasyfikacja VALIDATION_ONLY · Playground PUBLIC_STATIC
Kroki (katalog roboczy: katalog przykładu):
kret check . --json— w wyniku:"succeeded": truekret run . --policy host-policy.json --data {DATA}— w wyniku:zam
Wynik tej rundy: PASS — zob. EXPECTED_OUTPUT.txt.
Ćwiczenie i sprawdzenie wiedzy
W Declarations wskaż deklarację modelu oraz funkcję narzędzia KretS. Nie wpisuj klucza usług AI do źródeł.
Szkic nie jest wysyłany na serwer i znika po opuszczeniu lekcji. Przed wyjściem możesz go skopiować.Podpowiedzi
- KretAI (w SDK `KretAi`) deklaruje modele, narzędzia (funkcje KretS) i agentów. Zamrożone są deklaracje, walidacja oraz bramki uprawnień i polityki danych. **Wykonanie z prawdziwym modelem nie należy do kontraktu 1.0** (KretAI 1.1+, NOT_RUN). W Core KretAI jest DISABLED.
- Odczytaj ograniczenia i oczekiwane błędy z dostarczonego samouczka; check i run są oddzielnymi krokami.
Omówienie rozwiązania
Odpowiedź oprzyj na pokazanym kodzie i rozdziale źródłowym. KretAI opisuje modele, narzędzia i agentów. Kontrakt 1.0 obejmuje deklaracje, walidację i bramki danych. Pomyślny check nie oznacza odpowiedzi modelu. Prawdziwe wykonanie AI pozostaje poza kontraktem 1.0 i jest wyłączone w Core.
Podsumowanie i następny krok
KretAI opisuje modele, narzędzia i agentów. Kontrakt 1.0 obejmuje deklaracje, walidację i bramki danych. Pomyślny check nie oznacza odpowiedzi modelu. Prawdziwe wykonanie AI pozostaje poza kontraktem 1.0 i jest wyłączone w Core.
Zaloguj się na konto użytkownika, aby zapisywać postęp i zakładki. Konta obsługi mogą czytać bez zapisu postępu. Logowanie →