wsbuilder 1.2.13__tar.gz → 1.3.0__tar.gz

{wsbuilder-1.2.13/src/wsbuilder.egg-info → wsbuilder-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wsbuilder
-Version: 1.2.13
+Version: 1.3.0
 Summary: Lightweight HTTP + WebSocket framework for Python.
 Author: wsbuilder Authors
 License-Expression: MIT

wsbuilder-1.3.0/docs/ai-predict.md

@@ -0,0 +1,244 @@
+# IA y Prediccion
+
+## `DataSet`
+
+`DataSet` es el contenedor basico para pares `X` y `Y`.
+
+```python
+from wsbuilder import DataSet
+
+dataset = DataSet(
+    [[1, 2], [2, 3], [3, 4], [4, 5]],
+    [[0], [1], [1], [1]],
+)
+train, test = dataset.split(train_ratio=0.75, shuffle=False)
+```
+
+Metodos utiles:
+
+- `sample_count`, `feature_count`, `target_count`
+- `copy()`, `as_xy()`
+- `shuffle()`, `split()`, `batches()`
+- `describe_features()`, `describe_targets()`
+- `standardize()`, `normalize_min_max()`
+
+`split()` puede mezclar datos con `shuffle=True` y `seed` para resultados
+repetibles. `batches()` permite entrenar por lotes.
+
+## `NeuralNetwork`
+
+La red neuronal es completamente Python puro.
+
+```python
+from wsbuilder import NeuralNetwork
+
+net = NeuralNetwork(
+    seed=7,
+    learning_rate=0.3,
+    loss="binary_cross_entropy",
+    task="classification",
+)
+net.add_dense(6, input_size=2, activation="tanh")
+net.add_dense(1, activation="sigmoid")
+history = net.fit(
+    [[0, 0], [0, 1], [1, 0], [1, 1]],
+    [[0], [1], [1], [0]],
+    epochs=5000,
+    batch_size=4,
+    shuffle=False,
+)
+```
+
+Capacidades mas visibles:
+
+- `fit` para regresion.
+- `fit_classification` para etiquetas simbolicas.
+- `predict`, `predict_batch`, `predict_proba`, `predict_class`.
+- `evaluate`, `accuracy`, `classification_metrics`.
+- `predict_with_metrics` para reportes de error y confianza.
+
+Activaciones soportadas por la red:
+
+- `linear`
+- `sigmoid`
+- `tanh`
+- `relu`
+- `leaky_relu`
+- `softmax`
+
+Losses soportadas:
+
+- `mse`
+- `binary_cross_entropy`
+- `categorical_cross_entropy`
+
+## `DenseLayer`
+
+`DenseLayer` permite definir capas manuales y se usa como bloque interno del
+`NeuralNetwork`.
+
+Tambien puedes crear capas con `net.add_dense(units, input_size=..., activation=...)`,
+que es la forma mas directa para usuarios de la libreria.
+
+## Estadistica y error
+
+Helpers exportados:
+
+- `describe_data(values)`
+- `evaluate_errors(expected, predicted, permissible_error=...)`
+
+Devuelven `DataSummary` y `ErrorSummary`, ambos con la propiedad `uncertainty`.
+
+## Entrenamiento en background
+
+```python
+from wsbuilder import NeuralNetwork, TaskManager, submit_training_task
+
+X = [[0, 0], [0, 1], [1, 0], [1, 1]]
+labels = ["no", "yes", "yes", "no"]
+
+net = NeuralNetwork(
+    seed=7,
+    learning_rate=0.3,
+    loss="binary_cross_entropy",
+    task="classification",
+)
+net.add_dense(6, input_size=2, activation="tanh")
+net.add_dense(1, activation="sigmoid")
+
+tasks = TaskManager(max_concurrent=1)
+task = submit_training_task(
+    tasks,
+    net,
+    X,
+    labels,
+    classification=True,
+    epochs=1000,
+    batch_size=4,
+    shuffle=False,
+    name="ia-train",
+)
+history = task.get(timeout=5)
+```
+
+## Texto Unicode y tokens
+
+`ByteTokenizer` representa texto como IDs de bytes UTF-8 entre 0 y 255. No
+necesita vocabulario entrenado y conserva exactamente el texto valido, incluidos
+acentos, arabe, chino, emoji y codigo fuente. No aplica normalizacion. Estos IDs
+no son los tokens de un modelo externo ni una estimacion de su facturacion.
+
+```python
+from wsbuilder import ByteTokenizer
+
+tokenizer = ByteTokenizer(max_bytes=1_000_000)
+text = "Hola, 世界! مرحبا 👋\nprint('hola')"
+tokens = tokenizer.encode(text)
+assert tokenizer.decode(tokens) == text
+assert tokenizer.vocab_size == 256
+```
+
+`encode` rechaza texto que exceda `max_bytes`; `decode` rechaza secuencias
+demasiado largas, IDs no enteros o fuera de rango y bytes que no formen UTF-8
+valido. Un token individual puede ser solo parte de un caracter multibyte:
+decodifica secuencias completas. No pases IDs de longitud variable directamente
+a una capa densa de dimension fija.
+
+### Vectores de texto para la red
+
+`HashingTextVectorizer` convierte ngramas de caracteres Unicode en vectores de
+dimension fija usando un hash estable. Funciona tambien con idiomas que no
+separan palabras con espacios; no necesita `fit` ni un vocabulario mutable.
+Dos ngramas pueden caer en la misma posicion (colisiones). Estos vectores
+describen patrones de caracteres, no son embeddings semanticos preentrenados.
+
+```python
+from wsbuilder import DataSet, HashingTextVectorizer, NeuralNetwork
+
+vectorizer = HashingTextVectorizer(n_features=64, ngram_range=(1, 3))
+texts = ["hola", "buen dia", "adios", "hasta luego"]
+X = vectorizer.transform_batch(texts)
+dataset = DataSet(X, [[1], [1], [0], [0]])
+
+model = NeuralNetwork(
+    seed=7, learning_rate=0.3,
+    loss="binary_cross_entropy", task="classification",
+)
+model.add_dense(8, input_size=64, activation="tanh")
+model.add_dense(1, activation="sigmoid")
+model.fit_classification(
+    dataset.X, ["saludo", "saludo", "despedida", "despedida"],
+    epochs=300, batch_size=4, shuffle=False,
+)
+label = model.predict_class(vectorizer.transform("hola"))
+```
+
+Este conjunto diminuto ilustra la API; no demuestra comprension del lenguaje ni
+generalizacion a otros idiomas. Conserva la misma configuracion del vectorizador
+en entrenamiento e inferencia. El texto vacio produce un vector de ceros.
+`max_chars` limita la longitud por texto (100 000 por defecto).
+Por defecto se aplica `casefold` (`lowercase=True`), normalizacion Unicode NFC
+y norma euclidea unitaria (`normalize=True`). NFC se aplica incluso con
+`lowercase=False`; el tokenizador reversible no realiza estas transformaciones.
+`n_features` admite 1 a 65 536 y los extremos de `ngram_range`, 1 a 8.
+`transform_batch` no limita el numero de documentos: procesa tus colecciones
+en lotes acotados.
+
+## Audio WAV y caracteristicas
+
+`load_wav` lee una ruta o un archivo binario seekable con WAV PCM entero de
+8, 16, 24 o 32 bits. Convierte los canales a mono mediante su promedio: canales
+en contrafase pueden cancelarse. No remuestrea ni decodifica MP3, AAC o audio
+comprimido. No cierra el archivo proporcionado por el llamador.
+
+```python
+from wsbuilder import AudioData, NeuralNetwork, audio_features, load_wav
+
+audio = load_wav("grabacion.wav", max_frames=1_000_000, max_channels=8)
+features = audio_features(audio)
+# Orden: duracion en segundos, media, RMS, pico absoluto, cruces por cero.
+assert len(features) == 5
+
+silence = AudioData(samples=(0.0,) * 8000, sample_rate=8000)
+assert audio_features(silence) == [1.0, 0.0, 0.0, 0.0, 0.0]
+
+audio_model = NeuralNetwork(seed=7)
+audio_model.add_dense(1, input_size=5, activation="linear")
+# Entrenar audio_model.fit(...) con ejemplos y objetivos propios antes de inferir.
+```
+
+Los limites de frames y canales se verifican antes de leer las muestras; los
+archivos truncados se rechazan. Un frame contiene una muestra por canal, por lo
+que un millon de frames equivale aproximadamente a 20,8 segundos a 48 kHz.
+`AudioData` contiene una tupla de muestras mono finitas entre -1 y 1 y una
+frecuencia entera en Hz positiva. `duration` devuelve la duracion en segundos;
+una tupla vacia produce cinco caracteristicas cero. Los cruces por cero son
+la fraccion de pares adyacentes que cambian de signo, considerando cero positivo.
+Las caracteristicas resumen amplitud y duracion: no transcriben voz, reconocen
+idiomas ni generan audio. Usa la misma frecuencia de muestreo para comparar
+tasas de cruces por cero; divide los datos de entrenamiento y evaluacion por
+grabacion para evitar evaluar sobre fragmentos del mismo audio.
+
+Texto y audio pueden combinarse concatenando sus vectores y configurando
+`input_size` con la suma de dimensiones. Entrena con ejemplos emparejados y
+escalas consistentes; concatenar vectores no aporta por si solo comprension
+multimodal. Los adaptadores no cambian las condiciones de concurrencia de
+`NeuralNetwork`: evita compartir una instancia entre entrenamientos e
+inferencias simultaneos.
+
+## `Predictor`
+
+`Predictor` es una utilidad matematica aparte para regresion lineal simple.
+
+```python
+from wsbuilder import Predictor
+
+predictor = Predictor()
+predictor.fit([[1], [2], [3], [4]], [[2], [4], [6], [8]])
+prediction, sigma, lower, upper = predictor.predict([5])
+```
+
+Es util cuando quieres prediccion rapida sin configurar una red neuronal.
+
+Despues de `fit`, la instancia expone informacion como `rank`, coeficientes y
+residuos internos usados para calcular desviacion e intervalo estimado.

{wsbuilder-1.2.13 → wsbuilder-1.3.0}/docs/ia.md

@@ -13,6 +13,21 @@ WSBuilder incluye herramientas sencillas de data science y redes neuronales hech
 - `describe_data`
 - `evaluate_errors`
 - `submit_training_task`
+- `ByteTokenizer`
+- `HashingTextVectorizer`
+- `AudioData`, `load_wav`, `audio_features`
+
+## Texto, tokens y audio
+
+La IA acepta texto Unicode, incluidos idiomas sin espacios, emoji y codigo,
+mediante tokens UTF-8 reversibles y vectores numericos de caracteres. Tambien
+convierte audio WAV PCM en muestras mono y caracteristicas numericas para
+entrenar o ejecutar las redes existentes. Todo funciona con la biblioteca
+estandar, sin descargar modelos ni enviar datos a servicios externos.
+
+Consulta los [ejemplos de texto y audio](ai-predict.md#texto-unicode-y-tokens).
+Estos adaptadores preparan datos: no incorporan un modelo de conversacion,
+traduccion, reconocimiento de voz, generacion de audio, imagen o video.
 
 ## Datos
 

{wsbuilder-1.2.13 → wsbuilder-1.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "wsbuilder"
-version = "1.2.13"
+version = "1.3.0"
 description = "Lightweight HTTP + WebSocket framework for Python."
 readme = "README.md"
 requires-python = ">=3.11"

{wsbuilder-1.2.13 → wsbuilder-1.3.0}/src/wsbuilder/__init__.py

@@ -63,13 +63,18 @@ from .framework import (
 )
 from .headers import add_header, get_header, has_header, normalize_header_name, set_header
 from .ia import (
+    AudioData,
+    ByteTokenizer,
     DataSet,
     DataSummary,
     DenseLayer,
     ErrorSummary,
+    HashingTextVectorizer,
     NeuralNetwork,
+    audio_features,
     describe_data,
     evaluate_errors,
+    load_wav,
     submit_training_task,
 )
 from .logs import NDJSONLog, install_logs
@@ -152,7 +157,7 @@ def __dir__():
         names |= _PKI_EXPORTS
     return sorted(names)
 
-__version__ = "1.2.13"
+__version__ = "1.3.0"
 
 __all__ = [
     "App",
@@ -250,6 +255,11 @@ __all__ = [
     "OptimizedDatabase",
     "SQLite3OptimizationConfig",
     "DataSet",
+    "AudioData",
+    "ByteTokenizer",
+    "HashingTextVectorizer",
+    "audio_features",
+    "load_wav",
     "DataSummary",
     "ErrorSummary",
     "DenseLayer",

{wsbuilder-1.2.13 → wsbuilder-1.3.0}/src/wsbuilder/ia.py

@@ -20,7 +20,15 @@ import random
 from dataclasses import dataclass
 from statistics import NormalDist
 
+from .ia_audio import AudioData, audio_features, load_wav
+from .ia_text import ByteTokenizer, HashingTextVectorizer
+
 __all__ = [
+    "AudioData",
+    "ByteTokenizer",
+    "HashingTextVectorizer",
+    "audio_features",
+    "load_wav",
     "DataSet",
     "DataSummary",
     "DenseLayer",

wsbuilder-1.3.0/src/wsbuilder/ia_audio.py

@@ -0,0 +1,93 @@
+"""Bounded PCM WAV decoding and numeric mono audio features (no speech model)."""
+
+import math
+import os
+import wave
+from dataclasses import dataclass
+
+from .ia_text import _positive_integer
+
+__all__ = ["AudioData", "load_wav", "audio_features"]
+
+
+@dataclass(frozen=True)
+class AudioData:
+    """Mono samples in [-1, 1] and a positive sample rate in Hz.
+
+    Direct construction accepts a tuple only, so it never consumes an unbounded
+    iterable. ``load_wav`` supplies bounded decoded samples.
+    """
+
+    samples: tuple[float, ...]
+    sample_rate: int
+
+    def __post_init__(self):
+        _positive_integer(self.sample_rate, "sample_rate")
+        if not isinstance(self.samples, tuple):
+            raise TypeError("samples must be a tuple")
+        if any(isinstance(value, bool) or not isinstance(value, (int, float))
+               or not math.isfinite(value) or not -1 <= value <= 1
+               for value in self.samples):
+            raise ValueError("samples must contain finite numbers in [-1, 1]")
+
+    @property
+    def duration(self):
+        return len(self.samples) / self.sample_rate
+
+
+def load_wav(source, *, max_frames=1_000_000, max_channels=8):
+    """Read integer PCM WAV (8/16/24/32 bit), averaging channels to mono.
+
+    Opposite-phase channels can cancel during averaging. Source is a path or
+    binary seekable file; caller-owned files remain open. Declared frame count
+    and channels are checked before sample allocation. Malformed/truncated PCM
+    is rejected. Compressed audio and float WAV are not supported.
+    """
+    _positive_integer(max_frames, "max_frames")
+    _positive_integer(max_channels, "max_channels")
+    if isinstance(source, os.PathLike):
+        source = os.fspath(source)
+    with wave.open(source, "rb") as stream:
+        channels = stream.getnchannels()
+        width = stream.getsampwidth()
+        rate = stream.getframerate()
+        frames = stream.getnframes()
+        if not 1 <= channels <= max_channels:
+            raise ValueError("WAV channel count exceeds max_channels")
+        if frames > max_frames:
+            raise ValueError("WAV frame count exceeds max_frames")
+        if stream.getcomptype() != "NONE" or width not in (1, 2, 3, 4):
+            raise ValueError("WAV must use 8/16/24/32-bit integer PCM")
+        raw = stream.readframes(frames)
+        frame_size = width * channels
+        if len(raw) != frames * frame_size or stream.readframes(1):
+            raise ValueError("WAV contains truncated or incomplete PCM frames")
+    samples = []
+    scale = 1 << (width * 8 - 1)
+    for offset in range(0, len(raw), frame_size):
+        total = 0
+        for channel in range(channels):
+            start = offset + channel * width
+            value = int.from_bytes(raw[start:start + width], "little", signed=width != 1)
+            total += value - 128 if width == 1 else value
+        samples.append(total / (scale * channels))
+    return AudioData(tuple(samples), rate)
+
+
+def audio_features(audio):
+    """Return [duration seconds, mean, RMS, peak, zero-crossing fraction].
+
+    Zero crossings compare adjacent signs (zero is nonnegative). Empty audio
+    returns five zeros. These summaries discard temporal/spectral information;
+    they are suitable for basic signal classification, not transcription.
+    """
+    if not isinstance(audio, AudioData):
+        raise TypeError("audio must be AudioData")
+    samples = audio.samples
+    if not samples:
+        return [0.0] * 5
+    crossings = sum((samples[i - 1] < 0) != (samples[i] < 0)
+                    for i in range(1, len(samples)))
+    return [audio.duration, math.fsum(samples) / len(samples),
+            math.sqrt(math.fsum(value * value for value in samples) / len(samples)),
+            max(abs(value) for value in samples), crossings / max(1, len(samples) - 1)]

wsbuilder-1.3.0/src/wsbuilder/ia_text.py

@@ -0,0 +1,100 @@
+"""Bounded UTF-8 tokens and deterministic character features, using only stdlib."""
+
+import hashlib
+import math
+import unicodedata
+
+__all__ = ["ByteTokenizer", "HashingTextVectorizer"]
+
+
+def _positive_integer(value, name):
+    if type(value) is not int or value < 1:
+        raise ValueError(f"{name} must be a positive integer")
+    return value
+
+
+class ByteTokenizer:
+    """Reversible UTF-8 bytes (IDs 0..255), without text normalization.
+
+    These are byte tokens, not a provider/model's token accounting scheme.
+    Invalid UTF-8 and isolated Unicode surrogates are rejected.
+    """
+
+    vocab_size = 256
+
+    def __init__(self, *, max_bytes=1_000_000):
+        self.max_bytes = _positive_integer(max_bytes, "max_bytes")
+
+    def encode(self, text):
+        if not isinstance(text, str):
+            raise TypeError("text must be a string")
+        if len(text) > self.max_bytes:
+            raise ValueError("text exceeds max_bytes")
+        encoded = text.encode("utf-8")
+        if len(encoded) > self.max_bytes:
+            raise ValueError("text exceeds max_bytes")
+        return list(encoded)
+
+    def decode(self, tokens):
+        encoded = bytearray()
+        for token in tokens:
+            if len(encoded) >= self.max_bytes:
+                raise ValueError("tokens exceed max_bytes")
+            if type(token) is not int or not 0 <= token < self.vocab_size:
+                raise ValueError("tokens must be integer byte IDs in 0..255")
+            encoded.append(token)
+        return encoded.decode("utf-8")
+
+
+class HashingTextVectorizer:
+    """Fixed-width counts of Unicode character n-grams, with stable hashing.
+
+    NFC normalization and optional casefolding are applied only to features.
+    Hash collisions are possible; these are lexical features, not semantic
+    embeddings. ``normalize=True`` scales each vector to unit Euclidean norm.
+    Empty text produces zeros. Configuration must match training and inference.
+    """
+
+    def __init__(self, n_features=256, *, ngram_range=(1, 3), lowercase=True,
+                 normalize=True, max_chars=100_000):
+        self.n_features = _positive_integer(n_features, "n_features")
+        if self.n_features > 65_536:
+            raise ValueError("n_features must not exceed 65536")
+        if not isinstance(ngram_range, (tuple, list)) or len(ngram_range) != 2:
+            raise ValueError("ngram_range must contain two integers")
+        low, high = ngram_range
+        if type(low) is not int or type(high) is not int or not 1 <= low <= high <= 8:
+            raise ValueError("ngram_range must satisfy 1 <= low <= high <= 8")
+        if type(lowercase) is not bool or type(normalize) is not bool:
+            raise TypeError("lowercase and normalize must be booleans")
+        self.ngram_range = (low, high)
+        self.lowercase = lowercase
+        self.normalize = normalize
+        self.max_chars = _positive_integer(max_chars, "max_chars")
+
+    def transform(self, text):
+        if not isinstance(text, str):
+            raise TypeError("text must be a string")
+        if len(text) > self.max_chars:
+            raise ValueError("text exceeds max_chars")
+        text = unicodedata.normalize("NFC", text.casefold() if self.lowercase else text)
+        if len(text) > self.max_chars:
+            raise ValueError("normalized text exceeds max_chars")
+        vector = [0.0] * self.n_features
+        for width in range(self.ngram_range[0], self.ngram_range[1] + 1):
+            for offset in range(len(text) - width + 1):
+                digest = hashlib.blake2b(text[offset:offset + width].encode("utf-8"),
+                                         digest_size=8).digest()
+                index = int.from_bytes(digest, "big") % self.n_features
+                vector[index] += 1.0
+        if self.normalize:
+            norm = math.sqrt(sum(value * value for value in vector))
+            if norm:
+                vector = [value / norm for value in vector]
+        return vector
+
+    def transform_batch(self, texts):
+        """Transform a batch; the caller controls the number of documents."""
+        if isinstance(texts, str):
+            raise TypeError("texts must be an iterable of strings, not a string")
+        return [self.transform(text) for text in texts]

{wsbuilder-1.2.13 → wsbuilder-1.3.0/src/wsbuilder.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wsbuilder
-Version: 1.2.13
+Version: 1.3.0
 Summary: Lightweight HTTP + WebSocket framework for Python.
 Author: wsbuilder Authors
 License-Expression: MIT

{wsbuilder-1.2.13 → wsbuilder-1.3.0}/src/wsbuilder.egg-info/SOURCES.txt

@@ -64,6 +64,8 @@ src/wsbuilder/http3.py
 src/wsbuilder/http3_server.py
 src/wsbuilder/http3_websocket.py
 src/wsbuilder/ia.py
+src/wsbuilder/ia_audio.py
+src/wsbuilder/ia_text.py
 src/wsbuilder/logs.py
 src/wsbuilder/mdns.py
 src/wsbuilder/metrics.py
@@ -110,6 +112,7 @@ tests/test_http3_server.py
 tests/test_http3_streaming.py
 tests/test_http3_streaming_udp.py
 tests/test_ia.py
+tests/test_ia_text_audio.py
 tests/test_logs.py
 tests/test_mdns.py
 tests/test_metrics.py