Cuaderno de apoyo para hacer las prácticas por programa

Opcional. Todo el curso se puede hacer con la interfaz web de un modelo y con hojas de cálculo. Este cuaderno es para quien quiera dejar instrucciones, outputs, expectativas y decisiones en archivos, repetir la codificación con varios modelos, y calcular el acuerdo cuando quiera reportarlo. Está pensado para alguien sin experiencia previa en Python, copiando bloque a bloque. El cuaderno de apoyo de Validación del razonamiento con IA en ciencias sociales, el curso de fundamentos del programa, explica con más detalle la preparación del entorno y la función base que envía una instrucción a un modelo y guarda el registro; aquí se repite lo mínimo.

Preparación

Instale Python 3.11 o superior y, en una terminal:

pip install openai python-dotenv pandas

Cree un archivo .env con la clave del proveedor que use. La biblioteca openai sirve para cualquier proveedor compatible con su interfaz; cambie base_url según el caso. Para la triangulación entre familias conviene tener dos claves de proveedores distintos; varios ofrecen cuota gratuita.

API_KEY=su_clave
BASE_URL=https://api.openai.com/v1
MODEL=nombre_del_modelo

Función base con registro

Cada llamada queda en un archivo con fecha, modelo e instrucción literal. Ese archivo es el anexo que piden las plantillas.

import os, json, datetime
from dotenv import load_dotenv
from openai import OpenAI

load_dotenv()
client = OpenAI(api_key=os.getenv("API_KEY"), base_url=os.getenv("BASE_URL"))
MODEL = os.getenv("MODEL")

def preguntar(prompt, etiqueta, registro="registro.jsonl"):
    r = client.chat.completions.create(
        model=MODEL,
        messages=[{"role": "user", "content": prompt}],
        temperature=0.2,
    )
    texto = r.choices[0].message.content
    with open(registro, "a", encoding="utf-8") as f:
        f.write(json.dumps({
            "fecha": datetime.datetime.now().isoformat(),
            "modelo": MODEL,
            "etiqueta": etiqueta,
            "prompt": prompt,
            "respuesta": texto,
        }, ensure_ascii=False) + "\n")
    return texto

Semana 3. Declarar la expectativa antes de correr

La expectativa se escribe en un archivo con hora antes de la primera llamada. Lo que importa es que quede fechada.

def declarar_expectativa(condicion, expectativa, archivo="expectativas.jsonl"):
    with open(archivo, "a", encoding="utf-8") as f:
        f.write(json.dumps({
            "fecha": datetime.datetime.now().isoformat(),
            "condicion": condicion,
            "expectativa": expectativa,
        }, ensure_ascii=False) + "\n")

declarar_expectativa("con libro de códigos",
    "coincidencia alta: el modelo aplica mi regla; mide consistencia, no es pata")
declarar_expectativa("sin libro de códigos, otra familia",
    "divergencia en los fragmentos 4, 7 y 9, donde la categoría exige contexto local")

Semana 3. Las dos condiciones

fragmentos = open("fragmentos.txt", encoding="utf-8").read()
libro = open("libro-de-codigos.txt", encoding="utf-8").read()
pregunta = "¿Cómo narran los entrevistados su relación con las instituciones locales?"

p_con = f"""Libro de códigos:\n{libro}\n\nFragmentos:\n{fragmentos}\n
Asigna a cada fragmento uno o más códigos del libro. Para cada asignación cita
la frase exacta, di por qué ese código y no el más cercano, y marca si dudaste.
No inventes códigos; si ninguno aplica escribe "ninguno" y explica."""
con_libro = preguntar(p_con, "semana3-con-libro")

p_sin = f"""Pregunta de investigación: {pregunta}\n\nFragmentos:\n{fragmentos}\n
Propón códigos para cada fragmento. Para cada código: nombre breve, definición
en una frase, la frase exacta que lo sustenta, y qué supuesto das por sentado."""
sin_libro = preguntar(p_sin, "semana3-sin-libro")

Para la segunda condición con otra familia, cambie MODEL y BASE_URL en .env o cree un segundo cliente.

Semana 3. Cálculo del acuerdo y su uso

Si quiere reportar el acuerdo de la condición con libro de códigos, el curso pide que lo reporte como consistencia y no como validez. Con una tabla codificacion.csv de columnas fragmento, codigo_mio, codigo_modelo:

import pandas as pd

df = pd.read_csv("codificacion.csv")
acuerdo = (df["codigo_mio"] == df["codigo_modelo"]).mean()
print(f"Acuerdo observado: {acuerdo:.1%}")

Para un kappa de Cohen, pip install scikit-learn y:

from sklearn.metrics import cohen_kappa_score
print("Kappa:", round(cohen_kappa_score(df["codigo_mio"], df["codigo_modelo"]), 2))

Lo que se escribe en la matriz no es la cifra sino la frase: "el modelo aplica mi libro de códigos con un acuerdo de 0,81; mide consistencia; no cuenta como pata". Una cifra sin esa frase es el salto de la semana 1.

Semana 4. Candidatos de hipótesis con supuesto explícito

patron = "Los fragmentos que mencionan 'la alcaldía' nunca mencionan 'la policía', y al revés."
p = f"""Patrón observado: {patron}\n
Propón dos hipótesis distintas e incompatibles que lo explicarían. Para cada una:
(1) el hecho que explica, (2) una observación que la distinguiría de la otra,
(3) el supuesto que das por sentado al proponerla."""
print(preguntar(p, "semana4-candidatos"))

El punto 3 es el que llena la columna "desde qué trasfondo es plausible" de la ficha.

Semana 7. Marcadores de autoridad

Un conteo sencillo sobre el propio borrador. La lista es la de la práctica; amplíela con los marcadores de su campo.

import re

MARCADORES = [
    "los datos muestran", "el análisis revela", "es evidente que", "se observa que",
    "los resultados indican", "resulta claro", "como puede apreciarse",
    "la evidencia sugiere", "se concluye que", "queda demostrado",
]

texto = open("borrador.txt", encoding="utf-8").read().lower()
for m in MARCADORES:
    n = len(re.findall(re.escape(m), texto))
    if n:
        print(f"{m}: {n}")

El programa no reescribe nada. Marca dónde hay que ponerse a escribir.

Nota sobre costos y privacidad

Use cuotas gratuitas y material sin datos personales de terceros. Si su proyecto incluye material sensible, haga las prácticas con una muestra anonimizada o con material público, y revise las condiciones de uso de datos del proveedor antes de enviar nada: la plantilla de declaración pregunta si las revisó. Exterioridad y gobernanza de la IA en ciencias sociales, el curso del programa sobre derechos, exterioridad y gobernanza del uso de modelos, trata estos problemas en detalle: qué derechos pesan sobre cada pieza del material, qué daño puede causar su uso y a quién, y qué protocolo se da un equipo para responder por ello.

Práctica 3. Triangulación con un modelo como segundo codificador

Duración estimada: 3 horas, de las cuales 1 en la sesión sincrónica. Requisitos: acceso a un modelo de lenguaje de uso gratuito en su versión web (cualquiera sirve) y, si es posible, a un segundo modelo de otra familia; diez fragmentos propios ya codificados; el libro de códigos con que se codificaron; la plantilla plantillas/matriz-de-triangulacion.md. No requiere programar. El cuaderno cuaderno-apoyo.md indica cómo hacer lo mismo por programa y cómo calcular el acuerdo si se quiere reportar.

Objetivo

Hacer codificar diez fragmentos propios por un modelo en dos condiciones, con y sin libro de códigos, declarar antes de correr qué se espera, comparar con la codificación propia, y llenar una fila de la matriz de triangulación por condición, diciendo cuál mide consistencia y cuál cuenta como pata.

Antes de la sesión

1. Elija diez fragmentos de su material que ya tengan codificación suya o de su equipo. Que sean de distinta dificultad: tres claros, cuatro medios, tres en que usted dudó. Sin datos personales de terceros; si el material es sensible, use una muestra anonimizada.
2. Prepare dos archivos de texto. El primero, los diez fragmentos numerados, sin códigos. El segundo, el libro de códigos: nombre, definición en una o dos frases y un ejemplo por código.
3. Escriba, con fecha y hora, su expectativa para cada condición: en la condición con libro de códigos espero coincidencia alta porque aplica mi regla; en la condición sin libro de códigos espero divergencia en los fragmentos difíciles porque mis categorías vienen de un trasfondo que el modelo no tiene; o lo que usted espere. Esta expectativa se entrega con la matriz y no puede cambiarse después.
4. Llene el encabezado de la plantilla y las instancias que ya tiene, aparte del modelo.

Tres rondas durante la sesión

Ronda 1. Con libro de códigos

Dele al modelo el libro de códigos y los diez fragmentos. Use una instrucción que le exija citar y justificar. Ejemplo:

Aquí hay un libro de códigos con definiciones y ejemplos, y diez fragmentos
de entrevista numerados. Asigna a cada fragmento uno o más códigos del libro.
Para cada asignación: cita la frase exacta que la sustenta, di por qué ese
código y no el más cercano del libro, y marca si dudaste. No inventes códigos
nuevos; si ningún código aplica, escribe "ninguno" y explica por qué.

Copie el output completo al anexo. Compare fragmento por fragmento con su codificación: coincide, difiere, el modelo no asignó. Anote el conteo. Esta fila de la matriz se marca como consistencia: mide cuán bien el modelo aplica su regla, no si la regla es buena.

Ronda 2. Sin libro de códigos

Abra una conversación nueva, en lo posible con un modelo de otra familia. Dele los diez fragmentos y la pregunta de investigación, nada más. Ejemplo:

Aquí hay diez fragmentos de entrevista numerados y la pregunta de investigación:
[pregunta]. Propón códigos para cada fragmento a partir de lo que dice. Para
cada código: nombre breve, definición en una frase, la frase exacta que lo
sustenta, y qué supuesto das por sentado al nombrarlo así.

Copie el output al anexo. Compare con su codificación por sentido y no por nombre: un código del modelo converge con uno suyo si recortan el mismo fragmento con la misma razón, aunque el nombre cambie. Anote convergencia, divergencia o silencio por hallazgo. Esta fila puede contar como pata si el modelo es de otra familia que cualquier otro usado en el proyecto y la expectativa se declaró antes.

Ronda 3. Las divergencias

Tome cada divergencia de la ronda 2 y, antes de decidir si el modelo se equivocó, responda por escrito: qué trasfondo distinto produjo la divergencia. Tres preguntas de apoyo:

• ¿El modelo nombró con una categoría más general que la mía? Entonces lo que diverge es el nivel, y la pregunta es si mi nivel está justificado por el material o por mi marco.
• ¿El modelo nombró algo que yo no vi? Entonces hay que volver al fragmento y decidir si lo que vio está ahí o lo trajo de su corpus.
• ¿El modelo no nombró algo que para mí es obvio? Entonces lo obvio puede ser de mi pertenencia, y hay que decir si la categoría exige pertenecer para verse.

Las divergencias que se explican por prefiguración se registran en la matriz con esa explicación. Las que, después de volver al fragmento, resultan error del modelo, se registran como error, con la frase del fragmento que lo muestra.

Después de la sesión

1. Complete la matriz con las demás instancias que tenga: otras fuentes, otro método, otra teoría, otro investigador si lo hubo. Marque convergencia, divergencia o silencio por hallazgo y escriba la nota de cada celda.
2. Lea la matriz por columnas y asigne estatuto a cada hallazgo. Los de una sola pata se marcan como conjetura.
3. Lea la matriz por filas y responda si alguna instancia nunca diverge, y por qué.
4. Entregue la matriz con el anexo de instrucciones, outputs literales y expectativas fechadas.

Qué se evalúa

Que la condición de independencia de cada fila esté declarada y sea correcta, que la expectativa esté fechada antes de correr, que las divergencias tengan explicación por prefiguración y no solo por error, y que los hallazgos de una sola pata estén marcados. No se evalúa el acuerdo: una ronda con bajo acuerdo bien explicada vale más que una con acuerdo alto que se presenta como validación.

Variante para grupos

Dos estudiantes intercambian fragmentos y libros de códigos y cada uno codifica el material del otro antes de ver la codificación original. Esa fila sí es de investigadores independientes. Compararla con la fila del modelo bajo la misma condición es el mejor material de discusión: suele mostrar que el par humano diverge donde el modelo converge, y al revés.

Práctica 7. Reescritura de un informe generado hasta convertirlo en aserciones propias

Duración estimada: 3 horas, de las cuales 1 en la sesión sincrónica. Requisitos: un informe o borrador propio en el que un modelo haya redactado al menos un párrafo, o un párrafo de hallazgos que se le pide al modelo al empezar; la matriz de triangulación entregada en la semana 5; las plantillas plantillas/declaracion-de-uso-de-ia.md e plantillas/informe-analitico.md; la mini app apps/asercion-sin-aserente.html para calibrar. No requiere programar.

Objetivo

Convertir cada frase de un párrafo generado en una aserción con sujeto, base, criterio, alcance y procedencia, separar las frases que no se pueden firmar, y redactar la declaración de uso de IA del párrafo.

Antes de la sesión

1. Si no tiene un párrafo generado, pídale al modelo uno a partir de su matriz. Ejemplo:

Esta es mi matriz de triangulación: [pegar la lectura por columnas]. Redacta
un párrafo de hallazgos de unas 200 palabras, en el registro de un artículo
de ciencias sociales, que presente los tres hallazgos principales.

2. Guarde el párrafo literal en el anexo. No lo corrija todavía.
3. Pídale al modelo, en la misma conversación, que justifique cada afirmación del párrafo. Guarde esa justificación también. La va a necesitar para ver qué forma tiene una justificación sin aserente.

Cuatro pasos durante la sesión

Paso 1. Marcar

Resalte en el párrafo todos los marcadores de autoridad que atribuyen la afirmación a algo que no puede afirmar: "los datos muestran", "el análisis revela", "es evidente que", "se observa que", "los resultados indican", "resulta claro", "como puede apreciarse", "la evidencia sugiere", "se concluye que". Cuente cuántos hay. La mini app lo hace sobre un párrafo de ejemplo y sirve para calibrar el ojo.

Paso 2. Desarmar

Una fila por frase del párrafo, en la tabla de la semana:

Para cada frase, responda en orden:

• Verificar. ¿Hay en la frase un dato, una cifra, una cita, una referencia? ¿Lo comprobó contra el material o la fuente? Si no puede comprobarlo ahora, anote "no" y siga; la frase no se firma hasta que se compruebe.
• Criterio. ¿Sobre qué patas de la matriz se sostiene lo afirmado? ¿Qué prueba pasó, de qué tipo? ¿Por qué esta categoría o lectura y no otra? Si la matriz no lo sostiene, anótelo.
• Aserente y alcance. ¿Quién afirma esto? ¿Desde qué trasfondo? ¿A qué material, período o contexto se limita? Escriba la frase con sujeto en primera persona y alcance explícito.
• Procedencia. ¿La frase es output aceptado tal cual, output corregido, output rechazado y reemplazado, o propia? Anótelo con una palabra.

Paso 3. Reescribir o retirar

Escriba la frase nueva. Una frase reescrita tiene esta forma, con variaciones: "Sostengo que X, porque A y B convergen y la prueba C pasó; el modelo propuso X y lo acepté por D; lo afirmo para el material E". Es más larga que la original porque ahora tiene a alguien detrás.

Si al intentar la reescritura descubre que no puede sostener la frase, no la mejore: retírela y anote por qué. Las frases retiradas van a la sección 4 del informe, "Lo que cayó y lo que se retiró". Son el resultado esperado de la práctica y se evalúan.

Paso 4. Declarar

Con la plantilla de declaración de uso de IA, llene al menos las secciones 2, 3 y 7 para este párrafo: qué se pidió, qué produjo, qué se aceptó, corrigió y rechazó, con qué criterio, y la tabla de procedencia de cada hallazgo. Adjunte las instrucciones literales.

Después de la sesión

1. Compare la justificación que el modelo dio en el paso previo con las columnas de criterio que usted llenó. Anote qué tenía la justificación del modelo: conectores, forma de argumento, referencias a "los datos". Anote qué le faltaba: patas, prueba, alguien que responda. Esa comparación va a la bitácora.
2. Extienda la reescritura al resto del borrador del informe. No hace falta que todo el informe pase por la tabla, pero sí todo párrafo de hallazgos.
3. Entregue el borrador del informe con la sección de validación en el estado en que esté y la declaración de uso de IA. Se devuelve con observaciones antes de la entrega final.

Qué se evalúa

En el borrador no se califica. En el informe final se evalúa que ningún hallazgo conserve marcadores sin aserente, que cada reescritura haya añadido base y criterio y no solo sujeto, que las frases retiradas estén en la sección 4 con razón, y que la declaración diga qué fue de quién. Una reescritura que cambia "los datos muestran" por "considero que" sin añadir nada se devuelve.

Variante para grupos

Dos estudiantes intercambian párrafos reescritos y cada uno intenta formular, para cada frase del otro, la pregunta que un jurado haría. Las frases que no resisten la pregunta vuelven a la tabla. Es un ensayo de la semana 8.