🤖 Agents System

Locentra OS includes a fully integrated agent layer—self-optimizing background logic designed to monitor prompt quality, trigger training, adapt system behavior, and rewrite input intelligently.

Agents are modular and live at:

backend/agents/

They can run synchronously with inference or as asynchronous background processes.

---

🧬 Agent Modules Overview

Agent Name	Role
AutoTrainer	Detect low-quality responses, retrain automatically
FeedbackLoop	Monitor user behavior + corrections → flag for training
PromptOptimizer	Rewrite noisy or ambiguous input before inference

All agents are:

• Plugged directly into the LLM lifecycle

• Configurable

• Loggable

• Extendable with custom logic

---

📊 System Flow (High-Level)

flowchart TD
    A[New Prompt Received] --> B[Evaluate Output Quality]
    B -->|Good| C[Store in Vector Memory]
    B -->|Low| D[AutoTrainer Retrain Trigger]
    D --> E[Feedback Loop Captures Session]
    E --> F[Update Memory + Fine-Tune Model]
    F --> G[System Self-Upgrades]

---

🔁 AutoTrainer

Core logic for self-correction.

• Hooks into POST /api/llm/query

• Scores model output via utils/eval_metrics.py

• If the response score falls below threshold:

  • Stores prompt in vector memory

  • Pushes to models/trainer.py for live fine-tuning

  • Flags prompt metadata for later analysis

You can control training thresholds via:

# core/config.py
DEFAULT_AUTO_TRAIN_THRESHOLD = 10

The model fine-tunes itself—based on how well it performs.

---

🧠 FeedbackLoop

Monitors indirect indicators of model failure:

• ⏱ Response delay (user waits or edits)

• ✏️ Manual prompt rewrites

• 🔁 Repeated queries on the same topic

If the pattern matches “low confidence” behavior, the agent:

• Embeds the prompt semantically

• Stores it in persistent memory

• Queues retraining

• Flags it for potential prompt optimization

---

📝 PromptOptimizer

Some prompts just suck. This agent rewrites them before inference.

Functionality:

• Splits compound queries

• Normalizes slang, abbreviations

• Restructures the question to be more LLM-friendly

• Preserves semantic intent while improving clarity

Example:

Prompt: "what’s up with MEV?"
↓
Optimized: "Explain MEV (Maximal Extractable Value) in Ethereum."

Powered by:

• Zero-shot classification

• Regex-based refactoring

• Embedding distance for ambiguity detection

---

🔄 Example: Live Agent Loop

1. User sends: "wtf is zk-snarks vs starks?"

2. Model gives weak/unclear response

3. AutoTrainer flags score < threshold

4. FeedbackLoop captures session metadata

5. PromptOptimizer rewrites prompt:

   "Compare zk-SNARKs and zk-STARKs in zero-knowledge cryptography."

6. Fine-tuning is queued

7. Memory is updated with embedded vector

The system adapts. No user or dev needed.

---

📦 Build Your Own Agents

Create a custom agent by extending the base class:

class BaseAgent:
    def run(self, prompt: str, response: str) -> dict:
        # your custom logic here
        return {"action": "log", "priority": "medium"}

Register it in:

# core/registry.py
registry.register("my-agent", MyCustomAgent())

Agents can:

• Write logs

• Trigger webhooks

• Modify memory

• Queue training jobs

• Even call other agents

They run async, and can be chained, filtered, or scheduled.

---

🧠 Why This Matters

With agents:

• Your model gets better the more it’s used

• No manual fine-tuning needed

• Prompts evolve

• Output quality stabilizes

• System becomes self-sustaining