@adonis-agora/agent 0.34.1 → 0.36.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # @adonis-agora/agent
 
+## 0.36.0
+
+### Minor Changes
+
+- [#191](https://github.com/DavideCarvalho/adonis-agora-agent/pull/191) [`c70587d`](https://github.com/DavideCarvalho/adonis-agora-agent/commit/c70587d52cb00235203539d5b4868d5055789788) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - `PgLexicalVectorStore.searchText` (and `retrievers.pgvector({ fullText })`): natural-language questions are searched by their meaningful terms. The question's stop words are dropped (new `fullText.stopWords`, default `DEFAULT_STOP_WORDS`: English, Portuguese and Spanish, only the language(s) the question is written in; `false` keeps every word) and rows holding any remaining term are ranked by the sum of the matched terms' IDF among the matching rows (BM25 without term frequencies), `ts_rank_cd` breaking ties. Before, a question had to match every word and then fell back to any word including stop words, ranked by `ts_rank_cd`, so rows dense in "the/of/which" won: in a 149-question benchmark over 12k chunks this took the keyword-only evidence hit rate from 18% to 75% (hybrid 69% to 80%), and it is faster. Quoted phrases and `-word` still go through `websearch_to_tsquery` as written first; `anyTermFallback: false` keeps the old every-word-only behavior. New exports: `keywordTerms`, `hasSearchSyntax`, `anyTermTsquery`, `DEFAULT_STOP_WORDS`.
+
+## 0.35.0
+
+### Minor Changes
+
+- [#186](https://github.com/DavideCarvalho/adonis-agora-agent/pull/186) [`e7d75e1`](https://github.com/DavideCarvalho/adonis-agora-agent/commit/e7d75e1f1e931d5071de94d5f9d207eb83c76c42) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - Guardrails, and processors you can actually configure
+  
+  - **`@adonis-agora/agent/guardrails`** — PII (Luhn-validated cards, CPF/CNPJ, SSN, IBAN, phones, emails, IPv4), secret (provider key formats, JWT, PEM, entropy-gated assignments), prompt-injection (EN / PT-BR / ES, hidden Unicode, encoded payloads) and tool-poisoning detectors; a rule engine with `allow`/`log`/`redact`/`approve`/`block`, fail modes and reversible redaction (`Vault`); and `createGuardrails(options)`, which runs it on the loop's processor seams — `guardrails.input` / `guardrails.output`, `wrapTool` for tool arguments, `screenTool` for tool definitions — with per-call rule resolution (per tenant) and an audit hook. A port of `@dudousxd/nestjs-agent-core/guardrails`.
+  - **`inputProcessors` / `outputProcessors` in `config/agent.ts`.** The loop has taken processors since they were ported, but nothing between the config and the loop carried them, so an app using the provider could not register one. They now reach every agent's turn, inline and durable.
+  - **`mcpServers[].screen`** — inspect each listed tool definition before it is imported, and skip the ones it refuses (a screen that throws skips the tool too).
+
+- [#185](https://github.com/DavideCarvalho/adonis-agora-agent/pull/185) [`2f4fc8c`](https://github.com/DavideCarvalho/adonis-agora-agent/commit/2f4fc8cf865e1b310280a40e2df91ed7f72caf93) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - First-party HTTP embedding and rerank adapters
+  
+  New `openAiEmbeddings` — an `EmbeddingProvider` over any OpenAI-compatible `/v1/embeddings` (OpenAI, gateways, TEI, Ollama, vLLM), with `embedWithUsage` so embedding spend reaches the ledger and quota — and `HttpReranker`, a `Reranker` over Cohere/Jina/Voyage/TEI-style `/rerank`. Both are dependency-free and throw `HttpModelError`. `@adonis-agora/agent/testing` adds `hashedEmbeddings(dimensions)`, a deterministic Unicode-aware hashed embedder.
+
+- [#184](https://github.com/DavideCarvalho/adonis-agora-agent/pull/184) [`1b8cc02`](https://github.com/DavideCarvalho/adonis-agora-agent/commit/1b8cc02fc447841e01bd58219e5c674413b46cc1) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - pgvector: batched upserts, full-text hybrid search, mixed dimensions
+  
+  `PgVectorStore` now upserts in multi-row `INSERT … ON CONFLICT` statements (`upsertBatchSize`, default 100; duplicate ids in one call keep the last), and gains opt-in `nullableEmbeddings` (`embedding: []` → `NULL`), mixed-dimension tables (`dimension: [768, 1536]`, one partial HNSW index per width, searches compare like with like), and pgvector ≥ 0.8 `iterativeScan` / `efSearch` (`SET LOCAL` inside a Lucid transaction, skipped on older pgvector). New `PgLexicalVectorStore` (Postgres full-text `searchText`), `LexicalVectorStore` / `isLexicalVectorStore` and `LexicalRetriever`; `retrievers.pgvector({ fullText: {} })` returns a `HybridRetriever` of both legs. `HybridRetriever` gains `retrieveWithUsage`, so embedding spend from its legs still reaches the ledger. Everything is off by default.
+
 ## 0.34.1
 
 ### Patch Changes

package/README.md

@@ -152,6 +152,40 @@ export const executeSql = dataTool({
 })
 ```
 
+### Guardrails — PII, secrets, prompt injection, tool poisoning
+
+`@adonis-agora/agent/guardrails` puts detectors and a rule engine on the loop's processor seams,
+which `config/agent.ts` now takes as `inputProcessors` / `outputProcessors`:
+
+```ts
+// config/agent.ts
+import { createGuardrails } from '@adonis-agora/agent/guardrails'
+
+const guardrails = createGuardrails({
+  pii: 'redact',                 // reversible: the model sees [EMAIL_1], the reader the address
+  secrets: 'block',
+  injection: { threshold: 0.6 }, // the prompt and every tool result; default action: block
+  toolPoisoning: true,           // guardrails.screenTool, for `mcpServers[].screen`
+  rules: (ctx) => rulesForTenant(ctx.actor?.tenantRef), // more rules, resolved per scan
+  onEvent: (event) => audit(event),                     // hits carry fingerprints, never values
+})
+
+export default defineConfig({
+  model: () => aiSdkModel(openai('gpt-4o-mini')),
+  inputProcessors: [guardrails.input],
+  outputProcessors: [guardrails.output],
+  mcpServers: [{ name: 'docs', transport: { type: 'http', url }, screen: (t) => guardrails.screenTool(t) }],
+})
+```
+
+A blocked prompt fails the run (`ProcessorFailedError` caused by a `GuardrailBlockedError`); a
+blocked tool result is withheld and the turn goes on; a blocked answer or tool call is an
+`OutputRejectedError`. `guardrails.wrapTool(name, handler)` restores placeholders into a tool's
+arguments and runs the `tool_args` rules on them. The output processor declares `incremental`, so the
+answer keeps streaming. The detectors (`detectPii` with Luhn/CPF/CNPJ/IBAN checks, `detectSecrets`,
+`scoreInjection`, `scoreToolText`) and `scan` work on their own. Same code as
+`@dudousxd/nestjs-agent-core/guardrails`, which also carries the raw OpenAI/Anthropic stream guard.
+
 ### Framework-agnostic core (no AdonisJS)
 
 `runAgentLoop(deps, input, hooks)` is the shared turn body both the in-process (`InlineAgentRunner`)