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.
- yunta_harness-1.0.2/LICENSE +21 -0
- yunta_harness-1.0.2/PKG-INFO +261 -0
- yunta_harness-1.0.2/README.md +228 -0
- yunta_harness-1.0.2/pyproject.toml +61 -0
- yunta_harness-1.0.2/setup.cfg +4 -0
- yunta_harness-1.0.2/tests/test_agent.py +225 -0
- yunta_harness-1.0.2/tests/test_compact.py +45 -0
- yunta_harness-1.0.2/tests/test_delegate.py +150 -0
- yunta_harness-1.0.2/tests/test_feedback.py +75 -0
- yunta_harness-1.0.2/tests/test_mcp.py +77 -0
- yunta_harness-1.0.2/tests/test_memory.py +52 -0
- yunta_harness-1.0.2/tests/test_metrics.py +128 -0
- yunta_harness-1.0.2/tests/test_provider.py +212 -0
- yunta_harness-1.0.2/tests/test_search.py +45 -0
- yunta_harness-1.0.2/tests/test_tools.py +75 -0
- yunta_harness-1.0.2/yunta/__init__.py +25 -0
- yunta_harness-1.0.2/yunta/agent.py +181 -0
- yunta_harness-1.0.2/yunta/api.py +123 -0
- yunta_harness-1.0.2/yunta/cli.py +103 -0
- yunta_harness-1.0.2/yunta/compact.py +28 -0
- yunta_harness-1.0.2/yunta/feedback.py +74 -0
- yunta_harness-1.0.2/yunta/mcp.py +147 -0
- yunta_harness-1.0.2/yunta/provider.py +233 -0
- yunta_harness-1.0.2/yunta/tools/__init__.py +44 -0
- yunta_harness-1.0.2/yunta/tools/bash.py +32 -0
- yunta_harness-1.0.2/yunta/tools/delegate.py +56 -0
- yunta_harness-1.0.2/yunta/tools/files.py +86 -0
- yunta_harness-1.0.2/yunta/tools/memory.py +116 -0
- yunta_harness-1.0.2/yunta/tools/search.py +74 -0
- yunta_harness-1.0.2/yunta_harness.egg-info/PKG-INFO +261 -0
- yunta_harness-1.0.2/yunta_harness.egg-info/SOURCES.txt +33 -0
- yunta_harness-1.0.2/yunta_harness.egg-info/dependency_links.txt +1 -0
- yunta_harness-1.0.2/yunta_harness.egg-info/entry_points.txt +2 -0
- yunta_harness-1.0.2/yunta_harness.egg-info/requires.txt +6 -0
- 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
|
+

|
|
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
|
+

|
|
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*"]
|