Page cover

🧩 Extending the System

This isn’t a black box. This is infrastructure you can fork, rewire, and evolve.

Every subsystem in the stack—memory, inference, agents, analytics—is designed to be plug-and-play. If you're building custom tooling or domain-specific LLM systems, this guide shows you exactly where to hook in.


🤖 Build Your Own Agent

Agents are autonomous workers that monitor model behavior, inject logic, or retrain automatically. You can create new ones in seconds:

  1. Create a new file in backend/agents/, e.g. my_custom_agent.py

  2. Implement the interface:

# backend/agents/my_custom_agent.py
class MyCustomAgent:
    def run(self, prompt: str, response: str) -> dict:
        # Insert evaluation, rewriting, scoring, etc.
        return {
            "log": "custom logic executed",
            "action": "flagged",
            "status": "ok"
        }
  1. Register your agent in core/registry.py

  2. Trigger it from:

    • CLI (cli/agent_runner.py)

    • Another agent

    • UI button or /api/agent/trigger

Agents have access to:

  • Memory

  • Logs

  • Model output

  • Full prompt lifecycle


🧠 Swap or Extend Your Model

Quick swaps:

# .env
MODEL_NAME=tiiuae/falcon-rw-1b

Advanced extensions:

Area
File
Purpose

Adapter Logic

models/adapter.py

Add support for LoRA, quantization, model-specific config

Tokenization

data/tokenizer.py

Load custom tokenizers or apply task-specific preprocessing

Training Control

models/trainer.py

Adjust parameters based on model type or mode (batch, streaming, prompt injection)


⚙️ New API Routes

The API layer is modular and based on FastAPI. You can easily extend it by adding a new route file:

# backend/api/routes/agent_control.py
from fastapi import APIRouter
router = APIRouter()

@router.post("/agent/trigger")
def trigger_agent(agent_id: str):
    # Call your agent via registry or system signal
    return {"status": "launched"}

Then plug it into api/server.py:

from api.routes.agent_control import router as agent_router
app.include_router(agent_router)

🔍 Custom Memory Logic

Want smarter recall, tagging, or retrieval?

  • Switch distance function: Edit data/vectorizer.py and replace cosine with dot, L2, or hybrid.

  • Add filters: Inject tag filtering or session context into the vector lookup logic.

  • Scale up: Swap PostgreSQL for FAISS or Weaviate to support ANN-based search at scale.

  • Track accuracy: Add logging hooks to log whether vector hits actually improved model outputs.


🛠 CLI Tooling (Plug & Extend)

Every CLI script in cli/ has access to core subsystems.

Example custom CLI tool:

# backend/cli/summarize.py
from backend.core.registry import registry

def main():
    model = registry.get("model")
    response = model("Summarize today’s market news")
    print(response)

if __name__ == "__main__":
    main()

Drop-in tools have access to:

  • Model

  • Logger

  • Vector Memory

  • Agents

  • Config / .env

Wrap your tools with bash or run in cron for automation.


🌍 Good First Extensions

Idea
Description

twitter_agent.py

Agent that scrapes X posts and retrains based on $TOKEN mentions

vector_cleaner.py

CLI script to prune semantic memory entries older than X days

live_model_switch

Add a toggle in UI to hot-swap between Falcon and Mistral

notion_sync.py

Sync LLM outputs or prompts to your personal knowledge repo

embedding_viewer.py

Web UI module for inspecting memory vectors visually


🔐 Contributing or Forking

Locentra OS is open-source under the MIT License.

Before opening a PR:

  • Stick to PEP8

  • Write tests under tests/

  • Document new flags or config keys

  • Describe exactly what behavior is added or changed

# Workflow
git clone https://github.com/locentra/OS
git checkout -b feat/my-agent
git commit -m "add my agent"

Submit your PR. We review every one.

Last updated