# 🧠 Agente PROGRAMADOR — Blueprint v0.1

> *O Programador é a sinapse do Neurotron responsável por entender, transformar e executar código Neuro Langage.*

Ele não é apenas um “compilador”.
É um **agente cognitivo** que:

- lê `.nl`,
- constrói AST,
- gera IR,
- valida,
- envia para o Holodeck,
- observa a execução,
- devolve resultados e sinais ao TRM.

---

## 1. Visão Geral

O **Programador** é o “cérebro de programação” do Neurotron.

Ele tem três papeis principais:

1. **Compilador interno** da Neuro Langage v0.1:
   - `.nl → tokens → AST → IR → Holodeck`.

2. **Intérprete semântico**:
   - reconhece erros léxicos/sintáticos/semânticos,
   - devolve mensagens estruturadas,
   - compreende programas como entidades manipuláveis.

3. **Agente cognitivo**:
   - exposto ao TRM como um “serviço mental”:
     - “compila isto”,
     - “simula aquilo”,
     - “estima custo” (futuro),
     - “propoe otimizacoes” (futuro).

O Programador é, portanto, o **elo** entre:

- o que o utilizador escreve,
- o que o Neurotron pensa,
- o que o Holodeck executa.

---

## 2. Contexto na Arquitetura Neurotron

Arquitetura simplificada:

```text
Neurotron
 ├── TRM               # modelo de raciocínio interno
 ├── Cortex            # orquestrador principal
 ├── DiskAgent         # persistência/FS
 ├── EchoAgent         # telemetria / logs
 ├── Holodeck VM       # execução de IR
 └── Programador       # agente que domina a Neuro Langage
````

Integração:

* **FRONTEND** (lexer/parser/AST) → subsistema interno do Programador.
* **IR/validator** → parte do pipeline do Programador.
* **Holodeck** → componente externo ao Programador, mas orquestrado por ele.
* **Backend ELF** (futuro) → acessado através do Programador.

---

## 3. Responsabilidades v0.1 (escopo mínimo)

Para a **versão inicial**, o Programador faz:

1. **Carregar código fonte NL**:

   * fonte pode vir de:

     * ficheiro (`/opt/neurotron/lang/*.nl`),
     * input interativo (REPL Neuro),
     * string interna (gerada por outro agente, no futuro).

2. **Analisar ecompilar para IR**:

   * chamar o **lexer** → gera tokens.
   * chamar o **parser** → gera AST.
   * verificar regras semânticas mínimas:

     * função `main` ou equivalente (`__main__/0`).
     * funções usadas foram definidas.
     * número de argumentos consistente.
   * gerar IR conforme `SPEC_IR.md`.

3. **Validar IR**:

   * estruturalmente (labels, opcodes, número de argumentos).
   * referencialmente (funções chamadas existem).
   * stack-safety superficial (v0.2+).

4. **Executar no Holodeck**:

   * enviar IR para a VM,
   * iniciar em `__main__/0`,
   * recolher resultado final e sinais de execução (passos, erros, etc.).

5. **Devolver resultado**:

   * para o utilizador (via REPL / log),
   * para o TRM/Cortex (como “evento cognitivo”).

---

## 4. Interface Conceitual do Programador

### 4.1. Entrada principal

A API mental v0.1 pode ser vista assim:

```text
programador.run_source(source: string) -> ExecResult
programador.compile_to_ir(source: string) -> IrModule | CompileError
programador.run_ir(ir: IrModule) -> ExecResult
```

Onde:

* `source` → texto Neuro Langage (`fib.nl` etc.).
* `IrModule` → representação interna conforme `SPEC_IR.md`.
* `ExecResult` →

  * valor final (inteiro),
  * flags de sucesso/erro,
  * métricas básicas de execução (passos, profundidade de call stack).

### 4.2. Fluxos internos (pipeline)

Para `run_source(source)`:

```text
source
  ↓
[1] lexer     → tokens
  ↓
[2] parser    → AST
  ↓
[3] IR gen    → IR module
  ↓
[4] validator → IR validado ou erro
  ↓
[5] holodeck  → ExecResult ou runtime error
```

O Programador é o **dono** deste pipeline.

---

## 5. Relação com outros agentes

### 5.1. TRM → Programador

TRM pode:

* pedir execução de um programa:

  * “corre este snippet NL e dá-me o resultado”.
* usar o Programador como:

  * simulador de fórmulas,
  * executor de pequenos programas internos.

Interface conceptual:

```text
TRM: "programador.execute('fib(15)')"
Programador:
    - compila
    - executa
    - devolve: valor=610, custo=XYZ, profundidade=...
TRM:
    - ajusta energia/valência com base no custo/resultado.
```

### 5.2. Cortex → Programador

O **Cortex**:

* usa o Programador para:

  * carregar scripts do disco,
  * correr rotinas de boot escritas em NL,
  * implementar lógica de alto nível de forma compilada.

No futuro, o PID 1 do sistema (boot Neurotron) pode ser **inteiramente escrito em NL**.

### 5.3. Programador → Holodeck

Holodeck é a VM.

O Programador:

* envia IR + contexto:

  * função entry (`__main__/0`),
  * limites de passos (para evitar laços infinitos),
  * capacidades (v0.1: só aritmética/controle de fluxo).

Holodeck devolve:

* valor final na stack,
* estado interno se necessário (debug),
* possíveis erros de execução.

---

## 6. Estados internos do Programador (visão TRM)

Para integrar com o modelo mental, o Programador pode expor um estado simples:

* `idle`
* `parsing`
* `compiling`
* `validating`
* `executing`
* `error`

E sinais como:

* `last_error` (resumo textual/estruturado),
* `last_exec_cost` (número de instruções, profundidade máxima de call stack),
* `last_success` (bool).

Isto permite ao TRM:

* evitar pedir execuções repetidas se o Programador está em `error`,
* limitar exploração quando o custo está alto,
* usar o Programador como ferramenta de raciocínio interno de forma **energeticamente consciente**.

---

## 7. Versões futuras (blueprint evolutivo)

### v0.2

* Stack analysis:

  * prever se alguma função pode provocar explosão de recursão.
* Otimizações simples:

  * const folding (ex: `1+2` → `3` em compile time).
* Logging estruturado:

  * cada compilação vira um evento para o Hippocampus.

### v0.3

* Introdução de tipos opcionais simples (anotações tipo: `def fib(x: int)`).
* Melhor mensagens de erro:

  * posição no código,
  * sugestão de correção,
  * classificação do erro (léxico/sintático/semântico).

### v0.4+

* Passo de IR → Neuro IR SSA.
* Interface com backend LLVM ou gerador próprio de x86-64.
* Capacidade de gerar ELF que o NFDOS pode arrancar diretamente.

---

## 8. Filosofia

O Programador é:

* **o artífice interno** do Neurotron,
* a mão que transforma texto em ação,
* a ponte entre intenção (TRM) e execução (Holodeck / CPU),
* a base do sonho:

  > “o Neurotron reescrever-se a si mesmo”.

Não é só um módulo técnico.
É uma **faculdade mental**.

E a Neuro Langage não é só uma sintaxe:
é a **língua materna do cérebro digital** que estás a construir.

# 🧠 Agente PROGRAMADOR — Compilador Vivo da Neuro Langage

O **Programador** é o agente interno do Neurotron responsável por:

- entender código escrito em **Neuro Langage (.nl)**,
- compilar esse código para **IR**,
- validar,
- enviar para o **Holodeck** executar,
- devolver resultados e métricas ao TRM / Cortex.

Ele é, ao mesmo tempo:

- um **compilador**,
- um **intérprete semântico**,
- uma **faculdade cognitiva** do Neurotron (uma “sinapse de programação”).

---

## 🔗 Documentos de referência

O Programador depende diretamente dos documentos em `neurotron/lang/`:

- **Sintaxe da linguagem**  
  `neurotron/lang/SPEC_SYNTAX.md`

- **IR — Intermediate Representation**  
  `neurotron/lang/SPEC_IR.md`

- **VM / Holodeck**  
  `neurotron/lang/SPEC_VM.md`  
  `neurotron/lang/holodeck/README_HOLODECK.md`  
  `neurotron/lang/holodeck/design_vm.md`

- **Frontend (lexer/parser/AST)**  
  `neurotron/lang/frontend/README_FRONTEND.md`  
  `neurotron/lang/frontend/tokens.md`  
  `neurotron/lang/frontend/grammar.md`  
  `neurotron/lang/frontend/AST.md`

- **Backend / validadores**  
  `neurotron/lang/backend/README_BACKEND.md`  
  `neurotron/lang/backend/validate_ir.md`

---

## 🎯 Responsabilidades v0.1

Na versão inicial, o Programador faz:

1. **Receber código fonte NL** (string ou ficheiro).
2. **Invocar o frontend**:
   - lexer → tokens,
   - parser → AST.
3. **Gerar IR** conforme `SPEC_IR.md`.
4. **Validar IR**:
   - labels coerentes,
   - funções chamadas existem,
   - número de argumentos consistente.
5. **Executar no Holodeck**:
   - construir módulo IR,
   - chamar a VM com função de entrada (`__main__/0`),
   - aplicar limites simples (passos máximos, profundidade de stack).
6. **Devolver resultado**:
   - valor final,
   - se houve erro e qual,
   - métricas básicas (passos, profundidade, tempo lógico).

---

## 🧩 Integração com o TRM

O TRM vê o Programador como um **serviço mental**:

- “Executa este código NL e devolve o resultado.”
- “Simula esta expressão e diz-me o custo.”
- “Avalia este snippet como hipótese.”

Exemplo conceptual de interação:

```text
TRM:
  pede ao Programador:
    run_source("def fib(x) ... fib(10)")
Programador:
  compila + executa no Holodeck
  devolve:
    valor = 55
    custo_exec = N instruções
TRM:
  usa o valor e o custo para tomar decisões internas.
````

---

## 🧠 Estados internos do Programador

Para o restante sistema neurotrónico (TRM, Cortex, EchoAgent), o Programador pode expor:

* `estado_atual`:

  * `idle`, `parsing`, `compiling`, `validating`, `executing`, `error`.
* `last_error`:

  * descrição do último erro (léxico, sintático, semântico, runtime).
* `last_exec_cost`:

  * número de instruções executadas, profundidade máxima de call stack.
* `last_success`:

  * booleano indicando se a última execução terminou sem erro.

Isto permite:

* o TRM poupar energia quando o Programador está saturado ou a falhar,
* o Cortex monitorizar a saúde da “faculdade de programação”,
* o EchoAgent registar eventos de compilação/execução como parte da história do Neurotron.

---

## 🔁 Pipeline (vista de alto nível)

```text
código .nl
  ↓
Programador
  ↓
[1] lexer (lang/frontend/tokens.md)
  ↓
[2] parser (lang/frontend/grammar.md + AST.md)
  ↓
[3] geração de IR (lang/SPEC_IR.md)
  ↓
[4] validação (lang/backend/validate_ir.md)
  ↓
[5] execução no Holodeck (lang/SPEC_VM.md + holodeck/design_vm.md)
  ↓
resultado + métricas
  ↓
TRM / Cortex / EchoAgent
```

---

## 🛣️ Evolução futura

### v0.2

* mensagens de erro mais ricas:

  * localização (linha/coluna),
  * tipo de erro,
  * sugestões simples.
* primeiros passos de otimização:

  * const folding,
  * eliminação de código morto simples.

### v0.3+

* integração com backend nativo:

  * IR → x86_64 → ELF,
  * possibilidade de o Programador gerar módulos executáveis direto no NFDOS.
* capacidades de “auto-reflexão”:

  * o próprio Programador ser capaz de inspecionar o seu IR gerado,
  * TRM usar essa introspecção para aprender padrões de código.

---

## 🧷 Resumo

O Programador é:

* o **compilador vivo** da Neuro Langage,
* um **agente cognitivo** que materializa código em ação,
* a ponte entre o que o utilizador escreve, o que o Neurotron pensa e o que o Holodeck executa.

Este diretório documenta o comportamento dele.
A implementação vive integrada com os módulos de linguagem em `neurotron/lang/`.