Skip to content

AGENTS.md

Latest commit

 

History

History
557 lines (399 loc) · 18.2 KB

AGENTS.md

File metadata and controls

557 lines (399 loc) · 18.2 KB

AGENTS.md

Manual de operación del repositorio kline_timestamp para agentes LLM y humanos.

1. Purpose

Este archivo describe cómo operar, mantener y contribuir al repositorio kline_timestamp. Está pensado para que tanto agentes automatizados como desarrolladores humanos puedan trabajar de forma autónoma con información verificable.

2. Repo facts (auto-detected)

Identidad del paquete

  • Distribution name (PyPI): kline_timestamp
  • Import name: kline_timestamp (flat layout, paquete en kline_timestamp/)
  • Versión actual: 0.3.0 (hardcoded en setup.py:20)
  • Gestión de versión: manual, string literal en setup.py. No usa SCM ni version.py.
  • Packaging: setup.py clásico (setuptools). No hay pyproject.toml ni setup.cfg.
  • Licencia: MIT
  • Python requerido: >=3.9

Dependencias de instalación

  • pandas>=2.3.0,<3.0
  • pytz>=2024.1

Declaradas en requirements.txt y leídas por setup.py.

Estructura del repo

kline_timestamp/          ← raíz del repo
├── kline_timestamp/      ← paquete importable
│   ├── __init__.py       ← re-exporta KlineTimestamp
│   └── kline_timestamp.py ← clase principal (única)
├── examples/
│   └── kline_timestamp_basic.ipynb
├── dist/                 ← artefactos de build (whl + tar.gz 0.2.0)
├── kline_timestamp.egg-info/
├── setup.py
├── requirements.txt
├── MANIFEST.in
├── deploy.sh             ← script de build + upload a PyPI
├── README.md
├── CHANGELOG.md
├── LICENSE
└── .gitignore
  • Layout: flat (no src/).
  • Módulo único: toda la lógica está en kline_timestamp/kline_timestamp.py.
  • Clase principal: KlineTimestamp - dataclass frozen, inmutable.
  • Intervalos soportados: 1m, 3m, 5m, 15m, 30m, 1h, 2h, 4h, 6h, 8h, 12h, 1d, 3d, 1w (fijos) + 1M (mensual, variable).
  • No hay: tests, linters, type-checkers, CI, docs (Sphinx/MkDocs), ni entrypoints CLI.

Tooling de desarrollo

  • Test runner: no detectado. No hay directorio tests/ ni configuración de pytest/unittest.
  • Linters/formatters: no detectados. No hay ruff.toml, .flake8, pyproject.toml con config, etc.
  • Type checker: no detectado. No hay config de mypy/pyright.
  • CI: no detectado. No hay .github/workflows/ ni .gitlab-ci.yml.
  • Gestión de deps: pip directo (requirements.txt). No usa poetry/pdm/uv.

Documentación

  • No hay Sphinx ni MkDocs.
  • La documentación es el README.md y el notebook de ejemplo.

Git topology

  • Remotes:
    • github -> git@github.com:nand0san/KlineTimestamp.git
    • nas -> ssh://ffad@192.168.89.201/.../kline_timestamp (NAS local)
  • Rama actual: master (tracking nas/master)
  • Otras ramas locales: github (apunta a commit 631675a, release 0.2.0)
  • Ramas remotas: github/github, nas/github, nas/master
  • Remote HEAD: no determinable (el remote origin no existe; hay github y nas)
  • Tags: ninguno
  • Convención de ramas: no formalizada. master es la rama de desarrollo principal.
  • Convención de commits: mensajes cortos en español/inglés, sin formato estricto.

PyPI status

  • Publicado: sí, kline_timestamp versión 0.2.0 (2025-11-23)
  • Summary: "KlineTimestamp is a Python library designed to efficiently handle timestamps within discrete time intervals (klines/candlesticks), commonly used in financial data analysis."
  • Home page: https://github.com/nand0san/kline_timestamp
  • Author: nand0san

3. API reference (for agents)

Referencia rapida para que un agente pueda usar kline_timestamp sin leer el codigo fuente.

Import

from kline_timestamp import KlineTimestamp

Constructor

KlineTimestamp(timestamp_ms: int, interval: str, tzinfo: str | pytz.BaseTzInfo = "UTC")
  • timestamp_ms: epoch en milisegundos (UTC). Debe ser int (no float).
  • interval: intervalo de la vela. Case-insensitive excepto 1M (mensual).
  • tzinfo: zona horaria para presentacion. No afecta identidad ni comparaciones.

Intervalos validos

Fijos: 1m, 3m, 5m, 15m, 30m, 1h, 2h, 4h, 6h, 8h, 12h, 1d, 3d, 1w

Variable: 1M (mensual, 28-31 dias segun mes). Case-sensitive: 1M != 1m.

Atributos de instancia

  • kt.open - primer ms de la vela (epoch ms UTC)
  • kt.close - ultimo ms de la vela (epoch ms UTC)
  • kt.tick_ms - duracion de la vela en ms (variable para 1M)
  • kt.interval - intervalo normalizado (str)
  • kt.tzinfo - zona horaria (pytz.BaseTzInfo)
  • kt.timestamp_ms - timestamp original pasado al constructor

Metodos

# Conversiones
kt.to_datetime()            # -> datetime.datetime (tz-aware)
kt.to_pandas_timestamp()    # -> pd.Timestamp (tz-aware)

# Transformaciones inmutables (devuelven nueva instancia)
kt.with_timezone("UTC")     # cambiar zona horaria
kt.with_interval("15m")     # cambiar intervalo (re-snap)

# Navegacion
kt.next()                   # siguiente vela contigua
kt.prev()                   # vela anterior contigua

Operadores

# Aritmetica
kt + timedelta(hours=1)     # -> KlineTimestamp desplazado
kt - timedelta(hours=1)     # -> KlineTimestamp desplazado
kt - kt_other               # -> timedelta (diferencia entre opens)
timedelta(...) + kt          # -> KlineTimestamp (__radd__)

# Comparaciones (por (open, tick_ms), timezone ignorado)
kt == kt_other
kt < kt_other
kt > kt_other
kt <= kt_other
kt >= kt_other

# Hash (consistente con __eq__)
hash(kt)                     # hash((open, tick_ms))

Notas para 1M (mensual)

  • tick_ms varia: febrero bisiesto = 2986400000, marzo = 3186400000, etc.
  • next()/prev() navegan por meses calendario (no suman tick_ms fijo).
  • kt + timedelta(days=15) re-snap al mes del timestamp resultante.
  • Dos klines mensuales del mismo mes son iguales independientemente del timestamp original.

Ejemplo de uso programatico

from kline_timestamp import KlineTimestamp
from datetime import timedelta

# Crear vela de 1 hora
kt = KlineTimestamp(1633036800000, "1h", "Europe/Madrid")
print(kt.open, kt.close, kt.to_datetime())

# Iterar 5 velas hacia adelante
current = kt
for _ in range(5):
    current = current.next()
    print(current.to_datetime())

# Vela mensual
kt_month = KlineTimestamp(1709251200000, "1M", "UTC")
print(kt_month.to_datetime())        # 2024-03-01
print(kt_month.next().to_datetime()) # 2024-04-01
print(kt_month.prev().to_datetime()) # 2024-02-01

# Diferencia temporal
delta = kt_month - kt_month.prev()
print(delta.days)  # 29 (febrero 2024, bisiesto)

Errores comunes

  • Pasar float como timestamp_ms -> TypeError
  • Pasar "1M" esperando minuto -> es mensual. Usar "1m" para minuto.
  • Comparar klines de distinto intervalo con mismo open: no son iguales (distinto tick_ms).

4. Coding conventions

3.1 Idiomas

Elemento Idioma Ejemplo
Módulos, clases, funciones, métodos English KlineTimestamp, with_timezone()
Variables English, autoexplicativas open_ts, tick_ms
Comentarios Español, mínimos # Normaliza el intervalo
Docstrings Español, concisos """Retorna la siguiente vela..."""

3.2 Docstrings

  • Formato: NumPy style (napoleon-compatible), para futura integración con Sphinx.
  • Resumen en 1 línea.
  • Parameters / Returns / Raises cuando aplique.
  • Type hints en firmas (from __future__ import annotations ya presente).
  • Describir contratos (pre/post), no repetir el código.

3.3 Estilo y arquitectura

  • Clase principal inmutable (@dataclass(frozen=True)). Toda mutación retorna instancia nueva.
  • __post_init__ para validación y cálculo de campos derivados.
  • Separación clara: identidad lógica (open, interval) vs. presentación (timezone).
  • Excepciones explícitas con mensajes útiles (ValueError, TypeError).
  • No hay logging actualmente.

3.4 Imports y organización

  • Orden: stdlib -> third-party (pandas, pytz) -> local.
  • Un solo módulo de lógica: kline_timestamp.py. No hay riesgo de imports circulares.
  • Nuevos módulos: colocar en kline_timestamp/ y exportar desde __init__.py.

3.5 Type hints

  • from __future__ import annotations habilitado.
  • Usar Union, ClassVar, Dict de typing (compatibilidad 3.9).
  • Si se sube el mínimo a 3.10+, preferir X | Y nativo.

5. Project layout

kline_timestamp/                  ← paquete importable
    __init__.py                   ← exporta KlineTimestamp
    kline_timestamp.py            ← clase KlineTimestamp (única)
examples/
    kline_timestamp_basic.ipynb   ← notebook de ejemplo
setup.py                          ← metadata + build
requirements.txt                  ← deps de instalación
MANIFEST.in                       ← archivos extra en sdist
deploy.sh                         ← build + twine upload
CHANGELOG.md                      ← changelog (Keep a Changelog)
README.md                         ← docs principal
LICENSE                           ← MIT

6. Setup & run

Crear entorno virtual

python3 -m venv .venv
source .venv/bin/activate

Instalar en modo editable

pip install -e .

Esto instala kline_timestamp + dependencias (pandas, pytz).

Instalar dependencias sin modo editable

pip install -r requirements.txt

Ejecutar ejemplo rápido

python -m kline_timestamp.kline_timestamp

Ejecuta el bloque if __name__ == "__main__" con un ejemplo manual.

Variables de entorno

No se detectan variables de entorno requeridas.

7. Tests / lint / type-check

Estado actual

No existe infraestructura de testing, linting ni type-checking en el repo.

Comandos (si se añadieran)

# Tests (futuro)
pytest tests/ -v

# Lint (futuro)
ruff check .

# Format (futuro)
ruff format .

# Type-check (futuro)
mypy kline_timestamp/

Definition of done (propuesta)

Un cambio está listo cuando:

  1. Pasa todos los tests (cuando existan).
  2. No introduce errores de lint/type.
  3. Docstrings actualizados si la API pública cambió.

8. Documentation

Estado actual

  • Herramienta de docs: ninguna (no hay Sphinx ni MkDocs).
  • Documentación existente: README.md + CHANGELOG.md + notebook de ejemplo.
  • Docstrings: presentes en la clase principal, estilo corto en español.

Convenciones

  • Docstrings NumPy style para compatibilidad futura con Sphinx + napoleon.
  • CHANGELOG.md sigue Keep a Changelog + SemVer.
  • Ejemplos en examples/ como notebooks Jupyter.

9. PyPI status

Campo Valor
Distribution name kline_timestamp
Import name kline_timestamp
Publicado en PyPI Sí
Última versión 0.2.0 (2025-11-23)
URL PyPI https://pypi.org/project/kline_timestamp/
Home page https://github.com/nand0san/kline_timestamp

Flujo de release actual

# 1. Actualizar version en setup.py
# 2. Actualizar CHANGELOG.md
# 3. Commit
git add setup.py CHANGELOG.md
git commit -m "release: vX.Y.Z"

# 4. Tag (OBLIGATORIO, sincronizado con la version de setup.py y PyPI)
git tag vX.Y.Z

# 5. Build y upload
./deploy.sh    # ejecuta: rm -rf dist/ build/ && python -m build && twine upload dist/*

# 6. Push con tags
git push nas master --tags

Requiere:

  • build y twine instalados.
  • Token de PyPI configurado (.pypirc o variable de entorno).

Tags de version (OBLIGATORIO)

  • Todo commit de release debe llevar un tag con formato vX.Y.Z (SemVer).
  • El tag debe coincidir exactamente con la version declarada en setup.py:20.
  • Si se publica en PyPI, la version del tag, setup.py y PyPI deben ser identicas.
  • Crear el tag antes de hacer push: git tag vX.Y.Z.
  • Push de tags: git push nas master --tags y git push github github --tags.
  • No crear tags sin commit de release asociado.
  • No publicar en PyPI sin tag.

10. Git workflow

Remotes

Remote URL Uso
github git@github.com:nand0san/KlineTimestamp.git Repositorio público
nas ssh://ffad@192.168.89.201/.../kline_timestamp Backup/NAS privado

Ramas

  • master - rama principal de desarrollo (tracking nas/master).
  • github - rama de release publico (apunta a release 0.2.0).
  • No hay rama main ni dev locales.

Flujo de trabajo

# Crear feature branch desde master
git checkout master
git pull nas master
git checkout -b feature/mi-cambio

# Trabajar, commit
git add <archivos>
git commit -m "descripcion corta del cambio"

# Mergear a master
git checkout master
git merge feature/mi-cambio

# Push a NAS
git push nas master

# Push a GitHub (cuando sea release)
git push github master:github

Convención de commits

  • Mensajes cortos, imperativos.
  • Idioma: español o inglés (historial mixto).
  • Scope opcional: feat:, fix:, docs: (no formalizado, pero recomendado).
  • Commits de release: deben ir acompañados de un tag vX.Y.Z (ver seccion 9).

11. GitHub publishing

Rama dedicada

La rama local github (tracking github/github) es la unica rama que se publica en el remote github (git@github.com:nand0san/KlineTimestamp.git). No se hace push de master ni de feature branches al remote de GitHub.

Squash obligatorio

Todos los commits que lleguen a la rama github deben ser squash merges desde master:

git checkout github
git merge --squash master
git commit -m "descripcion publica del cambio"
git tag vX.Y.Z   # sincronizado con setup.py y PyPI
git push github github --tags

Esto garantiza que el historial interno de desarrollo (commits intermedios, ramas de trabajo, mensajes de debug) no quede expuesto en el repositorio publico.

Eliminacion de rastros de agentes (OBLIGATORIO)

Antes de cada commit en la rama github, verificar y corregir todo el contenido staged:

  1. Co-Authored-By / co-authored-by: eliminar cualquier linea de co-autoria de agentes (Claude, Copilot, GPT, Codex, etc.) de los mensajes de commit y del contenido de archivos.
  2. Agentes como colaboradores: ningun agente debe aparecer como autor, co-autor o colaborador en commits, PRs ni en ningun metadata de GitHub.
  3. Caracteres watermark: sustituir caracteres atipicos usados como watermark por sus equivalentes normales:
    • Guion largo - (em-dash U+2014) -> guion normal -
    • Guion medio - (en-dash U+2013) -> guion normal -
    • Comillas tipograficas " " ' ' -> comillas rectas " '
    • Espacios especiales (non-breaking space U+00A0, thin space U+2009, etc.) -> espacio normal
    • Cualquier otro caracter Unicode inusual que no pertenezca al contenido tecnico del codigo.
  4. Revision manual: antes del push, ejecutar: 
    # Buscar em-dash, en-dash y comillas tipograficas en archivos staged
git diff --cached | grep -P '[\x{2014}\x{2013}\x{201C}\x{201D}\x{2018}\x{2019}\x{00A0}]'

# Buscar menciones a agentes en el diff
git diff --cached | grep -i -E '(co-authored|claude|copilot|codex|openai|anthropic|gpt-)'

# Buscar en el mensaje de commit antes de hacer push
git log -1 --format=%B | grep -i -E '(co-authored|claude|copilot|codex|openai|anthropic|gpt-)'
  5. Si se detecta algo: corregir, re-stage y hacer commit nuevo. No hacer push hasta que las verificaciones pasen limpias.

Resumen del flujo GitHub

master (desarrollo) ──squash merge──► github (publicacion) ──push──► github remote
                                          │
                                          ├─ sin rastros de agentes
                                          ├─ sin co-authored-by
                                          ├─ sin caracteres watermark
                                          └─ historial limpio y compacto

12. Agent playbook

Checklist previa a cambios

  1. Leer este AGENTS.md.
  2. Leer kline_timestamp/kline_timestamp.py (módulo único, ~244 líneas).
  3. Leer setup.py si el cambio afecta metadata/versión.
  4. Verificar que no hay tests que ejecutar (actualmente no existen).
  5. Verificar estado del repo: git status -sb.

Patrón de commits

<tipo>: <descripcion corta imperativa>

[cuerpo opcional]

Tipos sugeridos: feat, fix, refactor, docs, chore.

Cuándo tocar docs vs código

  • Si cambia la API pública -> actualizar README.md y docstrings.
  • Si cambia la versión -> actualizar setup.py:20, añadir entrada en CHANGELOG.md y crear tag vX.Y.Z.
  • Si se añade funcionalidad -> considerar ejemplo en examples/.

Qué reportar tras un cambio

El agente debe incluir en su respuesta:

  • Archivos tocados (con rutas).
  • Comandos ejecutados.
  • Si se creó commit: hash y mensaje.
  • Si hay efectos secundarios conocidos.

Restricciones

  • No modificar deploy.sh sin confirmación.
  • No hacer git push sin autorización explícita.
  • Versión solo se bumpa con indicación del usuario.

13. Quality gaps

Aspectos ausentes que se podrían mejorar (sin implementar aquí):

Gap Propuesta mínima
Tests Crear tests/test_kline_timestamp.py con pytest. Cubrir: creación, validación, open/close, conversiones, navegación, aritmética, comparaciones, edge cases.
Linter/formatter Añadir ruff con config en pyproject.toml.
Type checker Añadir mypy con --strict o pyright.
CI GitHub Actions: lint + tests en push/PR.
pyproject.toml Migrar de setup.py a PEP 621 (pyproject.toml).
Sphinx docs Configurar docs/ con autodoc + napoleon para generar API docs desde docstrings.
py.typed marker Añadir kline_timestamp/py.typed (el classifier Typing :: Typed ya está).