toolloop 0.1.0__tar.gz

toolloop-0.1.0/.gitignore

@@ -0,0 +1,25 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+
+# Environments
+.venv/
+venv/
+
+# Tooling caches
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+
+# uv (libraries don't ship lockfiles)
+uv.lock
+
+# Editors
+.idea/
+.vscode/
+*.swp

toolloop-0.1.0/.zcode/plans/plan-sess_d9dbb53a-b8d6-4fea-bf5f-ad02e807cf56.md

@@ -0,0 +1,47 @@
+# Plano de implementação — toolloop v0.1.0 (atualizado)
+
+Mesmo plano aprovado, com o ajuste de granularidade dos modos de controle: **ControlMode com exatamente 2 opções — `APPROVE` (default-deny: toda tool call precisa ser liberada por um hook `on_tool_call`) e `BYPASS` (default-allow: autônomo, hooks ainda podem vetar/modificar)**. Sem modo intermediário. A renomeação da pasta `~/Projects/openFlow` → `~/Projects/toolloop` está confirmada no scaffold.
+
+## 1. Scaffold e identidade
+
+- Renomear pasta (levando `brainstorms/`), `git init -b main`, atualizar o brainstorm com a decisão dos 2 modos (fonte da verdade).
+- `pyproject.toml` (hatchling): `toolloop` 0.1.0, **Python ≥3.11**, runtime dep única **pydantic ≥2**; dev: `pytest`, `pytest-asyncio`, `ruff`. Gerenciado com **uv**. **MIT**.
+- Layout `src/`: `_types` (mensagens, exceções, Status), `provider` (Protocol async), `tools/` (`definition.py` com `@tool` + std toolset `shell/fs/search`), `protocol/` (`base.py` ABC + `json_protocol.py`), `agent` (loop + RunResult), `hooks` (3 hooks + ControlMode), `context` (truncation + compaction), `subagent`, `examples/`, `tests/`.
+
+## 2. Contratos centrais
+
+```python
+class Provider(Protocol):
+    async def complete(self, messages: Sequence[Message]) -> str: ...
+
+@tool  # async fn; nome=função, desc=docstring, schema via type hints (pydantic)
+
+class Agent:
+    def __init__(self, provider, tools=(), *, protocol=None, system_prompt=None,
+                 control=ControlMode.BYPASS, on_step=None, on_tool_call=None,
+                 on_tool_result=None, max_context_tokens=None): ...
+    async def run(self, input, *, max_iterations=25, on_max=OnMax.RAISE,
+                  control=None, output_model=None) -> RunResult
+# RunResult: output (validado se output_model), status (COMPLETED|MAX_ITERATIONS), history completo
+```
+
+- Envelope JSON: `{"type":"tool_call","calls":[{id?,name,args}]}` | `{"type":"final_answer","output":...}`; parse tolerante (fenced/cru, último bloco válido vence); auto-repair com limite de falhas consecutivas; calls executadas **sequencialmente**.
+- Hooks: `on_step`/`on_tool_call`→`Decision.allow/deny`/`on_tool_result`; BYPASS mantém observabilidade; APPROVE sem hook `on_tool_call` → erro de configuração claro no `run()`.
+- Contexto: heurística chars/4; truncation de observações antigas; compaction via sumarização pelo próprio provider (preserva system + mensagens recentes); safety-net de tamanho por resultado; toolset com resultados compactos por design.
+- `subagent_tool(agent)` no core; toolset padrão com `bash` marcada `dangerous`.
+
+## 3. Milestones (commits por grupo)
+
+1. Scaffold + config + git
+2. Core (`_types`, `provider`, `tools`)
+3. `protocol/json_protocol`
+4. `agent` (loop, políticas de max_iterations, histórico)
+5. `hooks` + ControlMode APPROVE/BYPASS
+6. `context` + `subagent`
+7. Toolset padrão (6 tools)
+8. `examples/` + README real
+9. Suite de testes (FakeProvider scriptado: happy path, auto-repair, veto, modos, políticas de estouro, compaction, subagent, tools em tmp_path) + ruff limpo + tag `v0.1.0`
+
+## 4. Fora do escopo v1 (roadmap no README)
+
+Streaming, tool calls paralelas, CLI (`init`/`test`), adapters publicados como extras.

toolloop-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 apavanello
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

toolloop-0.1.0/PKG-INFO

@@ -0,0 +1,238 @@
+Metadata-Version: 2.5
+Name: toolloop
+Version: 0.1.0
+Summary: Agent loop framework for LLM providers without native tool use
+Author: apavanello
+License: MIT
+License-File: LICENSE
+Keywords: agents,ai,framework,llm,tool-use
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: pydantic>=2.7
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# toolloop
+
+**Agent loops for LLM providers without native tool use.**
+
+`toolloop` is a Python framework for building autonomous agents — tool use,
+exploration, coding — on top of any LLM endpoint, even (especially) the ones
+whose SDKs never exposed a `tools` parameter. If you can send messages and get
+text back, you can run an agent on it.
+
+```
+             ┌─────────────────────────────────────────────┐
+             │                                             │
+  input ──▶  │   system prompt (tool instructions)        │
+             │   + conversation history                    │
+             ▼                                             │
+       ┌───────────┐   {"type":"tool_call", ...}   ┌────────────┐
+       │ provider  │ ────────────────────────────▶ │ tool runs  │
+       │ (yours)   │                               └────────────┘
+       └───────────┘                                       │
+             │                                             │ observation
+             │ {"type":"final_answer", ...}               ▼
+             ▼                                       back to provider
+          output
+```
+
+## Why
+
+Plenty of real-world LLM access goes through proprietary corporate SDKs that
+proxy the big providers (Anthropic, OpenAI, Kimi, DeepSeek, ...) but strip or
+never implemented the tool-use layer. The models behind them are perfectly
+capable of agentic work — the SDK just won't carry function calls.
+
+`toolloop` solves this at the application layer:
+
+- **Bring your own provider.** The framework never manages providers. The
+  whole contract is one async method: `complete(messages) -> str`.
+- **Tools over plain text.** Tool schemas are rendered into the system prompt;
+  tool calls are parsed out of the model's text responses. Parse errors are
+  fed back to the model (auto-repair) until it gets the envelope right.
+- **Loop until satisfied.** Given an input, the agent calls tools, receives
+  observations, and iterates until it emits a `final_answer`.
+
+## Install
+
+Requires Python 3.11+.
+
+```bash
+pip install toolloop        # once published
+# or, from source:
+uv sync --extra dev
+```
+
+## Quickstart (no LLM needed)
+
+```python
+import asyncio
+
+from toolloop import Agent, tool
+
+
+@tool
+async def add(a: int, b: int) -> int:
+    """Add two numbers."""
+    return a + b
+
+
+class DemoProvider:
+    """A scripted provider standing in for your real one."""
+
+    def __init__(self):
+        self.turns = [
+            '{"type": "tool_call", "calls": [{"id": "c1", "name": "add", "args": {"a": 2, "b": 3}}]}',
+            '{"type": "final_answer", "output": "2 + 3 = 5"}',
+        ]
+
+    async def complete(self, messages):
+        return self.turns.pop(0)
+
+
+agent = Agent(DemoProvider(), tools=[add])
+result = asyncio.run(agent.run("how much is 2 + 3?"))
+print(result.output)                    # 2 + 3 = 5
+print(result.status)                    # Status.COMPLETED
+print(result.history[0].calls[0].result)  # 5
+```
+
+## Bring your own provider
+
+Implement one async method and you are done — SDK, plain HTTP, whatever:
+
+```python
+class MyCorporateProxyProvider:
+    async def complete(self, messages):
+        response = await my_corporate_sdk.chat(
+            [{"role": m.role.value, "content": m.content} for m in messages]
+        )
+        return response.text
+```
+
+Reference adapters (OpenAI-compatible endpoints and Anthropic) live in
+[`examples/`](examples/) as copy-paste code, not dependencies.
+
+## Tour
+
+### Defining tools
+
+```python
+@tool                                    # name = function, schema = type hints
+async def search_docs(query: str, limit: int = 5) -> str:
+    """Search the internal documentation."""
+    ...
+
+@tool(dangerous=True)                    # flagged for approval hooks
+async def run_migration(env: str) -> str:
+    """Run the database migration."""
+    ...
+```
+
+Arguments are validated with pydantic; invalid arguments and raised exceptions
+become error observations the model repairs from — they never crash the loop.
+
+### Running agents
+
+```python
+result = await agent.run(
+    "summarize open PRs",
+    max_iterations=25,
+    on_max=OnMax.WRAP_UP,       # or RAISE (default) or PARTIAL
+    output_model=Summary,       # pydantic model: validated structured output
+)
+result.status                   # Status.COMPLETED | Status.MAX_ITERATIONS
+result.output                   # str, or a validated Summary instance
+result.history                  # full audit trail of every step and call
+```
+
+### Control modes and hooks
+
+Two modes, configurable on the `Agent` and overridable per `run()`:
+
+- **`ControlMode.BYPASS`** (default) — autonomous; hooks may still veto or
+  rewrite calls.
+- **`ControlMode.APPROVE`** — default-deny; every tool call must be allowed by
+  an `on_tool_call` hook (human-in-the-loop).
+
+```python
+async def gatekeeper(ctx) -> Decision:
+    if ctx.dangerous:
+        answer = input(f"allow {ctx.name}({ctx.args})? [y/N] ")
+        return Decision.allow() if answer == "y" else Decision.deny("no")
+    return Decision.allow()
+
+agent = Agent(provider, tools=STD_TOOLS, control=ControlMode.APPROVE, on_tool_call=gatekeeper)
+```
+
+`on_step` and `on_tool_result` hooks give you full observability (audit,
+logging, tracing) in both modes.
+
+### Context management
+
+Set `max_context_tokens` and the agent keeps the conversation within budget:
+old tool observations are truncated first, then the middle of the conversation
+is compacted via summarization by the provider itself. The standard toolset
+already returns compact results by design (a write tool confirms the size it
+wrote, it does not echo the content).
+
+```python
+agent = Agent(provider, tools=STD_TOOLS, max_context_tokens=16_000)
+```
+
+### Subagents
+
+Wrap an agent as a tool: it explores with its own isolated context and only
+its final answer comes back.
+
+```python
+from toolloop import subagent_tool
+
+researcher = Agent(provider, tools=[search_docs])
+agent = Agent(provider, tools=[subagent_tool(researcher), write_file])
+```
+
+### Standard toolset (optional)
+
+```python
+from toolloop import STD_TOOLS
+# bash, read_file, write_file, edit_file, list_files, grep
+```
+
+Pure-Python coding-agent toolset; import it or ignore it — the core knows
+nothing about it.
+
+## Testing your agents
+
+The provider contract is one method, so deterministic tests are trivial:
+script a fake provider with canned responses (see `tests/conftest.py` in this
+repo) and assert on `result.history` — no LLM, no flakes.
+
+## Project
+
+- License: MIT
+- Python: 3.11+
+- Dependencies: pydantic (only)
+- Roadmap: streaming, parallel tool calls, a small CLI (`init`, `test`), ...
+
+## How it works
+
+1. Tool schemas and the JSON envelope format are rendered into the system
+   prompt by a pluggable `ToolProtocol` (default: `JsonToolProtocol`).
+2. The agent calls the provider and parses the response envelope:
+   `tool_call` (a list of calls, executed sequentially in v1) or
+   `final_answer`.
+3. Tool results are appended as observations; parse/validation errors are fed
+   back so the model can repair its own output.
+4. The loop ends on `final_answer`, on `max_iterations` (per the configured
+   policy), or when a hook denies everything.

toolloop-0.1.0/README.md

@@ -0,0 +1,215 @@
+# toolloop
+
+**Agent loops for LLM providers without native tool use.**
+
+`toolloop` is a Python framework for building autonomous agents — tool use,
+exploration, coding — on top of any LLM endpoint, even (especially) the ones
+whose SDKs never exposed a `tools` parameter. If you can send messages and get
+text back, you can run an agent on it.
+
+```
+             ┌─────────────────────────────────────────────┐
+             │                                             │
+  input ──▶  │   system prompt (tool instructions)        │
+             │   + conversation history                    │
+             ▼                                             │
+       ┌───────────┐   {"type":"tool_call", ...}   ┌────────────┐
+       │ provider  │ ────────────────────────────▶ │ tool runs  │
+       │ (yours)   │                               └────────────┘
+       └───────────┘                                       │
+             │                                             │ observation
+             │ {"type":"final_answer", ...}               ▼
+             ▼                                       back to provider
+          output
+```
+
+## Why
+
+Plenty of real-world LLM access goes through proprietary corporate SDKs that
+proxy the big providers (Anthropic, OpenAI, Kimi, DeepSeek, ...) but strip or
+never implemented the tool-use layer. The models behind them are perfectly
+capable of agentic work — the SDK just won't carry function calls.
+
+`toolloop` solves this at the application layer:
+
+- **Bring your own provider.** The framework never manages providers. The
+  whole contract is one async method: `complete(messages) -> str`.
+- **Tools over plain text.** Tool schemas are rendered into the system prompt;
+  tool calls are parsed out of the model's text responses. Parse errors are
+  fed back to the model (auto-repair) until it gets the envelope right.
+- **Loop until satisfied.** Given an input, the agent calls tools, receives
+  observations, and iterates until it emits a `final_answer`.
+
+## Install
+
+Requires Python 3.11+.
+
+```bash
+pip install toolloop        # once published
+# or, from source:
+uv sync --extra dev
+```
+
+## Quickstart (no LLM needed)
+
+```python
+import asyncio
+
+from toolloop import Agent, tool
+
+
+@tool
+async def add(a: int, b: int) -> int:
+    """Add two numbers."""
+    return a + b
+
+
+class DemoProvider:
+    """A scripted provider standing in for your real one."""
+
+    def __init__(self):
+        self.turns = [
+            '{"type": "tool_call", "calls": [{"id": "c1", "name": "add", "args": {"a": 2, "b": 3}}]}',
+            '{"type": "final_answer", "output": "2 + 3 = 5"}',
+        ]
+
+    async def complete(self, messages):
+        return self.turns.pop(0)
+
+
+agent = Agent(DemoProvider(), tools=[add])
+result = asyncio.run(agent.run("how much is 2 + 3?"))
+print(result.output)                    # 2 + 3 = 5
+print(result.status)                    # Status.COMPLETED
+print(result.history[0].calls[0].result)  # 5
+```
+
+## Bring your own provider
+
+Implement one async method and you are done — SDK, plain HTTP, whatever:
+
+```python
+class MyCorporateProxyProvider:
+    async def complete(self, messages):
+        response = await my_corporate_sdk.chat(
+            [{"role": m.role.value, "content": m.content} for m in messages]
+        )
+        return response.text
+```
+
+Reference adapters (OpenAI-compatible endpoints and Anthropic) live in
+[`examples/`](examples/) as copy-paste code, not dependencies.
+
+## Tour
+
+### Defining tools
+
+```python
+@tool                                    # name = function, schema = type hints
+async def search_docs(query: str, limit: int = 5) -> str:
+    """Search the internal documentation."""
+    ...
+
+@tool(dangerous=True)                    # flagged for approval hooks
+async def run_migration(env: str) -> str:
+    """Run the database migration."""
+    ...
+```
+
+Arguments are validated with pydantic; invalid arguments and raised exceptions
+become error observations the model repairs from — they never crash the loop.
+
+### Running agents
+
+```python
+result = await agent.run(
+    "summarize open PRs",
+    max_iterations=25,
+    on_max=OnMax.WRAP_UP,       # or RAISE (default) or PARTIAL
+    output_model=Summary,       # pydantic model: validated structured output
+)
+result.status                   # Status.COMPLETED | Status.MAX_ITERATIONS
+result.output                   # str, or a validated Summary instance
+result.history                  # full audit trail of every step and call
+```
+
+### Control modes and hooks
+
+Two modes, configurable on the `Agent` and overridable per `run()`:
+
+- **`ControlMode.BYPASS`** (default) — autonomous; hooks may still veto or
+  rewrite calls.
+- **`ControlMode.APPROVE`** — default-deny; every tool call must be allowed by
+  an `on_tool_call` hook (human-in-the-loop).
+
+```python
+async def gatekeeper(ctx) -> Decision:
+    if ctx.dangerous:
+        answer = input(f"allow {ctx.name}({ctx.args})? [y/N] ")
+        return Decision.allow() if answer == "y" else Decision.deny("no")
+    return Decision.allow()
+
+agent = Agent(provider, tools=STD_TOOLS, control=ControlMode.APPROVE, on_tool_call=gatekeeper)
+```
+
+`on_step` and `on_tool_result` hooks give you full observability (audit,
+logging, tracing) in both modes.
+
+### Context management
+
+Set `max_context_tokens` and the agent keeps the conversation within budget:
+old tool observations are truncated first, then the middle of the conversation
+is compacted via summarization by the provider itself. The standard toolset
+already returns compact results by design (a write tool confirms the size it
+wrote, it does not echo the content).
+
+```python
+agent = Agent(provider, tools=STD_TOOLS, max_context_tokens=16_000)
+```
+
+### Subagents
+
+Wrap an agent as a tool: it explores with its own isolated context and only
+its final answer comes back.
+
+```python
+from toolloop import subagent_tool
+
+researcher = Agent(provider, tools=[search_docs])
+agent = Agent(provider, tools=[subagent_tool(researcher), write_file])
+```
+
+### Standard toolset (optional)
+
+```python
+from toolloop import STD_TOOLS
+# bash, read_file, write_file, edit_file, list_files, grep
+```
+
+Pure-Python coding-agent toolset; import it or ignore it — the core knows
+nothing about it.
+
+## Testing your agents
+
+The provider contract is one method, so deterministic tests are trivial:
+script a fake provider with canned responses (see `tests/conftest.py` in this
+repo) and assert on `result.history` — no LLM, no flakes.
+
+## Project
+
+- License: MIT
+- Python: 3.11+
+- Dependencies: pydantic (only)
+- Roadmap: streaming, parallel tool calls, a small CLI (`init`, `test`), ...
+
+## How it works
+
+1. Tool schemas and the JSON envelope format are rendered into the system
+   prompt by a pluggable `ToolProtocol` (default: `JsonToolProtocol`).
+2. The agent calls the provider and parses the response envelope:
+   `tool_call` (a list of calls, executed sequentially in v1) or
+   `final_answer`.
+3. Tool results are appended as observations; parse/validation errors are fed
+   back so the model can repair its own output.
+4. The loop ends on `final_answer`, on `max_iterations` (per the configured
+   policy), or when a hook denies everything.

toolloop-0.1.0/brainstorms/2026-08-22-framework-ia-tool-use.md

@@ -0,0 +1,79 @@
+# toolloop — Framework Python de agent loop sem tool use nativo: Brainstorm / Discovery Notes
+Date: 2026-08-22 · Goal: Definir um framework Python que facilite a criação de ferramentas/agentes que usam IA, onde o provider (abstraido) não suporta tool use nativamente.
+
+## Summary / key decisions
+- **O que é**: framework de **agent loop** (harness de agente autônomo, estilo Claude Code), não só emulação de tool use. Loop central: dada uma entrada X, o modelo usa as tools disponíveis em loop (uso ferramental, exploratório e codificatório) **até ficar satisfeito**, produzindo a saída final.
+- **Problema real**: SDKs privativos corporativos que fazem proxy de providers grandes (Anthropic, OpenAI, Kimi, DeepSeek etc.) mas têm uma camada corporativa que **não expõe tools use** ("OpenRouter corporativo"). Modelos por trás são fortes; a limitação é do SDK.
+- **Provider**: framework **não gerencia providers**. Contrato mínimo async: `async def complete(messages) -> str` (Protocol). Sem streaming no contrato v1. Usuário traz SDK próprio/código próprio. Adapters OpenAI-compatível e Anthropic apenas como `examples/`, não dependência.
+- **Protocolo de tools plugável** (renderizador de system prompt + parser de saída); default = **bloco JSON**; **auto-repair**: erro de parse/validação volta ao modelo como observação.
+- **Envelope explícito com discriminador**: `{"type": "tool_call", "calls": [...], ...}` ou `{"type": "final_answer", "output": ...}`. Loop termina só com `final_answer` (pode carregar saída estruturada validada). Campo `calls` é lista desde o v1 (forward-compatible), mas **v1 executa sequencialmente**; paralelização no roadmap. `max_iterations` configurável com política de estouro (erro / forçar wrap-up / retornar parcial com status).
+- **Definição de tools**: `@tool` em funções **async**; nome = função, descrição = docstring, schema via type hints + **pydantic** (validação alimenta auto-repair). Retorno `str` ou serializável; exceções viram observação de erro por padrão (configurável).
+- **Toolset opcional** `toolloop.tools`: `bash`, `read_file`, `write_file`, `edit_file`, `grep`/`search`, `list_files`. Core permanece agnóstico.
+- **Hooks async de primeira classe**: `on_step` (por turno), `on_tool_call` (pré-execução; veto/modificação/aprovação → human-in-the-loop), `on_tool_result` (pós-execução). Resultado de `run()` carrega histórico completo.
+- **Modos de controle: exatamente 2** (decisão final do usuário ao aprovar o plano) — `APPROVE` (default-deny: toda tool call precisa ser liberada pelo hook `on_tool_call`) e `BYPASS` (default-allow: autônomo; hooks ainda podem vetar/modificar). Configuráveis na instanciação e sobrescrevíveis no `run()`. Sem modo intermediário.
+- **Gestão de contexto como harnesses modernos**: `max_context_tokens` opcional com truncation de tool results antigos + compaction por sumarização; resultados de tools **compactos por design** (confiança na sub-execução, estilo a2a); safety-net de tamanho por resultado; tool **`subagent` no core v1** (contexto isolado, devolve só `final_answer`).
+- **Identidade**: nome **toolloop** (PyPI livre, sem colisões conceituais — `openloop` colide com thu-nmrc/openloop; `openflow` colide com projeto SDN de rede). **Open source, MIT**. Python 3.11+, pyproject + uv, pytest com provider fake em memória, ruff. v1 é **library pura** (sem CLI); roadmap: CLI básico (`init`, `test`, etc.).
+
+## Q&A log
+### Q0 — contexto adicional (antes da Q1)
+- Asked: (usuário forneceu contexto espontaneamente)
+- Captured: "simular o comportamento de agentes autônomos como harnesses ou claws" — facilitar o loop de uso ferramental, exploratório e codificatório; dado input X, o modelo usa as tools em loop até ficar satisfeito e provê a saída.
+- Flags: interpretação "harnesses/claws" = agentes estilo Claude Code — **resolvida implicitamente** pelas respostas seguintes (toolset coding, modos de controle, "como harnesses modernos fazem").
+
+### Q1 — Providers alvo / quem gerencia o provider
+- Asked: Quais providers/modelos concretos suportar primeiro? Foco em endpoints OpenAI-compatible?
+- Captured: Compatível com OpenAI Chat Completions e Anthropic **como referência**, mas o framework **não deve gerenciar o provider diretamente**. O utilizador fica livre para usar o provider que desejar — SDK próprio ou código próprio.
+- Decisão: core 100% provider-agnostic; só um contrato mínimo (mensagens → texto), sem depender de nenhum SDK.
+- Flags: adaptadores prontos opcionais → **resolvido na Q10** (examples/, não dependência).
+
+### Q2 — Contrato do provider (sync/async, streaming)
+- Asked: Contrato síncrono ou assíncrono? Streaming no contrato mínimo?
+- Captured: "async então" — confirmado **async-first**.
+- Decisão: Protocol async único (`async def complete(messages) -> str`). Streaming fora do contrato v1 (extensão futura).
+
+### Q3 — Formato da tool call emulado + parsing
+- Asked: Como o modelo expressa tool call em texto (ReAct / JSON / XML)? Plugável?
+- Captured: Confirmou plugável + JSON default + auto-repair. Contexto adicional: alvo **não** são modelos pequenos — são **SDKs privativos corporativos** proxyando providers grandes sem expor tools use ("OpenRouter corporativo").
+- Decisão: protocolo de tools plugável (par system-prompt-renderer + output-parser); default = bloco JSON; auto-repair devolve erros de parse/validação como observação. Modelos fortes → JSON de primeira é o caso comum.
+
+### Q4 — Condição de parada e saída final
+- Asked: Envelope explícito com discriminador vs. ausência de tool call = final (ReAct)?
+- Captured: "confirmo".
+- Decisão: envelope JSON com `type` — `tool_call` ou `final_answer` (com saída estruturada validada). Loop termina só com `final_answer`. `max_iterations` com política configurável (erro / wrap-up forçado / parcial com status).
+
+### Q5 — API de definição de tools
+- Asked: Decorator + type hints + pydantic, ou zero-dep com schema manual?
+- Captured: "Sim".
+- Decisão: `@tool` em funções async; schema por type hints via pydantic (gera JSON schema do prompt e valida args → alimenta auto-repair). Retorno `str`/serializável; exceções → observação de erro por padrão. Pydantic no core.
+
+### Q6 — Toolset embutido vs. tools só do utilizador
+- Asked: Framework embarca tools prontas? Quais?
+- Captured: "Sim pode incluir".
+- Decisão: core agnóstico; módulo opcional `toolloop.tools` com `bash`, `read_file`, `write_file`, `edit_file`, `grep`/`search`, `list_files`.
+
+### Q7 — Hooks de observabilidade/controle + histórico
+- Asked: Confirmar 3 hooks + histórico completo no resultado?
+- Captured: "Sim, porém importante ter a opção (na chamada ou no instanciamento) de **bypass ou Full Control**".
+- Decisão: hooks `on_step` / `on_tool_call` (veto/modifica/aprova) / `on_tool_result`; histórico completo no resultado. **Modos de controle** bypass ↔ full control, configuráveis na instanciação e/ou no `run()`; níveis intermediários possíveis (ex.: aprovar só tools perigosas).
+- Flags: nome/enum dos modos e granularidade (por tool? categoria?) -> definir na implementação.
+
+### Q8 — Gestão de contexto / tamanho do histórico
+- Asked: v1 sem gestão, truncation, ou compaction?
+- Captured: "como harnesses modernos fazem" + ideia própria: chamada de tool quase **a2a**, separada do contexto principal, retornando só o relevante (tool de escrita não retorna o que escreveu) — "confiança na sub-execução" (usuário duvidava que fosse funcional).
+- Decisão: truncation de tool results antigos + compaction por sumarização (`max_context_tokens` opcional). Ideia a2a **aceita** (é o pattern sub-agent de harnesses reais): (1) toolset retorna compacto por design; (2) safety-net de tamanho por resultado; (3) tool `subagent` com contexto isolado devolvendo só `final_answer`.
+
+### Q9 — Identidade e distribuição (nome, OSS, licença, tooling)
+- Asked: Nome? Open source? Licença?
+- Captured: nome proposto "openloop" (pasta openFlow foi criada errada — openflow já existe no mercado); aberto a sugestões; OSS "que pede apenas créditos".
+- Checagem: PyPI — `openloop` e `toolloop` livres; `open-loop`, `agentloop`, `loopkit`, `pyopenloop` ocupados. GitHub thu-nmrc/openloop = mesmo conceito (colisão).
+- Decisão: **nome = toolloop** (escolha do usuário após ver colisões). **MIT**. Python 3.11+, uv, pytest + provider fake, ruff.
+- Flags: renomear pasta `~/Projects/openFlow` → `~/Projects/toolloop` no scaffold.
+
+### Q10 — Escopo final (paralelismo, CLI, subagent)
+- Asked: (1) tool calls paralelas? (2) CLI no v1? (3) subagent no core v1?
+- Captured: "1. Ok / 2. Ok, no roadmap adicionar um cli básico (init, test, etc) / 3. Sim".
+- Decisão: envelope nasce com `"calls": [...]` (lista) mas v1 executa **sequencialmente** (paralelização no roadmap); v1 **library pura** + `examples/` com adapters; **roadmap: CLI básico** (`init`, `test`); `subagent` **no core v1**.
+
+## Open flags (pending input)
+- ~~Nome/enum e granularidade dos modos de controle~~ -> **resolvido**: `ControlMode.APPROVE | ControlMode.BYPASS` (2 opções, decisão do usuário na aprovação do plano)
+- ~~Renomear pasta~~ -> **executado**: pasta agora é `~/Projects/toolloop` (2026-08-22)

toolloop-0.1.0/examples/anthropic_provider.py

@@ -0,0 +1,37 @@
+"""Provider adapter for the Anthropic Messages API.
+
+Install the SDK with: pip install anthropic
+"""
+
+from __future__ import annotations
+
+from anthropic import AsyncAnthropic
+
+from toolloop import Message
+
+
+class AnthropicProvider:
+    """Implements toolloop's one-method provider contract."""
+
+    def __init__(self, model: str = "claude-sonnet-4-5", max_tokens: int = 4096) -> None:
+        self.client = AsyncAnthropic()
+        self.model = model
+        self.max_tokens = max_tokens
+
+    async def complete(self, messages: list[Message]) -> str:
+        system = "\n\n".join(m.content for m in messages if m.role.value == "system")
+        conversation = [
+            {
+                "role": "assistant" if m.role.value == "assistant" else "user",
+                "content": m.content,
+            }
+            for m in messages
+            if m.role.value != "system"
+        ]
+        response = await self.client.messages.create(
+            model=self.model,
+            max_tokens=self.max_tokens,
+            system=system,
+            messages=conversation,
+        )
+        return "".join(block.text for block in response.content if block.type == "text")