yunta-harness 1.0.2__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (35) hide show
  1. yunta_harness-1.0.2/LICENSE +21 -0
  2. yunta_harness-1.0.2/PKG-INFO +261 -0
  3. yunta_harness-1.0.2/README.md +228 -0
  4. yunta_harness-1.0.2/pyproject.toml +61 -0
  5. yunta_harness-1.0.2/setup.cfg +4 -0
  6. yunta_harness-1.0.2/tests/test_agent.py +225 -0
  7. yunta_harness-1.0.2/tests/test_compact.py +45 -0
  8. yunta_harness-1.0.2/tests/test_delegate.py +150 -0
  9. yunta_harness-1.0.2/tests/test_feedback.py +75 -0
  10. yunta_harness-1.0.2/tests/test_mcp.py +77 -0
  11. yunta_harness-1.0.2/tests/test_memory.py +52 -0
  12. yunta_harness-1.0.2/tests/test_metrics.py +128 -0
  13. yunta_harness-1.0.2/tests/test_provider.py +212 -0
  14. yunta_harness-1.0.2/tests/test_search.py +45 -0
  15. yunta_harness-1.0.2/tests/test_tools.py +75 -0
  16. yunta_harness-1.0.2/yunta/__init__.py +25 -0
  17. yunta_harness-1.0.2/yunta/agent.py +181 -0
  18. yunta_harness-1.0.2/yunta/api.py +123 -0
  19. yunta_harness-1.0.2/yunta/cli.py +103 -0
  20. yunta_harness-1.0.2/yunta/compact.py +28 -0
  21. yunta_harness-1.0.2/yunta/feedback.py +74 -0
  22. yunta_harness-1.0.2/yunta/mcp.py +147 -0
  23. yunta_harness-1.0.2/yunta/provider.py +233 -0
  24. yunta_harness-1.0.2/yunta/tools/__init__.py +44 -0
  25. yunta_harness-1.0.2/yunta/tools/bash.py +32 -0
  26. yunta_harness-1.0.2/yunta/tools/delegate.py +56 -0
  27. yunta_harness-1.0.2/yunta/tools/files.py +86 -0
  28. yunta_harness-1.0.2/yunta/tools/memory.py +116 -0
  29. yunta_harness-1.0.2/yunta/tools/search.py +74 -0
  30. yunta_harness-1.0.2/yunta_harness.egg-info/PKG-INFO +261 -0
  31. yunta_harness-1.0.2/yunta_harness.egg-info/SOURCES.txt +33 -0
  32. yunta_harness-1.0.2/yunta_harness.egg-info/dependency_links.txt +1 -0
  33. yunta_harness-1.0.2/yunta_harness.egg-info/entry_points.txt +2 -0
  34. yunta_harness-1.0.2/yunta_harness.egg-info/requires.txt +6 -0
  35. yunta_harness-1.0.2/yunta_harness.egg-info/top_level.txt +1 -0
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 j0sp0nc3 <beroiza79@gmail.com>
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,261 @@
1
+ Metadata-Version: 2.4
2
+ Name: yunta-harness
3
+ Version: 1.0.2
4
+ Summary: Harness de agente de código para terminal, agnóstico al proveedor del modelo y guiado por especificaciones (SDD)
5
+ Author-email: Jose Ponce <j0sp0nc3@users.noreply.github.com>
6
+ License: MIT
7
+ Project-URL: Homepage, https://github.com/j0sp0nc3/yunta-harness
8
+ Project-URL: Repository, https://github.com/j0sp0nc3/yunta-harness.git
9
+ Project-URL: Documentation, https://github.com/j0sp0nc3/yunta-harness/blob/master/docs/quickstart.md
10
+ Project-URL: Changelog, https://github.com/j0sp0nc3/yunta-harness/blob/master/CHANGELOG.md
11
+ Project-URL: Issues, https://github.com/j0sp0nc3/yunta-harness/issues
12
+ Keywords: ai-agent,coding-agent,harness,cli,sdd,spec-driven-development,litellm,developer-tools,pair-programming
13
+ Classifier: Development Status :: 5 - Production/Stable
14
+ Classifier: Environment :: Console
15
+ Classifier: Intended Audience :: Developers
16
+ Classifier: License :: OSI Approved :: MIT License
17
+ Classifier: Operating System :: OS Independent
18
+ Classifier: Programming Language :: Python :: 3
19
+ Classifier: Programming Language :: Python :: 3.11
20
+ Classifier: Programming Language :: Python :: 3.12
21
+ Classifier: Programming Language :: Python :: 3.13
22
+ Classifier: Topic :: Software Development :: Code Generators
23
+ Classifier: Topic :: Software Development :: Quality Assurance
24
+ Requires-Python: >=3.11
25
+ Description-Content-Type: text/markdown
26
+ License-File: LICENSE
27
+ Requires-Dist: litellm>=1.40.0
28
+ Provides-Extra: dev
29
+ Requires-Dist: pytest>=8.0; extra == "dev"
30
+ Requires-Dist: build>=1.0.0; extra == "dev"
31
+ Requires-Dist: twine>=5.0.0; extra == "dev"
32
+ Dynamic: license-file
33
+
34
+ # Yunta: El Harness para Spec-Driven Development (SDD)
35
+
36
+ [English](README_en.md) | **Español**
37
+
38
+ ![logo](docs/logo.png)
39
+
40
+ **Harness de agente de código para terminal, agnóstico al proveedor del modelo.**
41
+
42
+ *Yunta*: pareja de bueyes unidos para trabajar juntos — tú y el agente, sin importar qué modelo tire del otro lado.
43
+
44
+ ## 🎯 Yunta: El Harness para Spec-Driven Development (SDD)
45
+
46
+ En la metodología **Spec-Driven Development (SDD)**, el código no se genera por intuición o prompts ad-hoc, sino a partir de especificaciones formales y contratos verificables. Yunta actúa como el **harness de ejecución y verificación**:
47
+
48
+ - 📋 **Consumo Estricto de Especificaciones**: Lee `AGENTS.md` y especificaciones del proyecto en cada ciclo como única fuente de verdad.
49
+ - 🔬 **Edición Quirúrgica (`str_replace`)**: Previene la degradación del código mediante reemplazos exactos con validación estricta de unicidad.
50
+ - 🛡️ **Aprobaciones Humanas en Tiempo Real**: Visualización interactiva de `git diff` antes de autorizar cualquier escritura o comando.
51
+ - ⚡ **Prompt Caching Agnóstico**: Permite iterar continuamente contra especificaciones y arquitecturas extensas con hasta un 90% de ahorro en costos y latencia.
52
+ - 🔄 **Bucle Cerrado de Verificación**: El agente valida autónomamente sus cambios contra la suite de pruebas (`pytest`) antes de dar por cerrada la tarea.
53
+
54
+ 👉 **[Ver la Guía y Presentación Completa de Yunta + SDD](docs/sdd.md)**
55
+
56
+ Diseñado desde cero para ser independiente de cualquier proveedor de modelos: el acceso a los LLMs es 100% vía [LiteLLM](https://docs.litellm.ai/docs/), por lo que cualquier proveedor soportado funciona cambiando una variable de entorno.
57
+
58
+ ---
59
+
60
+ ## Características Principales
61
+
62
+ - **Agnóstico al Proveedor**: Conecta OpenAI, Anthropic Claude, Google Gemini, DeepSeek, Groq, o modelos locales vía Ollama/vLLM sin tocar una sola línea de código.
63
+ - **Minimalismo Extremo (~500 líneas)**: Sin frameworks de agentes pesados (sin LangChain ni CrewAI). Código comprensible, auditable y fácil de hackear.
64
+ - **Edición Quirúrgica de Código (`str_replace`)**: Edita fragmentos exactos de archivos validando unicidad de contexto al estilo de Anthropic Claude Code y SWE-bench.
65
+ - **Aprobaciones Humanas con Diff Unificado**: Visualiza exactamente qué líneas se agregarán o eliminarán antes de confirmar la escritura o ejecución.
66
+ - **Prompt Caching Agnóstico**: Inyección de puntos de corte de caché (`cache_control`) para Anthropic Claude y detección automática en OpenAI/DeepSeek/Gemini, ahorrando hasta 90% en tokens de entrada y reduciendo la latencia.
67
+ - **Interrupción Limpia (`Ctrl+C`)**: Cancela un turno largo o llamada a herramienta en cualquier momento sin perder la sesión del REPL ni romper el historial de la conversación.
68
+ - **Soporte Nativo de MCP (Model Context Protocol)**: Conecta servidores MCP externos vía `stdio` JSON-RPC 2.0 sin librerías adicionales.
69
+ - **Memoria Persistente y Aprendizaje Continuo**: Recuerda hechos clave entre sesiones (`.yunta/memory.json`) y acumula lecciones aprendidas (`.yunta/learnings.md`).
70
+ - **Subagentes de Investigación**: Delega tareas de lectura intensiva a subagentes secundarios sin saturar la ventana de contexto principal.
71
+
72
+ ---
73
+
74
+ ## Guía Rápida Paso a Paso
75
+
76
+ 👉 ¿Primera vez usando Yunta? Sigue la **[Guía Paso a Paso Completa (docs/quickstart.md)](docs/quickstart.md)** para aprender desde la configuración del modelo hasta el flujo de edición con diffs y comandos del REPL.
77
+
78
+ ---
79
+
80
+ ## Instalación
81
+
82
+ Requiere Python 3.11 o superior.
83
+
84
+ ```bash
85
+ git clone https://github.com/j0sp0nc3/yunta.git
86
+ cd yunta
87
+ pip install -r requirements.txt
88
+ ```
89
+
90
+ O instala en modo editable:
91
+
92
+ ```bash
93
+ pip install -e .
94
+ ```
95
+
96
+ ---
97
+
98
+ ## Configuración de Modelos
99
+
100
+ Yunta **no tiene modelos por defecto**: tú eliges quién tira del carro configurando tu entorno.
101
+ Consulta la [Matriz de Proveedores Verificados](docs/PROVEEDORES.md) para ver la lista de modelos probados con el script de prueba universal (`scripts/prueba_proveedor.py`).
102
+
103
+ ### Google Gemini
104
+ ```bash
105
+ export LLM_MODEL=gemini/gemini-3.5-flash
106
+ export GEMINI_API_KEY=tu-api-key
107
+ ```
108
+
109
+ ### Anthropic Claude
110
+ ```bash
111
+ export LLM_MODEL=anthropic/claude-3-7-sonnet
112
+ export ANTHROPIC_API_KEY=sk-ant-...
113
+ ```
114
+
115
+ ### OpenAI
116
+ ```bash
117
+ export LLM_MODEL=openai/gpt-4o
118
+ export OPENAI_API_KEY=sk-...
119
+ ```
120
+
121
+ ### DeepSeek / OpenRouter
122
+ ```bash
123
+ export LLM_MODEL=openrouter/deepseek/deepseek-chat
124
+ export LLM_API_KEY=tu-openrouter-key
125
+ ```
126
+
127
+ ### Modelos Locales (Ollama)
128
+ ```bash
129
+ export LLM_MODEL=ollama/llama3.3
130
+ ```
131
+
132
+ ### Endpoints Compatibles con OpenAI (vLLM, LocalAI, etc.)
133
+ ```bash
134
+ export LLM_MODEL=openai/tu-modelo-local
135
+ export LLM_API_BASE=http://localhost:8000/v1
136
+ export LLM_API_KEY=dummy
137
+ ```
138
+
139
+ ---
140
+
141
+ ## Uso y Comandos
142
+
143
+ Inicia la sesión interactiva:
144
+
145
+ ```bash
146
+ python main.py
147
+ # O si lo instalaste con pip install -e .:
148
+ yunta
149
+ ```
150
+
151
+ ### Comandos del REPL
152
+ - `/clear`: Limpia el historial de mensajes de la sesión actual.
153
+ - `/tokens`: Muestra el consumo acumulado de tokens (entrada y salida) de la sesión.
154
+ - `/exit`: Guarda lecciones aprendidas en `.yunta/learnings.md` y finaliza la sesión.
155
+ - `Ctrl+C`: Interrumpe el turno en curso de forma limpia y regresa al prompt `> ` sin tumbar la sesión.
156
+
157
+ ---
158
+
159
+ ---
160
+
161
+ ## Uso como Librería en Python (API v1.0)
162
+
163
+ A partir de la versión 1.0.0, puedes importar y embeber a Yunta directamente en tus scripts o aplicaciones:
164
+
165
+ ```python
166
+ from yunta import Agent, LiteLLMProvider, FeedbackStore
167
+
168
+ # Inicializa el proveedor usando la variable de entorno LLM_MODEL
169
+ provider = LiteLLMProvider(system="Eres un asistente técnico conciso.")
170
+
171
+ # Instancia el agente con aprobaciones automáticas o personalizadas
172
+ agent = Agent(provider=provider, system=provider.system, confirm=lambda name, detail: True)
173
+
174
+ # Envía un mensaje y recibe la respuesta estructurada
175
+ respuesta = agent.send("Lista los archivos en el directorio actual")
176
+ print(respuesta)
177
+ ```
178
+
179
+ ---
180
+
181
+ ## Detalles de Implementación para el Usuario
182
+
183
+ ### 1. Contexto de Proyecto (`AGENTS.md`)
184
+ Si creas un archivo `AGENTS.md` en la raíz de tu proyecto, Yunta lo leerá e inyectará automáticamente en su `system prompt`. Úsalo para definir reglas inviolables, comandos de test o convenciones de tu equipo.
185
+
186
+ ### 2. Edición de Archivos y Aprobaciones
187
+ Cuando Yunta decida modificar o escribir un archivo:
188
+ - **`str_replace`**: Reemplaza fragmentos específicos. Si la cadena a reemplazar es ambigua (aparece más de una vez), fallará pidiendo más contexto.
189
+ - **Previsualización de Diffs**: Si la herramienta requiere aprobación, verás un diff unificado estilo Git en la consola antes de pulsar `y` (confirmar) o `n` (rechazar).
190
+
191
+ ### 3. Memoria Persistente entre Sesiones
192
+ El agente cuenta con las herramientas `remember` y `recall` para almacenar notas, decisiones de arquitectura o preferencias en `.yunta/memory.json`.
193
+
194
+ ### 4. Servidores MCP (Model Context Protocol)
195
+ Puedes conectar herramientas de servidores MCP locales (`stdio`) creando el archivo `.yunta/mcp.json`:
196
+
197
+ ```json
198
+ {
199
+ "mcpServers": {
200
+ "weather": {
201
+ "command": "python",
202
+ "args": ["servidores/weather_server.py"]
203
+ }
204
+ }
205
+ }
206
+ ```
207
+ Las herramientas descubiertas se registrarán como `mcp__weather__<nombre_tool>`.
208
+
209
+ ### 5. Creación de Herramientas Propias
210
+ Para agregar herramientas al agente, crea un archivo en `yunta/tools/` y usa el decorador `@registry.register`:
211
+
212
+ ```python
213
+ from . import _parse, registry
214
+
215
+ @registry.register(
216
+ "mi_tool",
217
+ "Descripción clara de la herramienta para el modelo.",
218
+ {
219
+ "type": "object",
220
+ "properties": {
221
+ "parametro": {"type": "string", "description": "Texto de entrada"}
222
+ },
223
+ "required": ["parametro"]
224
+ },
225
+ requires_approval=False,
226
+ )
227
+ def mi_tool(raw: str) -> str:
228
+ args = _parse(raw)
229
+ return f"Resultado procesado: {args['parametro']}"
230
+ ```
231
+
232
+ ---
233
+
234
+ ## Arquitectura
235
+
236
+ Yunta está organizado de forma modular, limpia y compacta:
237
+
238
+ ```
239
+ main.py -> Punto de entrada y REPL de consola
240
+ yunta/
241
+ api.py -> Tipos canónicos neutrales (Message, Block, ToolDef, Response)
242
+ provider.py -> Capa de conexión LiteLLM (streaming, reintentos 429/503)
243
+ agent.py -> Bucle iterativo de turnos, approvals de diffs y Ctrl+C
244
+ compact.py -> Compactación de contexto (SlidingWindow)
245
+ feedback.py -> Auto-feedback de lecciones (.yunta/learnings.md)
246
+ mcp.py -> Cliente nativo JSON-RPC 2.0 stdio MCP
247
+ tools/ -> Registro y herramientas nativas
248
+ files.py -> read_file, write_file, str_replace (SWE-bench style)
249
+ bash.py -> Ejecución de comandos en subprocess con timeout
250
+ search.py -> glob y grep dentro del repositorio
251
+ memory.py -> remember y recall (.yunta/memory.json)
252
+ delegate.py -> delegate_research con subagente secundario
253
+ ```
254
+
255
+ Para una explicación técnica detallada del diseño, consulta la [Documentación de Arquitectura Completa](docs/architecture.md).
256
+
257
+ ---
258
+
259
+ ## Licencia
260
+
261
+ Este proyecto está bajo la [Licencia MIT](LICENSE) - Copyright (c) 2026 j0sp0nc3 <beroiza79@gmail.com>.
@@ -0,0 +1,228 @@
1
+ # Yunta: El Harness para Spec-Driven Development (SDD)
2
+
3
+ [English](README_en.md) | **Español**
4
+
5
+ ![logo](docs/logo.png)
6
+
7
+ **Harness de agente de código para terminal, agnóstico al proveedor del modelo.**
8
+
9
+ *Yunta*: pareja de bueyes unidos para trabajar juntos — tú y el agente, sin importar qué modelo tire del otro lado.
10
+
11
+ ## 🎯 Yunta: El Harness para Spec-Driven Development (SDD)
12
+
13
+ En la metodología **Spec-Driven Development (SDD)**, el código no se genera por intuición o prompts ad-hoc, sino a partir de especificaciones formales y contratos verificables. Yunta actúa como el **harness de ejecución y verificación**:
14
+
15
+ - 📋 **Consumo Estricto de Especificaciones**: Lee `AGENTS.md` y especificaciones del proyecto en cada ciclo como única fuente de verdad.
16
+ - 🔬 **Edición Quirúrgica (`str_replace`)**: Previene la degradación del código mediante reemplazos exactos con validación estricta de unicidad.
17
+ - 🛡️ **Aprobaciones Humanas en Tiempo Real**: Visualización interactiva de `git diff` antes de autorizar cualquier escritura o comando.
18
+ - ⚡ **Prompt Caching Agnóstico**: Permite iterar continuamente contra especificaciones y arquitecturas extensas con hasta un 90% de ahorro en costos y latencia.
19
+ - 🔄 **Bucle Cerrado de Verificación**: El agente valida autónomamente sus cambios contra la suite de pruebas (`pytest`) antes de dar por cerrada la tarea.
20
+
21
+ 👉 **[Ver la Guía y Presentación Completa de Yunta + SDD](docs/sdd.md)**
22
+
23
+ Diseñado desde cero para ser independiente de cualquier proveedor de modelos: el acceso a los LLMs es 100% vía [LiteLLM](https://docs.litellm.ai/docs/), por lo que cualquier proveedor soportado funciona cambiando una variable de entorno.
24
+
25
+ ---
26
+
27
+ ## Características Principales
28
+
29
+ - **Agnóstico al Proveedor**: Conecta OpenAI, Anthropic Claude, Google Gemini, DeepSeek, Groq, o modelos locales vía Ollama/vLLM sin tocar una sola línea de código.
30
+ - **Minimalismo Extremo (~500 líneas)**: Sin frameworks de agentes pesados (sin LangChain ni CrewAI). Código comprensible, auditable y fácil de hackear.
31
+ - **Edición Quirúrgica de Código (`str_replace`)**: Edita fragmentos exactos de archivos validando unicidad de contexto al estilo de Anthropic Claude Code y SWE-bench.
32
+ - **Aprobaciones Humanas con Diff Unificado**: Visualiza exactamente qué líneas se agregarán o eliminarán antes de confirmar la escritura o ejecución.
33
+ - **Prompt Caching Agnóstico**: Inyección de puntos de corte de caché (`cache_control`) para Anthropic Claude y detección automática en OpenAI/DeepSeek/Gemini, ahorrando hasta 90% en tokens de entrada y reduciendo la latencia.
34
+ - **Interrupción Limpia (`Ctrl+C`)**: Cancela un turno largo o llamada a herramienta en cualquier momento sin perder la sesión del REPL ni romper el historial de la conversación.
35
+ - **Soporte Nativo de MCP (Model Context Protocol)**: Conecta servidores MCP externos vía `stdio` JSON-RPC 2.0 sin librerías adicionales.
36
+ - **Memoria Persistente y Aprendizaje Continuo**: Recuerda hechos clave entre sesiones (`.yunta/memory.json`) y acumula lecciones aprendidas (`.yunta/learnings.md`).
37
+ - **Subagentes de Investigación**: Delega tareas de lectura intensiva a subagentes secundarios sin saturar la ventana de contexto principal.
38
+
39
+ ---
40
+
41
+ ## Guía Rápida Paso a Paso
42
+
43
+ 👉 ¿Primera vez usando Yunta? Sigue la **[Guía Paso a Paso Completa (docs/quickstart.md)](docs/quickstart.md)** para aprender desde la configuración del modelo hasta el flujo de edición con diffs y comandos del REPL.
44
+
45
+ ---
46
+
47
+ ## Instalación
48
+
49
+ Requiere Python 3.11 o superior.
50
+
51
+ ```bash
52
+ git clone https://github.com/j0sp0nc3/yunta.git
53
+ cd yunta
54
+ pip install -r requirements.txt
55
+ ```
56
+
57
+ O instala en modo editable:
58
+
59
+ ```bash
60
+ pip install -e .
61
+ ```
62
+
63
+ ---
64
+
65
+ ## Configuración de Modelos
66
+
67
+ Yunta **no tiene modelos por defecto**: tú eliges quién tira del carro configurando tu entorno.
68
+ Consulta la [Matriz de Proveedores Verificados](docs/PROVEEDORES.md) para ver la lista de modelos probados con el script de prueba universal (`scripts/prueba_proveedor.py`).
69
+
70
+ ### Google Gemini
71
+ ```bash
72
+ export LLM_MODEL=gemini/gemini-3.5-flash
73
+ export GEMINI_API_KEY=tu-api-key
74
+ ```
75
+
76
+ ### Anthropic Claude
77
+ ```bash
78
+ export LLM_MODEL=anthropic/claude-3-7-sonnet
79
+ export ANTHROPIC_API_KEY=sk-ant-...
80
+ ```
81
+
82
+ ### OpenAI
83
+ ```bash
84
+ export LLM_MODEL=openai/gpt-4o
85
+ export OPENAI_API_KEY=sk-...
86
+ ```
87
+
88
+ ### DeepSeek / OpenRouter
89
+ ```bash
90
+ export LLM_MODEL=openrouter/deepseek/deepseek-chat
91
+ export LLM_API_KEY=tu-openrouter-key
92
+ ```
93
+
94
+ ### Modelos Locales (Ollama)
95
+ ```bash
96
+ export LLM_MODEL=ollama/llama3.3
97
+ ```
98
+
99
+ ### Endpoints Compatibles con OpenAI (vLLM, LocalAI, etc.)
100
+ ```bash
101
+ export LLM_MODEL=openai/tu-modelo-local
102
+ export LLM_API_BASE=http://localhost:8000/v1
103
+ export LLM_API_KEY=dummy
104
+ ```
105
+
106
+ ---
107
+
108
+ ## Uso y Comandos
109
+
110
+ Inicia la sesión interactiva:
111
+
112
+ ```bash
113
+ python main.py
114
+ # O si lo instalaste con pip install -e .:
115
+ yunta
116
+ ```
117
+
118
+ ### Comandos del REPL
119
+ - `/clear`: Limpia el historial de mensajes de la sesión actual.
120
+ - `/tokens`: Muestra el consumo acumulado de tokens (entrada y salida) de la sesión.
121
+ - `/exit`: Guarda lecciones aprendidas en `.yunta/learnings.md` y finaliza la sesión.
122
+ - `Ctrl+C`: Interrumpe el turno en curso de forma limpia y regresa al prompt `> ` sin tumbar la sesión.
123
+
124
+ ---
125
+
126
+ ---
127
+
128
+ ## Uso como Librería en Python (API v1.0)
129
+
130
+ A partir de la versión 1.0.0, puedes importar y embeber a Yunta directamente en tus scripts o aplicaciones:
131
+
132
+ ```python
133
+ from yunta import Agent, LiteLLMProvider, FeedbackStore
134
+
135
+ # Inicializa el proveedor usando la variable de entorno LLM_MODEL
136
+ provider = LiteLLMProvider(system="Eres un asistente técnico conciso.")
137
+
138
+ # Instancia el agente con aprobaciones automáticas o personalizadas
139
+ agent = Agent(provider=provider, system=provider.system, confirm=lambda name, detail: True)
140
+
141
+ # Envía un mensaje y recibe la respuesta estructurada
142
+ respuesta = agent.send("Lista los archivos en el directorio actual")
143
+ print(respuesta)
144
+ ```
145
+
146
+ ---
147
+
148
+ ## Detalles de Implementación para el Usuario
149
+
150
+ ### 1. Contexto de Proyecto (`AGENTS.md`)
151
+ Si creas un archivo `AGENTS.md` en la raíz de tu proyecto, Yunta lo leerá e inyectará automáticamente en su `system prompt`. Úsalo para definir reglas inviolables, comandos de test o convenciones de tu equipo.
152
+
153
+ ### 2. Edición de Archivos y Aprobaciones
154
+ Cuando Yunta decida modificar o escribir un archivo:
155
+ - **`str_replace`**: Reemplaza fragmentos específicos. Si la cadena a reemplazar es ambigua (aparece más de una vez), fallará pidiendo más contexto.
156
+ - **Previsualización de Diffs**: Si la herramienta requiere aprobación, verás un diff unificado estilo Git en la consola antes de pulsar `y` (confirmar) o `n` (rechazar).
157
+
158
+ ### 3. Memoria Persistente entre Sesiones
159
+ El agente cuenta con las herramientas `remember` y `recall` para almacenar notas, decisiones de arquitectura o preferencias en `.yunta/memory.json`.
160
+
161
+ ### 4. Servidores MCP (Model Context Protocol)
162
+ Puedes conectar herramientas de servidores MCP locales (`stdio`) creando el archivo `.yunta/mcp.json`:
163
+
164
+ ```json
165
+ {
166
+ "mcpServers": {
167
+ "weather": {
168
+ "command": "python",
169
+ "args": ["servidores/weather_server.py"]
170
+ }
171
+ }
172
+ }
173
+ ```
174
+ Las herramientas descubiertas se registrarán como `mcp__weather__<nombre_tool>`.
175
+
176
+ ### 5. Creación de Herramientas Propias
177
+ Para agregar herramientas al agente, crea un archivo en `yunta/tools/` y usa el decorador `@registry.register`:
178
+
179
+ ```python
180
+ from . import _parse, registry
181
+
182
+ @registry.register(
183
+ "mi_tool",
184
+ "Descripción clara de la herramienta para el modelo.",
185
+ {
186
+ "type": "object",
187
+ "properties": {
188
+ "parametro": {"type": "string", "description": "Texto de entrada"}
189
+ },
190
+ "required": ["parametro"]
191
+ },
192
+ requires_approval=False,
193
+ )
194
+ def mi_tool(raw: str) -> str:
195
+ args = _parse(raw)
196
+ return f"Resultado procesado: {args['parametro']}"
197
+ ```
198
+
199
+ ---
200
+
201
+ ## Arquitectura
202
+
203
+ Yunta está organizado de forma modular, limpia y compacta:
204
+
205
+ ```
206
+ main.py -> Punto de entrada y REPL de consola
207
+ yunta/
208
+ api.py -> Tipos canónicos neutrales (Message, Block, ToolDef, Response)
209
+ provider.py -> Capa de conexión LiteLLM (streaming, reintentos 429/503)
210
+ agent.py -> Bucle iterativo de turnos, approvals de diffs y Ctrl+C
211
+ compact.py -> Compactación de contexto (SlidingWindow)
212
+ feedback.py -> Auto-feedback de lecciones (.yunta/learnings.md)
213
+ mcp.py -> Cliente nativo JSON-RPC 2.0 stdio MCP
214
+ tools/ -> Registro y herramientas nativas
215
+ files.py -> read_file, write_file, str_replace (SWE-bench style)
216
+ bash.py -> Ejecución de comandos en subprocess con timeout
217
+ search.py -> glob y grep dentro del repositorio
218
+ memory.py -> remember y recall (.yunta/memory.json)
219
+ delegate.py -> delegate_research con subagente secundario
220
+ ```
221
+
222
+ Para una explicación técnica detallada del diseño, consulta la [Documentación de Arquitectura Completa](docs/architecture.md).
223
+
224
+ ---
225
+
226
+ ## Licencia
227
+
228
+ Este proyecto está bajo la [Licencia MIT](LICENSE) - Copyright (c) 2026 j0sp0nc3 <beroiza79@gmail.com>.
@@ -0,0 +1,61 @@
1
+ [project]
2
+ name = "yunta-harness"
3
+ version = "1.0.2"
4
+ description = "Harness de agente de código para terminal, agnóstico al proveedor del modelo y guiado por especificaciones (SDD)"
5
+ readme = "README.md"
6
+ requires-python = ">=3.11"
7
+ license = { text = "MIT" }
8
+ authors = [
9
+ { name = "Jose Ponce", email = "j0sp0nc3@users.noreply.github.com" }
10
+ ]
11
+ keywords = [
12
+ "ai-agent",
13
+ "coding-agent",
14
+ "harness",
15
+ "cli",
16
+ "sdd",
17
+ "spec-driven-development",
18
+ "litellm",
19
+ "developer-tools",
20
+ "pair-programming"
21
+ ]
22
+ classifiers = [
23
+ "Development Status :: 5 - Production/Stable",
24
+ "Environment :: Console",
25
+ "Intended Audience :: Developers",
26
+ "License :: OSI Approved :: MIT License",
27
+ "Operating System :: OS Independent",
28
+ "Programming Language :: Python :: 3",
29
+ "Programming Language :: Python :: 3.11",
30
+ "Programming Language :: Python :: 3.12",
31
+ "Programming Language :: Python :: 3.13",
32
+ "Topic :: Software Development :: Code Generators",
33
+ "Topic :: Software Development :: Quality Assurance",
34
+ ]
35
+ dependencies = [
36
+ "litellm>=1.40.0",
37
+ ]
38
+
39
+ [project.scripts]
40
+ yunta = "yunta.cli:main"
41
+
42
+ [project.urls]
43
+ Homepage = "https://github.com/j0sp0nc3/yunta-harness"
44
+ Repository = "https://github.com/j0sp0nc3/yunta-harness.git"
45
+ Documentation = "https://github.com/j0sp0nc3/yunta-harness/blob/master/docs/quickstart.md"
46
+ Changelog = "https://github.com/j0sp0nc3/yunta-harness/blob/master/CHANGELOG.md"
47
+ Issues = "https://github.com/j0sp0nc3/yunta-harness/issues"
48
+
49
+ [project.optional-dependencies]
50
+ dev = [
51
+ "pytest>=8.0",
52
+ "build>=1.0.0",
53
+ "twine>=5.0.0",
54
+ ]
55
+
56
+ [build-system]
57
+ requires = ["setuptools>=68"]
58
+ build-backend = "setuptools.build_meta"
59
+
60
+ [tool.setuptools.packages.find]
61
+ include = ["yunta*"]
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+