API Reference

Complete API Reference & Developer Cheat-Sheet

This document provides a technical specification of every class, interface, method, annotation, and configuration property in AgentGuard, accompanied by concrete code examples.

---

Table of Contents

1. Suite Facade: AgentGuardSuite
2. Suite Builder: AgentGuardSuite.Builder
3. PII Masker: PiiMasker
4. Reversible Context: PiiContext
5. Injection Firewall: PromptInjectionDetector
6. Budget Guard: BudgetGuard
7. Spring Boot @SecurePrompt Annotation
8. Spring Boot Configuration Properties

---

1. Suite Facade: AgentGuardSuite

Package: io.github.frodygr.agentguard.core.AgentGuardSuite

The central entry point coordinating prompt sanitization, threat detection, and response restoration.

.securePrompt(String rawPrompt)

• Signature: public GuardedPrompt securePrompt(String rawPrompt)
• Description: Pre-processes an outgoing prompt before transmission to any LLM. Validates token budget limits, detects prompt injection threats (throwing SecurityException if detected and blocking is active), and substitutes sensitive PII with reversible surrogate tokens.
• Parameters:
  • rawPrompt: Raw user prompt or query.
• Returns: An immutable GuardedPrompt record holding sanitizedPrompt, piiContext, and injectionAnalysis.
• Throws:
  • SecurityException if prompt injection attack signatures are detected.
  • BudgetLimitException if the estimated token count exceeds the configured threshold.

AgentGuardSuite suite = AgentGuardSuite.ofDefaults();
AgentGuardSuite.GuardedPrompt result = suite.securePrompt("My email is alice@corp.com");

System.out.println(result.sanitizedPrompt()); // "My email is [EMAIL_1]"

---

.restoreResponse(String llmResponse, PiiContext context)

• Signature: public String restoreResponse(String llmResponse, PiiContext context)
• Description: Post-processes the text generated by the LLM, swapping surrogate tokens back into their original sensitive values using the active in-memory PiiContext.
• Parameters:
  • llmResponse: Text received from the LLM provider.
  • context: PiiContext obtained from the matching securePrompt call.
• Returns: Natural text with real identity values restored.

String llmOutput = "Sent confirmation to [EMAIL_1].";
String finalUserText = suite.restoreResponse(llmOutput, result.piiContext());
// "Sent confirmation to alice@corp.com."

---

.validateToolIteration(int iteration)

• Signature: public void validateToolIteration(int iteration)
• Description: Enforces loop boundaries on autonomous agent tool-calling loops.
• Throws: BudgetLimitException if iteration exceeds maxToolIterations.

int currentStep = 1;
while (agentHasMoreSteps()) {
    suite.validateToolIteration(currentStep++);
    agent.executeNextStep();
}

---

2. Suite Builder: AgentGuardSuite.Builder

Constructed via AgentGuardSuite.builder().

Method	Parameter Type	Default	Description
piiMasking(boolean)	boolean	true	Enables or disables reversible PII masking.
injectionDetection(boolean)	boolean	true	Enables in-memory prompt injection heuristic analysis.
blockOnInjection(boolean)	boolean	true	When true, throws SecurityException on HIGH or CRITICAL risk.
maxInputTokens(int)	int	4096	Max allowable input tokens per prompt.
maxToolIterations(int)	int	10	Max autonomous agent recursion loop count.
maxSessionTokens(int)	int	50000	Max accumulated tokens before tripping budget circuit breaker.

AgentGuardSuite customSuite = AgentGuardSuite.builder()
    .piiMasking(true)
    .injectionDetection(true)
    .blockOnInjection(true)
    .maxInputTokens(2048)
    .maxToolIterations(5)
    .build();

---

3. PII Masker: PiiMasker

Package: io.github.frodygr.agentguard.core.pii.PiiMasker

Stand-alone anonymization engine supporting seven sensitive categories:

Category	Identifier Pattern	Validation Method
Email	RFC 5322 regex	Standard format check
Credit Card	13-19 digit card formats	Luhn Checksum Algorithm (ISO/IEC 7812)
IBAN	European Bank Account Numbers	ISO 13616 pattern
Tax ID / DNI / SSN	Spanish DNI/NIE and US SSN	Check digit & structure
Phone Number	International (+34, +1, etc.)	9+ digit length validation
Secrets / JWTs	eyJ... Bearer tokens	JWT structure validation
IPv4 Address	Dotted quad addresses	Validates octets 0-255 (excludes localhost)

PiiMasker masker = new PiiMasker();
PiiMasker.MaskResult maskResult = masker.mask("Transfer funds to ES9121000418450200051332");

---

4. Reversible Context: PiiContext

Package: io.github.frodygr.agentguard.core.pii.PiiContext

Thread-safe bidirectional store keeping token substitutions in memory:

• getOrCreateToken(String original, PiiType type): Allocates or returns surrogate token ([TYPE_N]).
• resolveOriginal(String token): Looks up original sensitive string.
• hasMaskedEntities(): boolean indicating if any items were anonymized.
• totalMaskedCount(): Number of unique sensitive values captured.
• getMappings(): Returns unmodifiable map of token -> original.

---

5. Injection Firewall: PromptInjectionDetector

Package: io.github.frodygr.agentguard.core.injection.PromptInjectionDetector

PromptInjectionDetector detector = new PromptInjectionDetector();
InjectionResult result = detector.analyze(userPrompt);

if (!result.safe()) {
    System.err.println("Threat Level: " + result.risk());
    System.err.println("Patterns: " + result.detectedPatterns());
}

---

6. Budget Guard: BudgetGuard

Package: io.github.frodygr.agentguard.core.budget.BudgetGuard

Enforces financial boundaries and prevents denial-of-wallet:

BudgetGuard guard = new BudgetGuard(4096, 8, 25000);
guard.validateInputPrompt(longPrompt); // Throws BudgetLimitException if oversized

---

7. Spring Boot @SecurePrompt Annotation

Package: io.github.frodygr.agentguard.spring.annotation.SecurePrompt

Place on Spring @Service or @Component methods:

@Service
public class ChatService {

    @SecurePrompt(maskPii = true, detectInjection = true, blockOnThreat = true)
    public String askAi(String prompt) {
        // 'prompt' is sanitized before method begins
        return llmClient.chat(prompt);
    }
}

---

8. Spring Boot Configuration Properties

Configure via application.yml:

agentguard:
  enabled: true
  pii-masking: true
  injection-detection: true
  block-on-injection: true
  max-input-tokens: 4096
  max-tool-iterations: 10
  max-session-tokens: 50000