🇺🇸 English (this file) · 🇧🇷 Português do Brasil

RS4-cortex-flow

Local Multi-Agent Orchestration Engine · Cortex-Flow V2 · v2.1.0

A deterministic LangGraph pipeline that turns raw human input into scored, auditable deliverables. Inference and vector storage stay on your machine — R$ 0,00 per run.

Author: Raphael Mendes · Rs4Machine Lab — 📧 python.dev.raphael@gmail.com

---

📑 Table of Contents

• 1. What problem does this system solve?
• 2. How does it solve it?
• 3. What are the boundaries and performance limits?
• 4. Who governs the decision?
• 🖥️ HITL Command Panel (Streamlit)
• 🔒 Builder Safety Guardrails
• 📚 RS4 Library Exporter
• 📈 Real-World Benchmarks (E2E Suite)
• 🧪 Running the End-to-End Test
• 🚀 Getting Started
• 📁 Project Structure
• 📄 License
• 🏢 Contact

---

1. What problem does this system solve?

Turning raw ideas into structured decisions normally requires either hours of manual analysis or sending private material to cloud LLM APIs on a per-token bill.

RS4-cortex-flow addresses the orchestration gap: it chains specialized agents locally to produce standardized, auditable artifacts (Markdown with YAML front-matter, client proposals, evaluation records) while:

• Cost stays at R$ 0,00 — no API fees; inference runs on the local machine through Ollama.
• Data stays local — prompts, context and the vector store never leave the host during inference and storage (see the egress boundary in section 3).
• Decisions stay auditable — every node writes telemetry to Metrics/, and every run ends with a written human decision record.

2. How does it solve it?

A LangGraph StateGraph moves a typed CortexState (TypedDict, 23 fields) through specialized nodes, with deterministic, LLM-free routers (rule-based) that select the production route. The two production fronts are:

Route	Node sequence	Output
A — COPY_OFFER (Commerce)	triagem → redator → critico → evaluator	Commercial copy / ad in drafts/ofertas/
B — BUILDER_TEMPLATE (Freelas)	triagem → mapeador → techscout → critico → sintetizador → freelas_proposta → evaluator	Technical scope in drafts/refinados/ + client proposal in drafts/freelas_propostas/

The Builder is not part of the automatic graph. It is an isolated node triggered only by the human operator — see Builder Safety Guardrails. The graph also carries an auxiliary Route C (raw ideas → refined synthesis in drafts/refinados/, shown in the Ideias tab of the panel). In the diagram, Routes B and C share edges, so only ROTA_B is labelled there.

Supporting layers:

• Typed state: cortex_flow_v2/graph/state.py defines CortexState; the wrapper in cortex_flow_v2/graph/__init__.py compiles the graph and exports the diagram above.
• RAG (ChromaDB): a persistent local store (./chroma_db_data, collection decisoes) embedded with nomic-embed-text via local Ollama, seeded idempotently from filosofia_rs4.txt (python cortex_flow_v2/vectorstore/seed_dna.py). Critic, Synthesizer, Builder and Evaluator query it for RS4 decision DNA before prompting.
• Local inference (Ollama): REST calls to localhost:11434 using qwen2.5:7b (default), qwen2.5-coder:7b (Builder) and qwen2.5:3b (fallback), with temperature=0.2, num_predict=1024 and a 240 s HTTP timeout per request.
• Commerce connector: cortex_flow_v2/inbox/conector_commerce.py loads PENDENTE opportunities from cortex_flow_v2/inbox/payload_commerce.json into the initial state; cortex_flow_v2/inbox/ponte_commerce.py caps the inbox at 3 items per type per cycle.

3. What are the boundaries and performance limits?

• Sequential FIFO on CPU: nodes execute strictly one at a time — no parallel node execution. This is deliberate, to keep RAM/VRAM bounded on consumer hardware.
• Hardware pause: time.sleep(2.0) runs at every node transition (PAUSA_HARDWARE_S = 2.0, Item 09) — 8.0 s total on Route A, 14.0 s on Route B.
• Model bounds: 7B-class local models; at most 1,024 tokens per response (num_predict); prompt context capped at 1,500 characters; 240 s timeout per request. Nodes degrade gracefully (smaller model or embedded rule fallback) instead of hanging.
• Fatal-failure halt: if a node fails fatally (e.g. a truncated response), the pipeline stops instead of passing garbage downstream.
• Wall time: 488.48 s for Route A and 1,137.32 s for Route B on the reference machine (Windows 11 + local Ollama) — about 27.1 minutes (1,625.80 s) for the full E2E suite, hardware pauses included.
• Availability gate: the E2E suite never fabricates results — if Ollama is offline it aborts with FALHA_OLLAMA_OFFLINE.
• Network egress: inference and vector storage are strictly local. The single optional outbound call is the Tech Scout's DuckDuckGo keyword search, triggered only when RAG returns insufficient hits; it fails soft when offline and is reported in telemetry.
• Determinism boundary: triage and routing are pure rules (sub-millisecond, zero LLM calls). LLM text itself is stochastic within the bounds above.

4. Who governs the decision?

Automation Level 1 — HITL (Human in the Loop): the system proposes, the human disposes.

1. The Evaluator grades each deliverable and emits a preliminary score (NOTA_PRELIMINAR, 1–5) plus a recommendation:

   Score	Recommendation
   Nota ≥ 4	APROVAR (approve)
   Nota = 3	REVISAR (revise)
   Nota ≤ 2	REJEITAR (reject)

2. The evaluation is persisted to drafts/avaliacoes/avaliacao_*.md with status AGUARDANDO_DECISAO_HUMANA.

3. Final authority is the CEO / Raphael Mendes (Rs4Machine Lab). The score is advisory only: nothing is approved or published autonomously, and the approval filter is Nota ≥ 4 plus explicit human confirmation.

🖥️ HITL Command Panel (Streamlit)

Level 1 governance has a visual front-end: cortex_flow_v2/app_hitl.py scans the drafts in drafts/ and lists them in tabs, one per production front.

streamlit run cortex_flow_v2/app_hitl.py     # http://localhost:8501

Tab	Source folder	Route
Commerce	drafts/ofertas/	A — COPY_OFFER
Freelas	drafts/refinados/ + drafts/freelas_propostas/	B — BUILDER_TEMPLATE
Ideias	drafts/refinados/	C — raw ideas
Histórico & Reversão	drafts/avaliacoes/	past decisions, with Restore to Pending

• Freelas duality: each Freelas card has two sub-tabs — Proposta (freelas-proposta: the text sent to the client) and Escopo (freelas-escopo: technical analysis plus the Evaluator's opinion).
• Agent opinions: only the Evaluator's preliminary score is highlighted; the opinions of Mapper, Tech Scout, Critic and Synthesizer sit inside the [ 🔍 Ver Pareceres dos Agentes ] expander.
• Human review: operator score 1–5 plus a written opinion, time-stamped and saved to drafts/avaliacoes/revisao_ceo_<timestamp>.json. Score ≥ 4 enables Approve & Persist (ChromaDB collection decisoes); score < 4 enables Reject / Discard; score = 5 also enables Trigger Builder.
• Pipeline from the panel: buttons chain the Commerce inbox and the pipeline, with per-demand progress.

🔒 Builder Safety Guardrails

The Builder (cortex_flow_v2/nodes/builder.py, model qwen2.5-coder:7b) generates an MVP code template. It is fully decoupled from the automatic graph and guarded by two hard locks, both checked before any ChromaDB or Ollama call:

1. Score-5 lock: it runs exclusively when the human operator grades the item 5. Any other score — or no score — blocks the node, and the block is logged.
2. Daily cap of 1 MVP/day: the date of the last run lives in Metrics/builder_daily_cap.json; further attempts the same day are refused and recorded in the block history and in logs/builder_fase2.log.

📚 RS4 Library Exporter

cortex_flow_v2/exportador_biblioteca.py mirrors the approved deliverables (operator score ≥ 4) from drafts/ into the physical RS4 library at Desktop/Rs4-Library, organised in numbered folders (04_agente_sintetizador, 05_agente_redator, 06_agente_builder, 07_avaliacoes_evaluator, 08_decisoes_humanas, 09_biblioteca_ideias) with sub-folders by score. It also runs when an evaluation is submitted in the panel.

python cortex_flow_v2/exportador_biblioteca.py [--destino PATH]

📈 Real-World Benchmarks (E2E Suite)

Measured by Metrics/metrics_integracao_v2.json during the full E2E run of the Commerce payload (2026-10-13), local Ollama:

Run	Route	Wall time	Score	Decision	Primary artifacts
A	COPY_OFFER	488.48 s	3 / 5	REVISAR	Drafts in drafts/ofertas/
B	BUILDER_TEMPLATE	1,137.32 s	4 / 5	APROVAR	Scope in drafts/refinados/ + proposal in drafts/freelas_propostas/
0	Triagem (Agent 0) — deterministic classifier, no LLM	1.24 ms	—	—	frente_alvo in CortexState

Notes: cumulative wall time of both routes = 1,625.80 s (~27.1 min), hardware pauses included; every run also writes an HITL record to drafts/avaliacoes/.

🧪 Running the End-to-End Test

python cortex_flow_v2/tests/test_esteira_completa.py        # both routes (default)
python cortex_flow_v2/tests/test_esteira_completa.py A      # Route A only
python cortex_flow_v2/tests/test_esteira_completa.py B      # Route B only

Prerequisites: Ollama online with the models listed below and at least one PENDENTE opportunity in cortex_flow_v2/inbox/payload_commerce.json.

The suite validates: py_compile integrity; orchestrator locks (num_predict=1024, timeout=240s); Commerce payload load; Ollama health; real execution of each route via app.invoke(...); node sequence via the per-node Metrics/*.json; deliverables (copy / synthesis / proposal / evaluation / score 1–5); and the consolidated report in Metrics/metrics_integracao_v2.json.

🚀 Getting Started

1. Prerequisites

• Python 3.11+ (validated on 3.14)

• Ollama running locally with:

  ollama pull qwen2.5:7b
  ollama pull qwen2.5-coder:7b
  ollama pull qwen2.5:3b        # fallback
  ollama pull nomic-embed-text  # RAG embeddings

• Python dependencies for V2 (the legacy orchestrator is stdlib-only):

  pip install langgraph chromadb ollama streamlit
  pip install duckduckgo-search   # optional: Tech Scout web fallback

2. Seed the RAG vector store

python cortex_flow_v2/vectorstore/seed_dna.py

3. Run the pipeline

# HITL command panel (recommended)
streamlit run cortex_flow_v2/app_hitl.py

# Full E2E suite (both routes)
python cortex_flow_v2/tests/test_esteira_completa.py

# Regenerate the graph diagram
python -m cortex_flow_v2.graph

4. Legacy orchestrator (v1, standard library only)

python orquestrador_claudio.py teste_frontend.txt

5. Docker (legacy orchestrator)

docker compose run --rm claudio-project python orquestrador_claudio.py teste_frontend.txt

The Compose stack isolates the orchestrator in a container while reaching the host's Ollama through host.docker.internal; ./bruto, ./agentes, ./biblioteca and ./Metrics are bind-mounted.

Telemetry: every node writes Metrics/metrics_*_v2.json (system / model / agent dimensions — CEO RS4 rule) with latency, token usage and exit status.

📁 Project Structure

RS4-cortex-flow/
├── cortex_flow_v2/
│   ├── graph/          # StateGraph, CortexState, routers, hardware pauses
│   ├── nodes/          # triagem, redator, mapeador, techscout, critico, freelas_proposta, builder (isolated), ...
│   ├── inbox/          # Commerce connector + bridge + payload_commerce.json
│   ├── vectorstore/    # ChromaDB client + seed_dna (RAG)
│   ├── app_hitl.py     # Streamlit HITL command panel
│   ├── exportador_biblioteca.py   # RS4-Library exporter
│   └── tests/          # unit tests + E2E suite
├── agentes/            # agent prompt files (pt-BR)
├── assets/             # Rs4Machine.png + cortex_flow_v2_graph.png
├── bruto/              # raw inputs (samples only are versioned)
├── drafts/             # outputs: ofertas/, refinados/, freelas_propostas/, templates/, avaliacoes/ (git-ignored)
├── Metrics/            # per-node telemetry + builder_daily_cap.json (git-ignored)
├── logs/               # execution logs (git-ignored)
├── chroma_db_data/     # local vector store (git-ignored)
├── orquestrador_claudio.py   # legacy v1 orchestrator (stdlib only)
├── docker-compose.yml / Dockerfile
└── README.pt-BR.md     # versão em português

📄 License

This project is open-source software licensed under the MIT License — see the LICENSE file for details.

🏢 Contact

Rs4Machine — AI Research Lab & Autonomous Systems

• Author: Raphael Mendes / Rs4Machine Lab
• 📧 Technical e-mail: python.dev.raphael@gmail.com
• 🔗 GitHub: github.com/raphaelmendes-dev

RS4-cortex-flow v2.1.0 — October 2026