Metadata-Version: 2.4
Name: scic-framework
Version: 0.2.3
Summary: Sistema de Control de Instruccion por Comandos
Author: Specter
License-Expression: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: resourcetree
Requires-Dist: datavalue
Provides-Extra: test
Requires-Dist: pytest>=8.0; extra == "test"
Requires-Dist: pytest-asyncio>=0.23; extra == "test"
Dynamic: license-file

# SCIC 0.2.0

SCIC (Sistema de Control de Instrucción por Comandos) registra, organiza,
resuelve y ejecuta funciones Python mediante instrucciones textuales.

```text
context1 context2 function parameters...
```

Una función se implementa una vez y puede consumirse desde CLI, WebGUI,
DesktopGUI, API, SDK, scripts o automatizaciones.

## Principios

- El árbol sólo contiene `Context` y `Executable`.
- Los nombres son únicos dentro de su contexto padre.
- Una función registrada sigue siendo un `callable` Python ordinario.
- `Executable` declara parámetros y resultados mediante `DataValue`.
- Los contratos usan validación posicional explícita.
- El registro compartido no contiene estado de navegación.
- Cada consumidor utiliza su propia `SCICSession`.
- Las interfaces controlan ayuda, presentación, progreso y procesos compuestos.
- La API primaria de ejecución es asíncrona.

## Dependencias

```text
resourcetree >= 0.2.0, < 0.3.0
datavalue   >= 0.2.0, < 0.3.0
```

## Instalación

```bash
python3 -m pip install .
```

Para desarrollo:

```bash
python3 -m pip install -e ".[test]"
pytest
```

## Uso

```python
from datavalue import ComplexData, PrimitiveData, ValidationMode
from scic import Executable, SCIC


def primitive(data_type, name, **constraints):
    return PrimitiveData(
        data_type=data_type,
        value=None,
        name=name,
        data_class=True,
        **constraints,
    )


def signature(name, *schemas):
    return ComplexData(
        data_type=list,
        value=None,
        name=name,
        possible_values=schemas,
        data_class=True,
        validation_mode=ValidationMode.POSITIONAL,
    )


def add(number_a: int, number_b: int) -> int:
    return number_a + number_b


scic = SCIC()
math = scic.create_context("math")

adapter = Executable(
    name="add",
    description="Suma dos enteros.",
    parameters=signature(
        "parameters",
        primitive(int, "number_a"),
        primitive(int, "number_b"),
    ),
    results=signature(
        "results",
        primitive(int, "sum"),
    ),
)

scic.register_function(
    adapter=adapter,
    function=add,
    context=math,
)

scic.freeze()
session = scic.create_session()

results = await session.execute(
    "math add 20 22"
)

assert results == [42]
```

## Navegación relativa

```python
await session.execute("math")
assert session.context_path == "scic/math"

results = await session.execute("add 10 5")
assert results == [15]

session.back()
session.reset()
```

El nombre de la raíz permite resolución absoluta sin modificar el contexto:

```python
results = await session.execute(
    "scic math add 7 8"
)
```

## Sesiones independientes

```python
cli = scic.create_session()
browser_a = scic.create_session()
browser_b = scic.create_session()

cli.enter("math")
browser_a.enter("user")
browser_b.enter("text")
```

Todos comparten el mismo árbol y las mismas funciones, pero conservan su
propio contexto activo.

## Autodescripción

```python
session.describe()
session.describe("math add")
session.list_context()
scic.export_tree()
```

La salida es estructurada. Cada consumidor decide si la transforma en texto,
HTML, JSON, widgets o documentación.

## Ejemplos

CLI:

```bash
python3 examples/cli.py
```

WebGUI con una sesión independiente por navegador:

```bash
python3 examples/webgui.py
```

Abrir:

```text
http://localhost:8080
```

## Límites intencionales

El núcleo no administra:

- Presentación.
- Permisos o roles.
- Procesos interactivos compuestos.
- Progreso.
- HTTP.
- Qt o HTML.
- Persistencia.
- Logging.
- Ejecución remota.

Estas capacidades pertenecen a la aplicación o a sus consumidores.
