pacod-ap

Защо съществува

pacod-ap е създаден за агенти, чиято задача е да дават верни отговори с посочени източници в една област — там, където грешна цена, ставка или срок е по-лошо от липсата на отговор. Три правила го определят:

• Всяко число идва от структуриран източник на истина, никога от паметта на модела.
• Всяко твърдение посочва източник — пасаж от базата знания, source_url на факт или уеб страница от разрешения списък.
• Администраторите коригират агента без ново внедряване — моделите, промптовете, директивите, уеб търсенето и кеширането се прилагат още от следващия ход.

Едно внедряване, много агенти

Агентът е профил: един ред в таблицата profiles плюс всичко, което принадлежи към него. Платформата идва с два:

• starter — универсален шаблон: малко измислено бюро за поддръжка („Nimbus Notes“), което използва базата знания и инструментите за справочни факти. Копирайте го, за да започнете свой агент.
• taxes — разширен пример за българските данъци и счетоводство, със собствени промптове, факти, корпус от закони и списък с разрешени източници за уеб търсене (make seed-example PROFILE=taxes). Корпусът му е там, за да покаже извличане върху реален масив от законодателство; той не се поддържа актуален и нищо, което агентът казва, не е правен или данъчен съвет.

Изолацията между агентите е граница на сигурността: всеки ред, принадлежащ на агент, носи profile_id, а всеки агент има собствени колекции в Qdrant.

Потребителите виждат само агентите, които са им възложени; администраторите работят глобално или в рамките на един агент. Квотите се броят за потребител общо за всички агенти. Агентите говорят български и английски; трети език е промяна в кода, а не в конфигурацията.

Компонентите

Всеки контейнер има едно име в общата Docker мрежа pacod-net: ap-* за собствените услуги на pacod-ap и pacod-* за компонентите, които той споделя с другите проекти на pacod. Собственият чат на приложението е единственият чат интерфейс.

Как протича един ход в чата

Проверките се изпълняват, преди нещо да започне да се стриймва, така че отказът е нормален HTTP статус, а не грешка по средата на потока:

1. Удостоверяване — токенът от pacod-id се проверява; приключила сесия или деактивиран акаунт се отказват.
2. Агент — заявеният агент трябва да е възложен на потребителя; ако не е посочен такъв, потребителят получава единствения си агент, никога предположение.
3. Език — разпознава се при всеки ход и се сверява с езиците на агента.
4. Квота — лимитът за токени на потребител в шлюза, плюс квота за заявки и ограничение на честотата в Redis.
5. Тема — филтър за незаконни фрази, след това евтин класификатор: въпрос извън темата се отклонява, а неясен въпрос получава обратно уточняващи въпроси.

След това се отваря потокът от server-sent events. Първи въпрос може да получи отговор от семантичния кеш на отговорите на агента; иначе се изпълнява малък граф на LangGraph:

• plan — плановикът връща JSON: кои инструменти да се извикат и дали въпросът е сложен.
• execute tools — всички планирани извиквания вървят паралелно: kb_search, get_fact / list_facts, web_search.
• synthesize — основният модел стриймва отговора от този контекст, с разширено мислене при сложните ходове, а накрая предлага следващи въпроси.

По-старите ходове се сгъват в обобщение, което се обновява, така че дълъг разговор не изпраща отново целия си запис. OpenAI-съвместимият /v1 минава през същите проверки и същия агент (без кеша на отговорите), като всеки агент се появява в него като модел. Той не е изложен през публичната точка; клиентите го достигат във вътрешната мрежа.

Знания, факти и уеб

Плановикът избира източника според вида на твърдението:

• Числата, цените, ставките, лимитите и датите идват само от справочните факти — типизирани редове в PostgreSQL, предоставяни чрез MCP. Кодът, а не моделът, задава агента и референтната година при всяко извикване, така че плановикът не може да достигне фактите на друг агент.
• Обясненията идват от базата знания: плътно търсене в Qdrant, пренареждане с cross-encoder и разширяване на малките откъси до родителския им пасаж. Отделна колекция с по-ниско тегло, кураторската, съдържа бележки, написани или одобрени от администратори.
• Актуалната информация идва от уеб търсенето, ограничено до разрешен списък с домейни за всеки агент.

Фактът има една обща форма, така че цените на бюро за поддръжка и сроковете на данъчен агент живеят в една таблица — нова област е данни, а не схема:

{"fact_key": "plan_price_monthly", "variant": "plus", "category": "pricing",
 "legal_year": 2026, "value_type": "money", "value_num": 6, "unit": "EUR",
 "label_en": "Plus plan — price per user per month",
 "source_url": "https://acme.example/pricing"}

Незадължителен верификатор, изключен по подразбиране, проверява числата в отговора спрямо резултатите от инструментите. Дообучението на извличането по обратната връзка от потребителите се пуска ръчно; нищо не го планира.

Цикълът на подобрение

Всеки агент се подобрява от собствения си трафик. Работен процес преглежда последните разговори на агента, с маскирани лични данни, всеки ден или при поискване. Той оценява всеки отговор спрямо това, което асистентът действително е прочел — дословния контекст и действащите директиви, — така че присъдата не е догадка.

Сходните находки се групират в клъстери, а клъстерът е задачата, по която работи проверяващият. Нищо не достига до кураторската колекция, докато администратор не го одобри — освен ако флагът за автоматично добавяне (изключен по подразбиране) е включен и строгите проверки минат; твърдение, което източниците опровергават, никога не се добавя автоматично.

Сигурност и изолация

• Идентичността е делегирана. Акаунтите, паролите, сесиите и ролите живеят в pacod-id. API-то следи потока от събития на pacod-id, така че приключила сесия или деактивиран акаунт се отказват до секунди. Промените по акаунти и роли се правят в pacod-id от името на администратора, който ги извършва: само суперпотребител може да създаде суперпотребител, а последният администратор не може да бъде премахнат.
• Агентите са оградени в кода. Агентът се оторизира преди каквато и да е работа, аргументите на инструментите, които засягат данни на агента, се задават от кода, /v1/models показва само агентите на извикващия, а всеки кеш ключ на агент съдържа неговия идентификатор.
• Тайните си стоят на мястото. Ключовете на LLM доставчиците са само в шлюза. Ключовете за уеб търсене са криптирани в базата данни. Файловете с тайни се генерират, с права 0600 и в gitignore, а вътрешните услуги отказват достъп, ако споделеният им токен не е зададен.
• Безопасност на промптовете. Отказът от незаконни заявки стои най-горе в промптовете на плановика и синтезатора и е над директивите на администратора; текстът на администратори и потребители винаги се вмъква като стойност, никога като шаблон.

Работа и поддръжка

Три стека на Docker Compose се стартират поред — make up-all го прави:

1. Приложението — два compose файла. Файлът на приложението съдържа собствените услуги на pacod-ap, Redis, PgBouncer и услугата за ембединги; самостоятелният (standalone) файл съдържа неговите копия на споделените компоненти: Caddy, PostgreSQL, Qdrant и pacod-id (локално и mailpit).
2. Шлюзът — файлът на приложението на pacod-gw от съседно копие на хранилището. Той влиза през същия pacod-id, пази базата си данни в същия PostgreSQL и се обслужва от същия Caddy.
3. Мониторингът — Prometheus, Alertmanager и Grafana; по избор, като make up-all го стартира, когато съществува monitoring/.env.

Тъй като споделените компоненти са в отделен файл, pacod-demo може да зареди файла на приложението на pacod-ap заедно с другите проекти на pacod и да пусне по един екземпляр от всеки споделен компонент; резултатът работи на demo.pacod.io. На един хост може да работи само едно копие на всеки споделен компонент, затова самостоятелният pacod-ap не може да работи редом с друг стек на pacod.

Локално шлюзът отговаря чрез своите симулирани доставчици: предварително зададени отговори, без разходи.

Конфигурацията се чете от кеш в Redis, после от ред в app_settings с ключ по агент, после от стойността по подразбиране от средата; при срив се използват стойностите по подразбиране, вместо ходът да бъде блокиран.

LLM извикванията се приписват на потребител, сесия, ход, агент и цел, така че страниците за използване и разходи в конзолата четат отчетите на шлюза, вместо да водят собствен регистър. Извикване, изтекло по време, никога не се повтаря — доставчикът го таксува така или иначе — затова потребителят пита отново.

Наблюдаемост — одитен ред за всяка заявка, Debug Console със стъпки при поискване, структурирани журнали и метрики за Prometheus от всяка услуга, с табла в Grafana за приложението, инфраструктурата, уеб трафика, обхождащите ботове и използването, плюс собствените табла на шлюза.

Резервни копия — make backup записва един архив с дъмповете на базите данни, снимките на Qdrant, конфигурацията и тайните; make restore го възстановява.

Изградете свой агент

Има два пътя:

• В конзолата — суперпотребител създава агент от страницата Profiles или във визуалния редактор на агенти. Новият агент започва в dev; тествате го там и го публикувате, когато е готов. Версиите само се добавят, така че публикуването и връщането назад просто преместват указател. AI асистент пише чернови на промптове и друг текст, но никога не променя самия граф.
• Като код — ProfileSpec в pacod-api/scripts/profiles/<id>.py (тема, езици, промени на промптове и настройки) и данни в pacod-api/data/profiles/<id>/: справочни факти, корпус и еталонен набор от въпроси. make seed-example PROFILE=<id> го инсталира.

След това разговаряйте с него, проверете Debug Console и следата на хода в шлюза и пуснете make eval срещу еталонния набор. Оттам нататък поема цикълът на подобрение.

Прочетете още

• Runbook — стекове, тайни, реални доставчици, резервни копия, отстраняване на проблеми.
• LLM шлюзът — приписване, повторни опити, квоти, използване.
• Изградете свой агент — пълното ръководство.
• Архитектура на API и архитектура на UI — дизайнът в дълбочина.