🧠 INTELECTO Fundamentals

Frameworks like LangChain and CrewAI abstract everything, but add unnecessary layers of complexity that make debugging and customization a nightmare.

Understanding the trade-offs lets you consciously choose when to use a framework and when to build from scratch — a rare skill in the market.

Abstraction tax, vendor lock-in, zero-dependency philosophy, full control of the code.

INTELECTO is organized like a grocery store: you go to each aisle (security, memory, channels...) and pick only what you need for your assistant.

This mental model prevents over-engineering. You don't install what you won't use, keeping the system lightweight, auditable, and easy to maintain.

8 functional corridors, modular composition, feature flags, framework ingredients.

An objective analysis of the differences: LangChain has 200+ dependencies, while CrewAI forces a rigid agent model. INTELECTO has zero required dependencies beyond Python.

Being able to technically defend your choice is essential for teams and clients. You need the numbers and arguments.

Package size, startup time, debugging latency, maintenance cost, learning curve.

Jarvis knows its creator, remembers previous conversations, acts proactively, and performs tasks in the real world. A generic chatbot only answers questions.

Sets the right level of ambition. You're building something that will grow with you, not a throwaway demo.

Persistent identity, long-term memory, real-world action, deep personalization.

Each file has a clear responsibility: context.py builds the system prompt, loop.py manages the reasoning cycle, secrets.py protects credentials.

Knowing the map before diving into the code saves hours of aimless orientation. Every change happens in the right place.

context.py, loop.py, secrets.py, safety.py, store.py, providers/base.py, channels/base.py, tools/base.py.

With mature and stable LLM APIs, the abstraction cost of frameworks outweighs the benefits for serious projects. Pure Python + clear contracts is enough.

The market is saturated with developers who only know how to use wrappers. Those who understand the fundamentals have a real competitive advantage.

API maturity, abstraction cost, competitive advantage, interface contracts, long-term maintenance.

INTELECTO has exactly 5 responsibilities: the central agent that thinks, the providers that access LLMs, the channels that receive messages, the memory that persists context, and the tools that act in the world.

Each component has a clear boundary. Knowing where one ends and another begins is what lets you add features without breaking the system.

Separation of concerns, interface contracts, dependency injection, modular composition.

User → Telegram → Channel.receive() → Agent.loop() → Memory.search() → Provider.chat() → Tool.execute() → Memory.store() → Channel.send() → User. Each arrow is a function call with a defined contract.

Visualizing the complete flow makes it possible to identify where to debug when something fails and where to optimize when it's slow.

Processing pipeline, async/await, cascading error handling, observability.

loop.py implements a reasoning cycle: receives a message → thinks → decides whether to use a tool or respond → if it used a tool, thinks again with the result → up to 5 iterations for safety.

The 5-round limit prevents infinite loops and runaway costs. Understanding the cycle lets you adjust reasoning depth for each use case.

ReAct pattern, tool calling, max iterations, cost per round, circuit breaker for loops.

The workspace/ directory contains Markdown files that define the personality (SOUL.md), behavior rules (AGENTS.md), and bootstrap facts (MEMORY.md) injected into every system prompt.

Every AI customization starts here. Changing Jarvis doesn’t require changing code — only the workspace files.

Configuration as code, system prompt construction, context injection, SOUL.md as identity.

Each extension category has an abstract base class with required methods. BaseProvider requires async chat(). BaseChannel requires start(), send(), stop(). BaseTool requires name, description, execute().

Contracts ensure that any implementation works with the rest of the system automatically. It's like a standardized plug — any device that follows the standard works in the outlet.

Abstract base class, duck typing, protocol pattern, plug-and-play architecture.

Three critical files in ~/.intelecto/: memory.db (SQLite database with history and facts), .secrets (keys encrypted with Fernet + hardware UUID), and audit.log (record of all actions).

Understanding where the data lives is essential for backup, migration, and troubleshooting. You should never lose your Jarvis's memory by accident.

Home directory pattern, SQLite portability, encrypted secrets, audit trail, backup strategy.

Python 3.11+ is required. Dependencies are minimal: httpx for async HTTP, python-telegram-bot for the channel, cryptography for Fernet. No LangChain, no CrewAI.

Knowing the actual dependencies lets you audit what’s installed and understand why each package exists in the project.

venv, minimal requirements.txt, Python 3.11 features, native async.

OpenRouter is an LLM proxy that provides access to GPT-4, Claude, Mistral, Llama, and 100+ other models with a single API key and unified billing.

Avoids vendor lock-in with a specific provider. If Anthropic raises its prices, you can switch to Mistral in 10 seconds by changing an environment variable.

API key management, model routing, cost tracking, fallback strategy, model by task.

The .env file defines OPENROUTER_API_KEY, TELEGRAM_BOT_TOKEN, MODEL_NAME, and other parameters without hard-coding them in the code. The .env file NEVER goes into git.

Separating configuration from code is a fundamental security practice. Keys in code are the number one cause of leaks in public repositories.

12-factor app, .gitignore, python-dotenv, environment variables, secrets management.

The setup.py script asks interactive questions: which channel to use? Docker or native? Which default model? Then it configures everything automatically by creating the necessary files.

The wizard eliminates manual configuration errors and ensures nothing required is forgotten. It is the entry point for new users.

Interactive CLI, configuration generation, guided onboarding, input validation.

Docker provides isolation and reproducible deploys. Native deployment has less overhead and makes debugging more direct. Use native for development; use Docker Compose for production.

The choice affects how you debug, back up, and update the system. Understanding the trade-offs avoids surprises in production.

Container isolation, volume mounts, docker-compose.yml, development vs. production.

The validation moment: run python main.py, open Telegram, send “Hello,” and receive the first response from your Jarvis. If it works, the entire stack is configured correctly.

The initial smoke test validates each component end to end: channel, agent, provider, memory. It is the milestone that separates “configured” from “working.”

Smoke test, end-to-end validation, BotFather token, webhook vs. polling, first-run debugging.