Merge pull request #12 from HectorMozo3110/main

docs: improve module index descriptions and update architecture overview

Author: HectorMozo3110

docs/architecture.rst

@@ -1,11 +1,334 @@
 Architecture
 ============
 
-This section describes the internal design of QML-HCS, including its modular
-quantum-classical architecture and interaction between core components.
+This section presents the internal design of QML-HCS (Quantum Machine-Learning 
+Hypercausal System), organized from the **lowest foundational layers** to the 
+**highest orchestration layers**, and visualized through layered diagrams.
 
+QML-HCS is fully modular. No single execution flow is mandatory. Instead, the 
+system exposes interoperable components that can be assembled into custom 
+pipelines depending on the experiment or backend.
 
-.. warning::
+Main Architecture Diagram
+-------------------------
 
-   🚧 These sections are currently under active development.  
-   Content will be expanded soon with detailed explanations, diagrams, and examples.
+The following diagram shows the entire architecture from bottom (foundations) 
+to top (orchestration):
+
+.. graphviz::
+   :align: center
+
+    digraph Architecture {
+        rankdir=TB;
+        node [shape=box, style="filled,rounded", color="#1E1E1E", fillcolor="#3A3A3A", fontcolor="white"];
+
+        Core       [label="Level 1 - Core Module\n(Contracts, Types, Registry, HCModel)"];
+        Backends   [label="Level 2 - Backends\n(PennyLane, Qiskit, C++, pybind11)"];
+        HC         [label="Level 3 - Hypercausal Layer\n(HCNode, HCGraph, Policies)"];
+        Predictors [label="Level 4 - Predictors\n(Deterministic & Counterfactual)"];
+        Loss       [label="Level 5 - Loss Module\n(Task • Coherence • Consistency)"];
+        Metrics    [label="Level 6 - Metrics Module\n(Anomaly • Control • Forecasting)"];
+        Optim      [label="Level 7 - Optimizers\n(SPSA, Adam, Natural-Grad, Trust-KL, KFAC)"];
+        Callbacks  [label="Level 8 - Callbacks\n(Telemetry, DepthScheduler)"];
+
+        Core -> Backends -> HC -> Predictors -> Loss -> Metrics -> Optim -> Callbacks;
+    }
+
+This is the **canonical structural view**, not a required flow of execution.
+
+.. note::
+
+   The diagram presents the canonical structural organization of QML-HCS. It is 
+   intended as a conceptual layering model rather than an operational pipeline. 
+   Component order in this diagram does *not* imply a mandatory execution sequence; 
+   QML-HCS supports modular use and flexible composition.
+
+Level 1 - Core Module (Structural Foundation)
+---------------------------------------------
+**See also the** :doc:`full Core documentation <modules/qmlhc/core/index>`
+
+The core defines:
+
+- Typed interfaces for backends, nodes, projection policies
+- Registry system
+- Formal validation
+- HCModel: optional high-level orchestrator
+
+.. graphviz::
+  :align: center
+
+    digraph Core {
+        rankdir=LR;
+        node [shape=box, style="rounded,filled", fillcolor="#2E2E2E", fontcolor="white"];
+
+        Types      [label="Types & Protocols"];
+        BackendIfc [label="QuantumBackend Interface"];
+        Registry   [label="Backend Registry"];
+        Model      [label="HCModel"];
+
+        Types -> BackendIfc -> Registry -> Model;
+    }
+
+Level 2 - Backend Layer (Execution Engines)
+-------------------------------------------
+**See also the** :doc:`full Backends documentation <modules/qmlhc/backends/index>`
+
+Backends provide actual numerical or quantum-based execution.
+
+Supported adapters:
+
+- PennyLane (analytic/differentiable)
+- Qiskit (shot-based, stochastic)
+- C++ pybind11 backend (deterministic, HPC speed)
+
+.. graphviz::
+   :align: center
+
+    digraph Backends {
+        rankdir=LR;
+        node [shape=box, style="rounded,filled", fillcolor="#334455", fontcolor="white"];
+
+        PL   [label="PennyLane Backend"];
+        QK   [label="Qiskit Backend"];
+        CPP  [label="C++ Backend"];
+
+        PL -> QK -> CPP;
+    }
+
+
+Level 3 - Hypercausal Layer (Logical Evolution Engine)
+------------------------------------------------------
+**See also the** :doc:`full Hypercausal Layer documentation <modules/qmlhc/hc/index>`
+
+Defines how states evolve over time and across branches.
+
+Components:
+
+- HCNode (input → state → futures → representative)
+- HCGraph (causal connections)
+- Projection policies
+
+.. graphviz::
+   :align: center
+
+    digraph HC {
+        rankdir=LR;
+        node [shape=box, style="rounded,filled", fillcolor="#556677", fontcolor="white"];
+
+        HCNode   [label="HCNode"];
+        HCGraph  [label="HCGraph"];
+        Policy   [label="Projection Policies"];
+
+        HCNode  -> HCGraph;
+        HCGraph -> Policy;
+    }
+
+
+Level 4 - Predictors (Deterministic & Counterfactual)
+-----------------------------------------------------
+**See also the** :doc:`full Predictors documentation <modules/qmlhc/predictors/index>`
+
+Predictors extend computation with:
+
+- LinearProjector
+- Counterfactual anticipators
+- Mirrored perturbations
+
+.. graphviz::
+   :align: center
+
+    digraph Predictors {
+        rankdir=LR;
+        node [shape=box, style="rounded,filled", fillcolor="#774444", fontcolor="white"];
+
+        Proj  [label="LinearProjector"];
+        CF    [label="Counterfactual Anticipator"];
+        Pert  [label="Perturbations"];
+
+        Proj -> CF -> Pert;
+    }
+
+
+Level 5 - Loss Evaluation Layer
+-------------------------------
+**See also the** :doc:`full Loss Module documentation <modules/qmlhc/loss/index>`
+
+Measures:
+
+- **Task accuracy**
+- **Inter-branch coherence**
+- **Triadic temporal consistency**
+
+.. graphviz::
+   :align: center
+
+    digraph Loss {
+        rankdir=LR;
+        node [shape=box, style="rounded,filled", fillcolor="#664466", fontcolor="white"];
+
+        Task [label="Task Losses"];
+        Coh  [label="Coherence"];
+        Cons [label="Consistency"];
+
+        Task -> Coh -> Cons;
+    }
+
+
+Level 6 - Metrics (Advanced Temporal & Statistical Analysis)
+------------------------------------------------------------
+**See also the** :doc:`full Metrics Module documentation <modules/qmlhc/metrics/index>`
+
+Provides higher-order diagnostics:
+
+- anomaly detection
+- control stability
+- forecasting alignment
+
+.. graphviz::
+   :align: center
+
+    digraph Metrics {
+        rankdir=LR;
+        node [shape=box, style="rounded,filled", fillcolor="#334433", fontcolor="white"];
+
+        Anom [label="Anomaly Metrics"];
+        Ctrl [label="Control Metrics"];
+        Fcast[label="Forecast Metrics"];
+
+        Anom -> Ctrl -> Fcast;
+    }
+
+
+Level 7 - Optimization Module
+-----------------------------
+**See also the** :doc:`full Optimization documentation <modules/qmlhc/optim/index>`
+
+Algorithms:
+
+- finite-diff
+- SPSA
+- Adam
+- Natural-Grad
+- Trust-KL
+- Dual-Ascent
+- MPC
+- KFAC
+
+.. graphviz::
+   :align: center
+
+    digraph Optim {
+        rankdir=LR;
+        node [shape=box, style="rounded,filled", fillcolor="#444444", fontcolor="white"];
+
+        GD   [label="Finite-Diff"];
+        SPSA [label="SPSA"];
+        Adam [label="Adam"];
+        NG   [label="Natural Grad"];
+        KL   [label="Trust-KL"];
+        KFAC [label="KFAC"];
+
+        GD -> SPSA -> Adam -> NG -> KL -> KFAC;
+    }
+
+
+Level 8 - Callbacks Layer
+-------------------------
+**See also the** :doc:`full Callbacks documentation <modules/qmlhc/callbacks/index>`
+
+Provides live monitoring and state adaptation.
+
+- TelemetryLogger  
+- MemoryLogger  
+- DepthScheduler  
+
+.. graphviz::
+   :align: center
+   
+    digraph Callbacks {
+        rankdir=LR;
+        node [shape=box, style="rounded,filled", fillcolor="#555555", fontcolor="white"];
+
+        TL [label="TelemetryLogger"];
+        ML [label="MemoryLogger"];
+        DS [label="DepthScheduler"];
+
+        TL -> ML -> DS;
+    }
+
+
+Optional Execution Flows (Not Mandatory)
+----------------------------------------
+
+QML-HCS allows multiple flows; these are optional examples.
+
+**Hypercausal Flow Example**
+
+.. graphviz::
+   :align: center
+
+    digraph FlowHC {
+        rankdir=LR;
+        node [shape=oval, style="filled", fillcolor="#335577", fontcolor="white"];
+
+        X  [label="Input"];
+        S  [label="State"];
+        K  [label="Future Branches"];
+        R  [label="Representative"];
+
+        X -> S -> K -> R;
+    }
+
+
+**Predictor/Counterfactual Flow Example**
+
+.. graphviz::
+   :align: center
+
+    digraph FlowCF {
+        rankdir=LR;
+        node [shape=oval, style="filled", fillcolor="#773333", fontcolor="white"];
+
+        St [label="State"];
+        LP [label="LinearProjector"];
+        CF [label="Counterfactuals"];
+        Ev [label="Evaluation"];
+
+        St -> LP -> CF -> Ev;
+    }
+
+
+**Optimization Loop Example**
+
+.. graphviz::
+   :align: center
+   
+    digraph FlowOptim {
+        rankdir=LR;
+        node [shape=oval, style="filled", fillcolor="#555555", fontcolor="white"];
+
+        P  [label="Params"];
+        M  [label="Model"];
+        L  [label="Loss/Metrics"];
+        O  [label="Optimizer Step"];
+
+        P -> M -> L -> O -> P;
+    }
+
+
+Summary
+-------
+
+QML-HCS is structured according to increasing abstraction:
+
+1. Core Module - structural base  
+2. Backends - execution engines  
+3. Hypercausal Layer - logical evolution framework  
+4. Predictors - deterministic & counterfactual expansion  
+5. Loss Layer - coherence and task evaluation  
+6. Metrics - statistical and temporal interpretation  
+7. Optimization - adaptation and learning  
+8. Callbacks - runtime monitoring and control  
+
+The diagrams above reflect modular organization, not a required pipeline.  
+Users may assemble custom computation flows depending on their needs.

docs/conf.py

@@ -17,7 +17,8 @@
     "myst_parser",                   
     "sphinx.ext.mathjax",   
     "sphinxcontrib.programoutput",
-    "sphinx.ext.intersphinx",      
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.graphviz",
 ]
 
 intersphinx_mapping = {

docs/examples/ex_full_hypercausal_Pennylane_demo.rst

@@ -1,3 +1,5 @@
+.. _ex-full-hypercausal-pennylane-demo:
+
 ====================================================
 Full Hypercausal System Demo (PennyLane + SPSA + KL)
 ====================================================
@@ -46,6 +48,16 @@ This demo wires the high-level components of **QML-HCS** as follows:
 - **Callbacks:** ``MemoryLogger`` (telemetry) and ``DepthScheduler`` (progressive circuit depth).
 - **Optimizers:** base **SPSA** (derivative-free) wrapped by a **KL-bounded trust-region** controller.
 
+.. note::
+   This demonstration combines both abstraction levels introduced in the core
+   and hypercausal modules. The ``HCNode`` manages the direct backend–policy
+   interaction for each causal step, while the ``HCModel`` wraps this node to
+   enable complete sequence execution and optimizer integration.
+
+   Readers can refer to the conceptual discussion in
+   :ref:`HCNode vs HCModel <core-hcnode-hcmodel-note>`
+   for details on their complementary roles within the QML-HCS framework.
+
 Data & Non-Stationary Drift
 ===========================
 We use a fixed seed input vector ``x0 ∈ ℝ^{qubits}`` and inject a **sinusoidal drift**

docs/getting_started.rst

@@ -96,7 +96,7 @@ You can verify installation by running:
 
 .. code-block:: bash
 
-   python -c "import qmlhcs; print(qmlhcs.__version__)"
+   python -c "import qmlhc; print(qmlhc.__version__)"
 
 This method is ideal for end-users or production deployments where the source code is not being modified, but the full library functionality and API features remain available for direct use.
 
@@ -329,7 +329,6 @@ The QML-HCS repository follows a clean modular layout:
       │   └── examples.rst
       │
       ├── pyproject.toml                 # Build metadata (PEP 621)
-      ├── Makefile                       # Build, test, and docs automation
       └── README.md                      # Project overview and installation guide
 
 
@@ -456,7 +455,7 @@ To view a detailed coverage report directly in your browser, run:
    25 files skipped due to complete coverage.
    Required test coverage of 75.0% reached. Total coverage: 92.03%
    53 passed in 0.32s
-   (.venv) (base) mozoh@pop-os:~/Desktop/P1/qml-hcs$
+  
 
 A 100% test success and a coverage above 90% confirm that the QMLHC package is correctly installed and all major modules are functioning as expected.