PTENES
MODULE 1.2

🏗 Overall Architecture

How the 5 components connect, the complete flow of a message from Telegram to the response, and the workspace system that configures everything.

6
Topics
60
Minutes
Basic
Level
Diagram
Type
1

🔄 The 5 Core Components

INTELECTO has exactly 5 distinct responsibilities. This division isn't arbitrary—each component can be replaced, tested, and evolved independently of the others. That's the secret to keeping the system manageable.

🧩 The 5 Components

🤖
Agent

The brain. Receives messages, builds context, decides whether to use tools or respond directly, and orchestrates everything.

🔮
Providers

Access to LLMs. OpenRouter, Ollama, direct API. Any implementation of BaseProvider will work.

📡
Channels

How the user communicates. Telegram, WhatsApp, Discord, CLI. Implement BaseChannel.

🧠
Memory

Context persistence. SQLite FTS5 with BM25 semantic search and automatic deduplication.

🔧
Tools

Real-world actions. Google Calendar, GitHub, browser, shell. Implement BaseTool.

2

📨 Complete Message Flow

Each message follows a precise path. Understanding this flow is essential to knowing where to intervene when something fails and where to add new features.

📊 Flow Diagram

U
User types a message in Telegram
↓
CH
Channel.receive() → normalizes to internal format
↓
S
Safety.check() → validates against the blocklist and injection
↓
AG
Agent.loop() → builds context with workspace + memory
↓
PR
Provider.chat() → sends to LLM, receives response
↓ (if tool_call)
TL
Tool.execute() → performs an action, returns a result
↓ (up to max 5 rounds)
ME
Memory.store() → persists relevant facts
↓
CH
Channel.send() → sends response to Telegram
↓
U
User receives the response

💡 Practical Tip

To debug, add logs at every step of the flow. Python logging with different levels (DEBUG for Channel, INFO for Agent, WARNING for Safety) lets you pinpoint exactly where the problem occurs.

3

🔁 The Agent Loop — Max 5 Rounds

O loop.py is the heart of INTELECTO. It implements the ReAct pattern (Reason + Act): the AI thinks, decides to use a tool, receives the result, thinks again, and so on—until it reaches a final answer or hits the 5-round limit.

🔄 The ReAct Cycle

R
Reason

LLM analyzes the message + context and decides what to do

↓
A
Act (Take Action)

If you decide to use a tool → call tool.execute() with the parameters

↓
O
Observe (Observe)

Tool result enters context → back to Reason

↓ (loop until response or max 5)
F
Final

LLM generates a natural language response for the user

⚠ Why a 5-Round Limit?

Without a limit, a bug in the AI logic can cause an infinite loop — costing hundreds of dollars in tokens. The limit of 5 is the circuit breaker that protects your billing. For complex tasks, adjust the limit carefully and always monitor it.

4

📁 The Workspace — Configuration in Markdown

The directory workspace/ is where you define what your Jarvis is. Three Markdown files that are read and injected into every system prompt. Changing the AI’s behavior doesn’t require changing code—just editing these files.

🧬 SOUL.md

The AI's personality: name, tone of voice, values, communication style, ethical limitations. Defines who Jarvis is.

You are Atlas, a direct, technical personal assistant. You prefer Python. You aren't afraid to disagree.

📋 AGENTS.md

Behavior rules: what to do, what never to do, how to prioritize tasks, when to ask for confirmation.

NEVER run rm -rf without confirmation. ALWAYS check whether files exist before overwriting them.

🧠 MEMORY.md

Bootstrap facts: information the AI needs to know from the first conversation without having to be taught.

User: João Silva. Stack: Python, FastAPI. Company: Acme Corp. Time zone: America/Sao_Paulo.

💡 Configuration as Code

Workspace files are "code" in the sense that they control system behavior. Version them with git, back them up, and treat changes to them with the same care as code changes.

5

🧩 Interface Contracts

The secret to INTELECTO’s extensibility is the interface contracts. Each component type has an abstract base class with required methods. If you follow the contract, your component works with everything else automatically.

📋 The 3 Main Contracts

BaseProviderproviders/base.py
async def chat(messages: list[dict], **kwargs) -> str: ...

The only required method. Any LLM that implements this works with the Agent.

BaseChannelchannels/base.py
async def start() → None
async def send(user_id, msg) → None
async def stop() → None

3 methods. Telegram, WhatsApp, CLI — all implement these 3.

BaseTooltools/base.py
name: str
description: str
parameters: dict # JSON Schema
async def execute(**kwargs) → str

The description + parameters are sent to the LLM so it knows how to use the tool.

6

🗄 Persistence in ~/.intelecto/

Everything INTELECTO persists is stored in ~/.intelecto/. Three critical files you need to know, back up, and never accidentally delete.

DB

memory.db

SQLite database with FTS5 enabled. Stores facts (category: fact/conversation/solution), conversation history, and results of previous searches. BM25 for relevance ranking.

🔐

.secrets

API keys encrypted with Fernet. The encryption key is derived from the hardware UUID using PBKDF2. The file can only be decrypted on the same machine.

📋

audit.log

Record of all actions: who requested them, what was executed, when, and with what result. Immutable by design — each line is append-only.

✅ Module 1.2 Summary

✓
5 Components — Agent, Providers, Channels, Memory, Tools with strictly separated responsibilities
✓
Complete Workflow — 8 stages from incoming message to sent response, each auditable
✓
ReAct Loop — Reason-Act-Observe with a 5-round limit as a cost circuit breaker
✓
Workspace — SOUL.md (personality), AGENTS.md (rules), MEMORY.md (bootstrap facts)
✓
Contracts — BaseProvider, BaseChannel, BaseTool ensure any implementation is plug-and-play
✓
Persistence — memory.db (SQLite FTS5), .secrets (Fernet), audit.log (append-only)

Next Module:

1.3 — Environment Setup: from scratch to Jarvis running on Telegram

← Module 1.1 Next: Module 1.3 →