Duplicate from geraskalnas/document-summarization

.gitattributes

@@ -0,0 +1,31 @@
+*.7z filter=lfs diff=lfs merge=lfs -text
+*.arrow filter=lfs diff=lfs merge=lfs -text
+*.bin filter=lfs diff=lfs merge=lfs -text
+*.bz2 filter=lfs diff=lfs merge=lfs -text
+*.ftz filter=lfs diff=lfs merge=lfs -text
+*.gz filter=lfs diff=lfs merge=lfs -text
+*.h5 filter=lfs diff=lfs merge=lfs -text
+*.joblib filter=lfs diff=lfs merge=lfs -text
+*.lfs.* filter=lfs diff=lfs merge=lfs -text
+*.model filter=lfs diff=lfs merge=lfs -text
+*.msgpack filter=lfs diff=lfs merge=lfs -text
+*.npy filter=lfs diff=lfs merge=lfs -text
+*.npz filter=lfs diff=lfs merge=lfs -text
+*.onnx filter=lfs diff=lfs merge=lfs -text
+*.ot filter=lfs diff=lfs merge=lfs -text
+*.parquet filter=lfs diff=lfs merge=lfs -text
+*.pickle filter=lfs diff=lfs merge=lfs -text
+*.pkl filter=lfs diff=lfs merge=lfs -text
+*.pb filter=lfs diff=lfs merge=lfs -text
+*.pt filter=lfs diff=lfs merge=lfs -text
+*.pth filter=lfs diff=lfs merge=lfs -text
+*.rar filter=lfs diff=lfs merge=lfs -text
+saved_model/**/* filter=lfs diff=lfs merge=lfs -text
+*.tar.* filter=lfs diff=lfs merge=lfs -text
+*.tflite filter=lfs diff=lfs merge=lfs -text
+*.tgz filter=lfs diff=lfs merge=lfs -text
+*.wasm filter=lfs diff=lfs merge=lfs -text
+*.xz filter=lfs diff=lfs merge=lfs -text
+*.zip filter=lfs diff=lfs merge=lfs -text
+*.zst filter=lfs diff=lfs merge=lfs -text
+*tfevents* filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,29 @@
+# logs
+*.log
+*LOGFILE*
+
+# output files need to be force-added
+*.csv
+*.png
+*.jpg
+*.jpeg
+*.pkl
+*.xlsx
+*.txt
+
+# cache
+*__pycache__/
+*.pyc
+
+# reports folder - need to be force-added
+*reports/
+
+# scratch files and folders
+
+*scratch*
+*scratch/
+
+# notebooks
+
+*notebooks/
+*.ipynb

README.md

@@ -0,0 +1,34 @@
+---
+title: Document Summarization
+emoji: 🌖
+colorFrom: gray
+colorTo: indigo
+sdk: gradio
+sdk_version: 3.32.0
+app_file: app.py
+pinned: true
+license: apache-2.0
+duplicated_from: geraskalnas/document-summarization
+---
+
+Check out the configuration reference at <https://huggingface.co/docs/hub/spaces-config-reference>
+
+# README - Document Summarization
+
+The original demo/what this repo was built for can be found [here](https://huggingface.co/spaces/pszemraj/document-summarization)
+
+## Usage
+
+If you are using this **not** as a gradio demo on hf spaces, you can run it locally with:
+
+```bash
+python app.py --share
+```
+
+To see all the available arguments, run `python app.py --help`.
+
+## Installation
+
+```bash
+pip install -r requirements.txt
+```

aggregate.py

@@ -0,0 +1,241 @@
+"""
+aggregate.py - module for aggregating text from multiple sources/multiple parts of a single source.
+    Primary usage is through the BatchAggregator class.
+
+How it works:
+1. We tell the language model to do it.
+2. The language model does it.
+3. Yaay!
+"""
+import logging
+import pprint as pp
+import time
+
+import torch
+from transformers import GenerationConfig, pipeline
+
+from utils import compare_model_size
+
+# Setting up logging
+logging.basicConfig(
+    level=logging.INFO, format="%(asctime)s - %(levelname)s - %(message)s"
+)
+
+
+class BatchAggregator:
+    """
+    BatchAggregator is a class for aggregating text from multiple sources.
+
+    Usage:
+    >>> from aggregate import BatchAggregator
+    >>> aggregator = BatchAggregator()
+    >>> agg = aggregator.infer_aggregate(["This is a test", "This is another test"])
+    >>> print(agg)
+    """
+
+    GENERIC_CONFIG = GenerationConfig(
+        num_beams=8,
+        early_stopping=True,
+        do_sample=False,
+        min_new_tokens=32,
+        max_new_tokens=256,
+        repetition_penalty=1.1,
+        length_penalty=1.4,
+        no_repeat_ngram_size=4,
+        encoder_no_repeat_ngram_size=5,
+    )
+    CONFIGURED_MODELS = [
+        "pszemraj/bart-large-mnli-dolly_hhrlhf-v1",
+        "pszemraj/bart-base-instruct-dolly_hhrlhf",
+        "pszemraj/flan-t5-large-instruct-dolly_hhrlhf",
+        "pszemraj/flan-t5-base-instruct-dolly_hhrlhf",
+    ]  # these have generation configs defined for this task in their model repos
+
+    DEFAULT_INSTRUCTION = "Write a comprehensive yet concise summary that pulls together the main points of the following text:"
+
+    def __init__(
+        self,
+        model_name: str = "pszemraj/bart-large-mnli-dolly_hhrlhf-v1",
+        force_cpu: bool = False,
+        **kwargs,
+    ):
+        """
+        __init__ initializes the BatchAggregator class.
+
+        :param str model_name: model name to use, default: "pszemraj/bart-large-mnli-dolly_hhrlhf-v1"
+        :param bool force_cpu: force the model to run on CPU, default: False
+        """
+        self.device = None
+        self.is_compiled = False
+        self.model_name = None
+        self.aggregator = None
+        self.force_cpu = force_cpu
+        self.logger = logging.getLogger(__name__)
+        self.init_model(model_name)
+
+    def init_model(self, model_name: str) -> None:
+        """
+        Initialize the model.
+
+        :param model_name: The name of the model to use.
+        """
+        # Free up memory
+        if torch.cuda.is_available():
+            torch.cuda.empty_cache()
+
+        self.logger.info(f"Setting model to {model_name}")
+        self.model_name = model_name
+        self.aggregator = self._create_pipeline(model_name)
+        self._configure_model()
+        # update the generation config with the specific tokenizer
+        tokenizer_params = {
+            "decoder_start_token_id": 0
+            if "t5" in model_name.lower()
+            else self.aggregator.tokenizer.eos_token_id,
+            "eos_token_id": 1
+            if "t5" in model_name.lower()
+            else self.aggregator.tokenizer.eos_token_id,
+            "pad_token_id": 0
+            if "t5" in model_name.lower()
+            else self.aggregator.tokenizer.pad_token_id,
+        }
+        self.update_generation_config(**tokenizer_params)
+
+    def _create_pipeline(
+        self, model_name: str = "pszemraj/bart-large-mnli-dolly_hhrlhf-v1"
+    ) -> pipeline:
+        """
+        _create_pipeline creates a pipeline for the model.
+
+        :param str model_name: model name to use, default: "pszemraj/bart-large-mnli-dolly_hhrlhf-v1"
+        :return pipeline: the pipeline for the model
+
+        :raises Exception: if the pipeline cannot be created
+        """
+        self.device = 0 if torch.cuda.is_available() and not self.force_cpu else -1
+        try:
+            self.logger.info(
+                f"Creating pipeline with model {model_name} on device {self.device}"
+            )
+            return pipeline(
+                "text2text-generation",
+                model_name,
+                device=self.device,
+                torch_dtype=torch.float32,
+            )
+        except Exception as e:
+            self.logger.error(f"Failed to create pipeline: {e}")
+            raise
+
+    def _configure_model(self):
+        """
+        Configure the model for generation.
+        """
+        try:
+            self.aggregator.model = torch.compile(self.aggregator.model)
+            self.is_compiled = True
+        except Exception as e:
+            self.logger.warning(f"Could not compile model with Torch 2.0: {e}")
+
+        if self.model_name not in self.CONFIGURED_MODELS:
+            self.logger.info("Setting generation config to general defaults")
+            self._set_default_generation_config()
+        else:
+            try:
+                self.logger.info("Loading generation config from hub")
+                self.aggregator.model.generation_config = (
+                    GenerationConfig.from_pretrained(self.model_name)
+                )
+            except Exception as e:
+                self.logger.warning(
+                    f"Could not load generation config, using defaults: {e}"
+                )
+                self._set_default_generation_config()
+
+        self.logger.info(self.aggregator.model.generation_config.to_json_string())
+
+    def _set_default_generation_config(self):
+        """
+        Set the default generation configuration for the model.
+        """
+        self.aggregator.model.generation_config = self.GENERIC_CONFIG
+
+        if (
+            "large"
+            or "xl" in self.model_name.lower()
+            or compare_model_size(self.model_name, 500)
+        ):
+            upd = {"num_beams": 4}
+            self.update_generation_config(**upd)
+
+    def update_generation_config(self, **kwargs):
+        """
+        Update the generation configuration with the specified parameters.
+
+        Args:
+            **kwargs: The parameters to update in the generation configuration.
+        """
+        self.logger.info(f"Updating generation config with {pp.pformat(kwargs)}")
+
+        self.aggregator.model.generation_config.update(**kwargs)
+
+    def get_generation_config(self) -> dict:
+        """
+        Get the current generation configuration.
+
+        Returns:
+            dict: The current generation configuration.
+        """
+        return self.aggregator.model.generation_config.to_dict()
+
+    def update_loglevel(self, level: str = "INFO"):
+        """
+        Update the log level.
+
+        Args:
+            level (str): The log level to set. Defaults to "INFO".
+        """
+        self.logger.setLevel(level)
+
+    def infer_aggregate(
+        self,
+        text_list: list,
+        instruction: str = DEFAULT_INSTRUCTION,
+        **kwargs,
+    ) -> str:
+        f"""
+        infer_aggregate - infers a consolidated summary from a list of texts.
+
+        Args:
+            text_list (list): The texts to summarize.
+            instruction (str): The instruction for the summary. Defaults to {self.DEFAULT_INSTRUCTION}.
+            **kwargs: Additional parameters to update in the generation configuration.
+
+        Returns:
+            The generated summary.
+        """
+        joined_text = "\n".join(text_list)
+        prompt = f"{instruction}\n\n{joined_text}\n"
+        if kwargs:
+            self.update_generation_config(**kwargs)
+        st = time.perf_counter()
+        self.logger.info(f"inference on {len(text_list)} texts ...")
+        result = self.aggregator(
+            prompt,
+            generation_config=self.aggregator.model.generation_config,
+        )[0]["generated_text"]
+        self.logger.info(f"Done. runtime:\t{round(time.perf_counter() - st, 2)}s")
+        self.logger.info(
+            f"Input tokens:\t{self.count_tokens(prompt)}. Output tokens:\t{self.count_tokens(result)}"
+        )
+        self.logger.debug(f"Generated text:\n{result}")
+
+        return result
+
+    def count_tokens(self, text: str) -> int:
+        """count the number of tokens in a text"""
+        return (
+            len(self.aggregator.tokenizer.encode(text, truncation=False, padding=False))
+            if text
+            else 0
+        )

app.py

@@ -0,0 +1,687 @@
+"""
+app.py - the main module for the gradio app for summarization
+
+Usage:
+    app.py [-h] [--share] [-m MODEL] [-nb ADD_BEAM_OPTION] [-batch TOKEN_BATCH_OPTION]
+              [-level {DEBUG,INFO,WARNING,ERROR}]
+Details:
+    python app.py --help
+
+Environment Variables:
+    USE_TORCH (str): whether to use torch (1) or not (0)
+    TOKENIZERS_PARALLELISM (str): whether to use parallelism (true) or not (false)
+Optional Environment Variables:
+    APP_MAX_WORDS (int): the maximum number of words to use for summarization
+    APP_OCR_MAX_PAGES (int): the maximum number of pages to use for OCR
+"""
+import argparse
+import contextlib
+import gc
+import logging
+import os
+import pprint as pp
+import random
+import re
+import sys
+import time
+from pathlib import Path
+
+os.environ["USE_TORCH"] = "1"
+os.environ["TOKENIZERS_PARALLELISM"] = "false"
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s [%(levelname)s] %(name)s - %(message)s",
+    datefmt="%Y-%b-%d %H:%M:%S",
+)
+
+import gradio as gr
+import nltk
+import torch
+from cleantext import clean
+from doctr.models import ocr_predictor
+
+from aggregate import BatchAggregator
+from pdf2text import convert_PDF_to_Text
+from summarize import load_model_and_tokenizer, summarize_via_tokenbatches
+from utils import (
+    contraction_aware_tokenize,
+    extract_batches,
+    load_example_filenames,
+    remove_stagnant_files,
+    remove_stopwords,
+    saves_summary,
+    textlist2html,
+    truncate_word_count,
+)
+
+_here = Path(__file__).parent
+
+nltk.download("punkt", force=True, quiet=True)
+nltk.download("popular", force=True, quiet=True)
+
+# Constants & Globals
+MODEL_OPTIONS = [
+    "pszemraj/long-t5-tglobal-base-16384-book-summary",
+    "pszemraj/long-t5-tglobal-base-sci-simplify",
+    "pszemraj/long-t5-tglobal-base-sci-simplify-elife",
+    "pszemraj/long-t5-tglobal-base-16384-booksci-summary-v1",
+    "pszemraj/pegasus-x-large-book-summary",
+]  # models users can choose from
+BEAM_OPTIONS = [2, 3, 4]  # beam sizes users can choose from
+TOKEN_BATCH_OPTIONS = [
+    1024,
+    1536,
+    2048,
+    2560,
+    3072,
+]  # token batch sizes users can choose from
+
+SUMMARY_PLACEHOLDER = "<p><em>Output will appear below:</em></p>"
+AGGREGATE_MODEL = "MBZUAI/LaMini-Flan-T5-783M"  # model to use for aggregation
+
+# if duplicating space: uncomment this line to adjust the max words
+# os.environ["APP_MAX_WORDS"] = str(2048)  # set the max words to 2048
+# os.environ["APP_OCR_MAX_PAGES"] = str(40)  # set the max pages to 40
+# os.environ["APP_AGG_FORCE_CPU"] = str(1)  # force cpu for aggregation
+
+aggregator = BatchAggregator(
+    AGGREGATE_MODEL, force_cpu=os.environ.get("APP_AGG_FORCE_CPU", False)
+)
+
+
+def aggregate_text(
+    summary_text: str,
+    text_file: gr.inputs.File = None,
+) -> str:
+    """
+    Aggregate the text from the batches.
+
+        NOTE: you should probably include the BatchAggregator object as a fn arg if using this code
+
+    :param batches_html: The batches to aggregate, in html format
+    :param text_file: The text file to append the aggregate summary to
+    :return: The aggregate summary in html format
+    """
+    if summary_text is None or summary_text == SUMMARY_PLACEHOLDER:
+        logging.error("No text provided. Make sure a summary has been generated first.")
+        return "Error: No text provided. Make sure a summary has been generated first."
+
+    try:
+        extracted_batches = extract_batches(summary_text)
+    except Exception as e:
+        logging.info(summary_text)
+        logging.info(f"the batches html is: {type(summary_text)}")
+        return f"Error: unable to extract batches - check input: {e}"
+    if not extracted_batches:
+        logging.error("unable to extract batches - check input")
+        return "Error: unable to extract batches - check input"
+
+    out_path = None
+    if text_file is not None:
+        out_path = text_file.name  # assuming name attribute stores the file path
+
+    content_batches = [batch["content"] for batch in extracted_batches]
+    full_summary = aggregator.infer_aggregate(content_batches)
+
+    # if a path that exists is provided, append the summary with markdown formatting
+    if out_path:
+        out_path = Path(out_path)
+
+        try:
+            with open(out_path, "a", encoding="utf-8") as f:
+                f.write("\n\n## Aggregate Summary\n\n")
+                f.write(
+                    "- This is an instruction-based LLM aggregation of the previous 'summary batches'.\n"
+                )
+                f.write(f"- Aggregation model: {aggregator.model_name}\n\n")
+                f.write(f"{full_summary}\n\n")
+            logging.info(f"Updated {out_path} with aggregate summary")
+        except Exception as e:
+            logging.error(f"unable to update {out_path} with aggregate summary: {e}")
+
+    full_summary_html = f"""
+        <div style="
+            margin-bottom: 20px;
+            font-size: 18px;
+            line-height: 1.5em;
+            color: #333;
+        ">
+            <h2 style="font-size: 22px; color: #555;">Aggregate Summary:</h2>
+            <p style="white-space: pre-line;">{full_summary}</p>
+        </div>
+        """
+    return full_summary_html
+
+
+def predict(
+    input_text: str,
+    model_name: str,
+    token_batch_length: int = 1024,
+    empty_cache: bool = True,
+    **settings,
+) -> list:
+    """
+    predict - helper fn to support multiple models for summarization at once
+
+    :param str input_text: the input text to summarize
+    :param str model_name: model name to use
+    :param int token_batch_length: the length of the token batches to use
+    :param bool empty_cache: whether to empty the cache before loading a new= model
+    :return: list of dicts with keys "summary" and "score"
+    """
+    if torch.cuda.is_available() and empty_cache:
+        torch.cuda.empty_cache()
+
+    model, tokenizer = load_model_and_tokenizer(model_name)
+    summaries = summarize_via_tokenbatches(
+        input_text,
+        model,
+        tokenizer,
+        batch_length=token_batch_length,
+        **settings,
+    )
+
+    del model
+    del tokenizer
+    gc.collect()
+
+    return summaries
+
+
+def proc_submission(
+    input_text: str,
+    model_name: str,
+    num_beams: int,
+    token_batch_length: int,
+    length_penalty: float,
+    repetition_penalty: float,
+    no_repeat_ngram_size: int,
+    predrop_stopwords: bool,
+    max_input_length: int = 6144,
+):
+    """
+    proc_submission - a helper function for the gradio module to process submissions
+
+    Args:
+        input_text (str): the input text to summarize
+        model_name (str): the hf model tag of the model to use
+        num_beams (int): the number of beams to use
+        token_batch_length (int): the length of the token batches to use
+        length_penalty (float): the length penalty to use
+        repetition_penalty (float): the repetition penalty to use
+        no_repeat_ngram_size (int): the no repeat ngram size to use
+        predrop_stopwords (bool): whether to pre-drop stopwords before truncating/summarizing
+        max_input_length (int, optional): the maximum input length to use. Defaults to 6144.
+
+    Note:
+        the max_input_length is set to 6144 by default, but can be changed by setting the
+        environment variable APP_MAX_WORDS to a different value.
+
+    Returns:
+        tuple (4): a tuple containing the following:
+    """
+
+    remove_stagnant_files()  # clean up old files
+    settings = {
+        "length_penalty": float(length_penalty),
+        "repetition_penalty": float(repetition_penalty),
+        "no_repeat_ngram_size": int(no_repeat_ngram_size),
+        "encoder_no_repeat_ngram_size": 4,
+        "num_beams": int(num_beams),
+        "min_length": 4,
+        "max_length": int(token_batch_length // 4),
+        "early_stopping": True,
+        "do_sample": False,
+    }
+    max_input_length = int(os.environ.get("APP_MAX_WORDS", max_input_length))
+    logging.info(
+        f"max_input_length set to: {max_input_length}. pre-drop stopwords: {predrop_stopwords}"
+    )
+
+    st = time.perf_counter()
+    history = {}
+    cln_text = clean(input_text, lower=False)
+    parsed_cln_text = remove_stopwords(cln_text) if predrop_stopwords else cln_text
+    logging.info(
+        f"pre-truncation word count: {len(contraction_aware_tokenize(parsed_cln_text))}"
+    )
+    truncation_validated = truncate_word_count(
+        parsed_cln_text, max_words=max_input_length
+    )
+
+    if truncation_validated["was_truncated"]:
+        model_input_text = truncation_validated["processed_text"]
+        # create elaborate HTML warning
+        input_wc = len(contraction_aware_tokenize(parsed_cln_text))
+        msg = f"""
+        <div style="background-color: #FFA500; color: white; padding: 20px;">
+        <h3>Warning</h3>
+        <p>Input text was truncated to {max_input_length} words. That's about {100*max_input_length/input_wc:.2f}% of the original text.</p>
+        <p>Dropping stopwords is set to {predrop_stopwords}. If this is not what you intended, please validate the advanced settings.</p>
+        </div>
+        """
+        logging.warning(msg)
+        history["WARNING"] = msg
+    else:
+        model_input_text = truncation_validated["processed_text"]
+        msg = None
+
+    if len(input_text) < 50:
+        # this is essentially a different case from the above
+        msg = f"""
+        <div style="background-color: #880808; color: white; padding: 20px;">
+        <br>
+        <img src="https://i.imgflip.com/7kadd9.jpg" alt="no text">
+        <br>
+        <h3>Error</h3>
+        <p>Input text is too short to summarize. Detected {len(input_text)} characters.
+        Please load text by selecting an example from the dropdown menu or by pasting text into the text box.</p>
+        </div>
+        """
+        logging.warning(msg)
+        logging.warning("RETURNING EMPTY STRING")
+        history["WARNING"] = msg
+
+        return msg, "<strong>No summary generated.</strong>", "", []
+
+    _summaries = predict(
+        input_text=model_input_text,
+        model_name=model_name,
+        token_batch_length=token_batch_length,
+        **settings,
+    )
+    sum_text = [s["summary"][0].strip() + "\n" for s in _summaries]
+    sum_scores = [
+        f" - Batch Summary {i}: {round(s['summary_score'],4)}"
+        for i, s in enumerate(_summaries)
+    ]
+
+    full_summary = textlist2html(sum_text)
+    history["Summary Scores"] = "<br><br>"
+    scores_out = "\n".join(sum_scores)
+    rt = round((time.perf_counter() - st) / 60, 2)
+    logging.info(f"Runtime: {rt} minutes")
+    html = ""
+    html += f"<p>Runtime: {rt} minutes with model: {model_name}</p>"
+    if msg is not None:
+        html += msg
+
+    html += ""
+
+    settings["remove_stopwords"] = predrop_stopwords
+    settings["model_name"] = model_name
+    saved_file = saves_summary(summarize_output=_summaries, outpath=None, **settings)
+    return html, full_summary, scores_out, saved_file
+
+
+def load_single_example_text(
+    example_path: str or Path,
+    max_pages: int = 20,
+) -> str:
+    """
+    load_single_example_text - loads a single example text file
+
+    :param strorPath example_path: name of the example to load
+    :param int max_pages: the maximum number of pages to load from a PDF
+    :return str: the text of the example
+    """
+    global name_to_path, ocr_model
+    full_ex_path = name_to_path[example_path]
+    full_ex_path = Path(full_ex_path)
+    if full_ex_path.suffix in [".txt", ".md"]:
+        with open(full_ex_path, "r", encoding="utf-8", errors="ignore") as f:
+            raw_text = f.read()
+        text = clean(raw_text, lower=False)
+    elif full_ex_path.suffix == ".pdf":
+        logging.info(f"Loading PDF file {full_ex_path}")
+        max_pages = int(os.environ.get("APP_OCR_MAX_PAGES", max_pages))
+        logging.info(f"max_pages set to: {max_pages}")
+        conversion_stats = convert_PDF_to_Text(
+            full_ex_path,
+            ocr_model=ocr_model,
+            max_pages=max_pages,
+        )
+        text = conversion_stats["converted_text"]
+    else:
+        logging.error(f"Unknown file type {full_ex_path.suffix}")
+        text = "ERROR - check example path"
+
+    return text
+
+
+def load_uploaded_file(file_obj, max_pages: int = 20, lower: bool = False) -> str:
+    """
+    load_uploaded_file - loads a file uploaded by the user
+
+    :param file_obj (POTENTIALLY list): Gradio file object inside a list
+    :param int max_pages: the maximum number of pages to load from a PDF
+    :param bool lower: whether to lowercase the text
+    :return str: the text of the file
+    """
+    global ocr_model
+    logger = logging.getLogger(__name__)
+    # check if mysterious file object is a list
+    if isinstance(file_obj, list):
+        file_obj = file_obj[0]
+    file_path = Path(file_obj.name)
+    try:
+        logger.info(f"Loading file:\t{file_path}")
+        if file_path.suffix in [".txt", ".md"]:
+            with open(file_path, "r", encoding="utf-8", errors="ignore") as f:
+                raw_text = f.read()
+            text = clean(raw_text, lower=lower)
+        elif file_path.suffix == ".pdf":
+            logger.info(f"loading a PDF file: {file_path.name}")
+            max_pages = int(os.environ.get("APP_OCR_MAX_PAGES", max_pages))
+            logger.info(f"max_pages is: {max_pages}. Starting conversion...")
+            conversion_stats = convert_PDF_to_Text(
+                file_path,
+                ocr_model=ocr_model,
+                max_pages=max_pages,
+            )
+            text = conversion_stats["converted_text"]
+        else:
+            logger.error(f"Unknown file type:\t{file_path.suffix}")
+            text = "ERROR - check file - unknown file type. PDF, TXT, and MD are supported."
+
+        return text
+    except Exception as e:
+        logger.error(f"Trying to load file:\t{file_path},\nerror:\t{e}")
+        return f"Error: Could not read file {file_path.name}. Make sure it is a PDF, TXT, or MD file."
+
+
+def parse_args():
+    """arguments for the command line interface"""
+    parser = argparse.ArgumentParser(
+        description="Document Summarization with Long-Document Transformers - Demo",
+        formatter_class=argparse.ArgumentDefaultsHelpFormatter,
+        epilog="Runs a local-only web UI to summarize documents. pass --share for a public link to share.",
+    )
+
+    parser.add_argument(
+        "--share",
+        dest="share",
+        action="store_true",
+        help="Create a public link to share",
+    )
+    parser.add_argument(
+        "-m",
+        "--model",
+        type=str,
+        default=None,
+        help=f"Add a custom model to the list of models: {pp.pformat(MODEL_OPTIONS, compact=True)}",
+    )
+    parser.add_argument(
+        "-nb",
+        "--add_beam_option",
+        type=int,
+        default=None,
+        help=f"Add a beam search option to the demo UI options, default: {pp.pformat(BEAM_OPTIONS, compact=True)}",
+    )
+    parser.add_argument(
+        "-batch",
+        "--token_batch_option",
+        type=int,
+        default=None,
+        help=f"Add a token batch size to the demo UI options, default: {pp.pformat(TOKEN_BATCH_OPTIONS, compact=True)}",
+    )
+    parser.add_argument(
+        "-max_agg",
+        "-2x",
+        "--aggregator_beam_boost",
+        dest="aggregator_beam_boost",
+        action="store_true",
+        help="Double the number of beams for the aggregator during beam search",
+    )
+    parser.add_argument(
+        "-level",
+        "--log_level",
+        type=str,
+        default="INFO",
+        choices=["DEBUG", "INFO", "WARNING", "ERROR"],
+        help="Set the logging level",
+    )
+
+    return parser.parse_args()
+
+
+if __name__ == "__main__":
+    """main - the main function of the app"""
+    logger = logging.getLogger(__name__)
+    args = parse_args()
+    logger.setLevel(args.log_level)
+    logger.info(f"args: {pp.pformat(args.__dict__, compact=True)}")
+
+    # add any custom options
+    if args.model is not None:
+        logger.info(f"Adding model {args.model} to the list of models")
+        MODEL_OPTIONS.append(args.model)
+    if args.add_beam_option is not None:
+        logger.info(f"Adding beam search option {args.add_beam_option} to the list")
+        BEAM_OPTIONS.append(args.add_beam_option)
+    if args.token_batch_option is not None:
+        logger.info(f"Adding token batch option {args.token_batch_option} to the list")
+        TOKEN_BATCH_OPTIONS.append(args.token_batch_option)
+
+    if args.aggregator_beam_boost:
+        logger.info("Doubling aggregator num_beams")
+        _agg_cfg = aggregator.get_generation_config()
+        _agg_cfg["num_beams"] = _agg_cfg["num_beams"] * 2
+        aggregator.update_generation_config(**_agg_cfg)
+
+    logger.info("Loading OCR model")
+    with contextlib.redirect_stdout(None):
+        ocr_model = ocr_predictor(
+            "db_resnet50",
+            "crnn_mobilenet_v3_large",
+            pretrained=True,
+            assume_straight_pages=True,
+        )
+
+    # load the examples
+    name_to_path = load_example_filenames(_here / "examples")
+    logger.info(f"Loaded {len(name_to_path)} examples")
+
+    demo = gr.Blocks(title="Document Summarization with Long-Document Transformers")
+    _examples = list(name_to_path.keys())
+    logger.info("Starting app instance")
+    with demo:
+        gr.Markdown("# Document Summarization with Long-Document Transformers")
+        gr.Markdown(
+            """An example use case for fine-tuned long document transformers. Model(s) are trained on [book summaries](https://hf.co/datasets/kmfoda/booksum). Architectures [in this demo](https://hf.co/spaces/pszemraj/document-summarization) are [LongT5-base](https://hf.co/pszemraj/long-t5-tglobal-base-16384-book-summary) and [Pegasus-X-Large](https://hf.co/pszemraj/pegasus-x-large-book-summary).
+
+            **Want more performance? Run this demo from a free Google Colab GPU:**.
+            <br>
+            <a href="https://colab.research.google.com/gist/pszemraj/52f67cf7326e780155812a6a1f9bb724/document-summarization-on-gpu.ipynb">
+            <img src="https://colab.research.google.com/assets/colab-badge.svg" alt="Open In Colab"/>
+            </a>
+            <br>
+            """
+        )
+        with gr.Column():
+            gr.Markdown("## Load Inputs & Select Parameters")
+            gr.Markdown(
+                """Enter/paste text below, or upload a file. Pick a model & adjust params (_optional_), and press **Summarize!**
+
+                See [the guide doc](https://gist.github.com/pszemraj/722a7ba443aa3a671b02d87038375519) for details.
+                """
+            )
+            with gr.Row(variant="compact"):
+                with gr.Column(scale=0.5, variant="compact"):
+                    model_name = gr.Dropdown(
+                        choices=MODEL_OPTIONS,
+                        value=MODEL_OPTIONS[0],
+                        label="Model Name",
+                    )
+                    num_beams = gr.Radio(
+                        choices=BEAM_OPTIONS,
+                        value=BEAM_OPTIONS[len(BEAM_OPTIONS) // 2],
+                        label="Beam Search: # of Beams",
+                    )
+                    load_examples_button = gr.Button(
+                        "Load Example in Dropdown",
+                    )
+                    load_file_button = gr.Button("Upload & Process File")
+                with gr.Column(variant="compact"):
+                    example_name = gr.Dropdown(
+                        _examples,
+                        label="Examples",
+                        value=random.choice(_examples),
+                    )
+                    uploaded_file = gr.File(
+                        label="File Upload",
+                        file_count="single",
+                        file_types=[".txt", ".md", ".pdf"],
+                        type="file",
+                    )
+            with gr.Row():
+                input_text = gr.Textbox(
+                    lines=4,
+                    max_lines=12,
+                    label="Text to Summarize",
+                    placeholder="Enter text to summarize, the text will be cleaned and truncated on Spaces. Narrative, academic (both papers and lecture transcription), and article text work well. May take a bit to generate depending on the input text :)",
+                )
+        gr.Markdown("---")
+        with gr.Column():
+            gr.Markdown("## Generate Summary")
+            with gr.Row():
+                summarize_button = gr.Button(
+                    "Summarize!",
+                    variant="primary",
+                )
+                gr.Markdown(
+                    "_Summarization should take ~1-2 minutes for most settings, but may extend up to 5-10 minutes in some scenarios._"
+                )
+            output_text = gr.HTML("<p><em>Output will appear below:</em></p>")
+            with gr.Column():
+                gr.Markdown("### Results & Scores")
+                with gr.Row():
+                    with gr.Column(variant="compact"):
+                        gr.Markdown(
+                            "Download the summary as a text file, with parameters and scores."
+                        )
+                        text_file = gr.File(
+                            label="Download as Text File",
+                            file_count="single",
+                            type="file",
+                            interactive=False,
+                        )
+                    with gr.Column(variant="compact"):
+                        gr.Markdown(
+                            "Scores **roughly** represent the summary quality as a measure of the model's 'confidence'. less-negative numbers (closer to 0) are better."
+                        )
+                        summary_scores = gr.Textbox(
+                            label="Summary Scores",
+                            placeholder="Summary scores will appear here",
+                        )
+            with gr.Column(variant="panel"):
+                gr.Markdown("### **Summary Output**")
+                summary_text = gr.HTML(
+                    label="Summary",
+                    value="<center><i>Summary will appear here!</i></center>",
+                )
+            with gr.Column():
+                gr.Markdown("### **Aggregate Summary Batches**")
+                gr.Markdown(
+                    "_Note: this is an experimental feature. Feedback welcome in the [discussions](https://hf.co/spaces/pszemraj/document-summarization/discussions)!_"
+                )
+                with gr.Row():
+                    aggregate_button = gr.Button(
+                        "Aggregate!",
+                        variant="primary",
+                    )
+                    gr.Markdown(
+                        f"""Aggregate the above batches into a cohesive summary.
+                    - A secondary instruct-tuned LM consolidates info
+                    - Current model: [{AGGREGATE_MODEL}](https://hf.co/{AGGREGATE_MODEL})
+                                """
+                    )
+                with gr.Column(variant="panel"):
+                    aggregated_summary = gr.HTML(
+                        label="Aggregate Summary",
+                        value="<center><i>Aggregate summary will appear here!</i></center>",
+                    )
+                    gr.Markdown(
+                        "\n\n_Aggregate summary is also appended to the bottom of the `.txt` file._"
+                    )
+
+        gr.Markdown("---")
+        with gr.Column():
+            gr.Markdown("### Advanced Settings")
+            gr.Markdown(
+                "Refer to [the guide doc](https://gist.github.com/pszemraj/722a7ba443aa3a671b02d87038375519) for what these are, and how they impact _quality_ and _speed_."
+            )
+            with gr.Row(variant="compact"):
+                length_penalty = gr.Slider(
+                    minimum=0.3,
+                    maximum=1.1,
+                    label="length penalty",
+                    value=0.7,
+                    step=0.05,
+                )
+                token_batch_length = gr.Radio(
+                    choices=TOKEN_BATCH_OPTIONS,
+                    label="token batch length",
+                    # select median option
+                    value=TOKEN_BATCH_OPTIONS[len(TOKEN_BATCH_OPTIONS) // 2],
+                )
+
+            with gr.Row(variant="compact"):
+                repetition_penalty = gr.Slider(
+                    minimum=1.0,
+                    maximum=5.0,
+                    label="repetition penalty",
+                    value=1.5,
+                    step=0.1,
+                )
+                no_repeat_ngram_size = gr.Radio(
+                    choices=[2, 3, 4, 5],
+                    label="no repeat ngram size",
+                    value=3,
+                )
+                predrop_stopwords = gr.Checkbox(
+                    label="Drop Stopwords (Pre-Truncation)",
+                    value=False,
+                )
+        with gr.Column():
+            gr.Markdown("## About")
+            gr.Markdown(
+                "- Models are fine-tuned on the [🅱️ookSum dataset](https://arxiv.org/abs/2105.08209). The goal was to create a model that generalizes well and is useful for summarizing text in academic and everyday use."
+            )
+            gr.Markdown(
+                "- _Update April 2023:_ Additional models fine-tuned on the [PLOS](https://hf.co/datasets/pszemraj/scientific_lay_summarisation-plos-norm) and [ELIFE](https://hf.co/datasets/pszemraj/scientific_lay_summarisation-elife-norm) subsets of the [scientific lay summaries](https://arxiv.org/abs/2210.09932) dataset are available (see dropdown at the top)."
+            )
+            gr.Markdown(
+                "Adjust the max input words & max PDF pages for OCR by duplicating this space and [setting the environment variables](https://hf.co/docs/hub/spaces-overview#managing-secrets) `APP_MAX_WORDS` and `APP_OCR_MAX_PAGES` to the desired integer values."
+            )
+            gr.Markdown("---")
+
+        load_examples_button.click(
+            fn=load_single_example_text, inputs=[example_name], outputs=[input_text]
+        )
+
+        load_file_button.click(
+            fn=load_uploaded_file, inputs=uploaded_file, outputs=[input_text]
+        )
+
+        summarize_button.click(
+            fn=proc_submission,
+            inputs=[
+                input_text,
+                model_name,
+                num_beams,
+                token_batch_length,
+                length_penalty,
+                repetition_penalty,
+                no_repeat_ngram_size,
+                predrop_stopwords,
+            ],
+            outputs=[output_text, summary_text, summary_scores, text_file],
+        )
+        aggregate_button.click(
+            fn=aggregate_text,
+            inputs=[summary_text, text_file],
+            outputs=[aggregated_summary],
+        )
+    demo.launch(enable_queue=True, share=args.share)

examples/AM Turing - The Imitation Game.txt

@@ -0,0 +1,442 @@
+A. M. Turing (1950) Computing Machinery and Intelligence. Mind 49: 433-460.
+
+
+
+
+
+COMPUTING MACHINERY AND INTELLIGENCE
+
+
+
+
+By A. M. Turing
+
+
+
+
+
+1. The Imitation Game
+
+
+I propose to consider the question, "Can machines think?" This should begin with definitions of the meaning of the terms "machine" and "think." The definitions might be framed so as to reflect so far as possible the normal use of the words, but this attitude is dangerous, If the meaning of the words "machine" and "think" are to be found by examining how they are commonly used it is difficult to escape the conclusion that the meaning and the answer to the question, "Can machines think?" is to be sought in a statistical survey such as a Gallup poll. But this is absurd. Instead of attempting such a definition I shall replace the question by another, which is closely related to it and is expressed in relatively unambiguous words.
+
+The new form of the problem can be described in terms of a game which we call the
+
+'imitation game." It is played with three people, a man (A), a woman (B), and an interrogator (C) who may be of either sex. The interrogator stays in a room apart front the other two. The object of the game for the interrogator is to determine which of the other two is the man and which is the woman. He knows them by labels X and Y, and at the end of the game he says either "X is A and Y is B" or "X is B and Y is A." The interrogator is allowed to put questions to A and B thus: C: Will X please tell me the length of his or her hair?
+
+Now suppose X is actually A, then A must answer. It is A's object in the game to try and cause C to make the wrong identification. His answer might therefore be:
+
+"My hair is shingled, and the longest strands are about nine inches long."
+
+In order that tones of voice may not help the interrogator the answers should be written, or better still, typewritten. The ideal arrangement is to have a teleprinter communicating between the two rooms. Alternatively the question and answers can be repeated by an intermediary. The object of the game for the third player (B) is to help the interrogator.
+
+The best strategy for her is probably to give truthful answers. She can add such things as
+
+"I am the woman, don't listen to him!" to her answers, but it will avail nothing as the man can make similar remarks.
+
+We now ask the question, "What will happen when a machine takes the part of A in this game?" Will the interrogator decide wrongly as often when the game is played like this as he does when the game is played between a man and a woman? These questions replace our original, "Can machines think?"
+
+2. Critique of the New Problem
+
+As well as asking, "What is the answer to this new form of the question," one may ask,
+
+"Is this new question a worthy one to investigate?" This latter question we investigate without further ado, thereby cutting short an infinite regress.
+
+The new problem has the advantage of drawing a fairly sharp line between the physical and the intellectual capacities of a man. No engineer or chemist claims to be able to produce a material which is indistinguishable from the human skin. It is possible that at some time this might be done, but even supposing this invention available we should feel there was little point in trying to make a "thinking machine" more human by dressing it up in such artificial flesh. The form in which we have set the problem reflects this fact in the condition which prevents the interrogator from seeing or touching the other competitors, or hearing -their voices. Some other advantages of the proposed criterion may be shown up by specimen questions and answers. Thus: Q: Please write me a sonnet on the subject of the Forth Bridge.
+
+A : Count me out on this one. I never could write poetry.
+
+Q: Add 34957 to 70764.
+
+A: (Pause about 30 seconds and then give as answer) 105621.
+
+Q: Do you play chess?
+
+A: Yes.
+
+Q: I have K at my K1, and no other pieces. You have only K at K6 and R at R1. It is your move. What do you play?
+
+A: (After a pause of 15 seconds) R-R8 mate.
+
+The question and answer method seems to be suitable for introducing almost any one of the fields of human endeavour that we wish to include. We do not wish to penalise the machine for its inability to shine in beauty competitions, nor to penalise a man for losing in a race against an aeroplane. The conditions of our game make these disabilities irrelevant. The "witnesses" can brag, if they consider it advisable, as much as they please about their charms, strength or heroism, but the interrogator cannot demand practical demonstrations.
+
+The game may perhaps be criticised on the ground that the odds are weighted too heavily against the machine. If the man were to try and pretend to be the machine he would clearly make a very poor showing. He would be given away at once by slowness and inaccuracy in arithmetic. May not machines carry out something which ought to be described as thinking but which is very different from what a man does? This objection is
+
+a very strong one, but at least we can say that if, nevertheless, a machine can be constructed to play the imitation game satisfactorily, we need not be troubled by this objection.
+
+It might be urged that when playing the "imitation game" the best strategy for the machine may possibly be something other than imitation of the behaviour of a man. This may be, but I think it is unlikely that there is any great effect of this kind. In any case there is no intention to investigate here the theory of the game, and it will be assumed that the best strategy is to try to provide answers that would naturally be given by a man.
+
+3. The Machines Concerned in the Game
+
+The question which we put in 1 will not be quite definite until we have specified what we mean by the word "machine." It is natural that we should wish to permit every kind of engineering technique to be used in our machines. We also wish to allow the possibility than an engineer or team of engineers may construct a machine which works, but whose manner of operation cannot be satisfactorily described by its constructors because they have applied a method which is largely experimental. Finally, we wish to exclude from the machines men born in the usual manner. It is difficult to frame the definitions so as to satisfy these three conditions. One might for instance insist that the team of engineers should be all of one sex, but this would not really be satisfactory, for it is probably possible to rear a complete individual from a single cell of the skin (say) of a man. To do so would be a feat of biological technique deserving of the very highest praise, but we would not be inclined to regard it as a case of "constructing a thinking machine." This prompts us to abandon the requirement that every kind of technique should be permitted.
+
+We are the more ready to do so in view of the fact that the present interest in "thinking machines" has been aroused by a particular kind of machine, usually called an "electronic computer" or "digital computer." Following this suggestion we only permit digital computers to take part in our game.
+
+This restriction appears at first sight to be a very drastic one. I shall attempt to show that it is not so in reality. To do this necessitates a short account of the nature and properties of these computers.
+
+It may also be said that this identification of machines with digital computers, like our criterion for "thinking," will only be unsatisfactory if (contrary to my belief), it turns out that digital computers are unable to give a good showing in the game.
+
+There are already a number of digital computers in working order, and it may be asked,
+
+"Why not try the experiment straight away? It would be easy to satisfy the conditions of the game. A number of interrogators could be used, and statistics compiled to show how often the right identification was given." The short answer is that we are not asking whether all digital computers would do well in the game nor whether the computers at present available would do well, but whether there are imaginable computers which would do well. But this is only the short answer. We shall see this question in a different light later.
+
+4. Digital Computers
+
+The idea behind digital computers may be explained by saying that these machines are intended to carry out any operations which could be done by a human computer. The human computer is supposed to be following fixed rules; he has no authority to deviate from them in any detail. We may suppose that these rules are supplied in a book, which is altered whenever he is put on to a new job. He has also an unlimited supply of paper on which he does his calculations. He may also do his multiplications and additions on a
+
+"desk machine," but this is not important.
+
+If we use the above explanation as a definition we shall be in danger of circularity of argument. We avoid this by giving an outline. of the means by which the desired effect is achieved. A digital computer can usually be regarded as consisting of three parts: (i) Store.
+
+(ii) Executive unit.
+
+(iii) Control.
+
+The store is a store of information, and corresponds to the human computer's paper, whether this is the paper on which he does his calculations or that on which his book of rules is printed. In so far as the human computer does calculations in his bead a part of the store will correspond to his memory.
+
+The executive unit is the part which carries out the various individual operations involved in a calculation. What these individual operations are will vary from machine to machine.
+
+Usually fairly lengthy operations can be done such as "Multiply 3540675445 by 7076345687" but in some machines only very simple ones such as "Write down 0" are possible.
+
+We have mentioned that the "book of rules" supplied to the computer is replaced in the machine by a part of the store. It is then called the "table of instructions." It is the duty of the control to see that these instructions are obeyed correctly and in the right order. The control is so constructed that this necessarily happens.
+
+The information in the store is usually broken up into packets of moderately small size. In one machine, for instance, a packet might consist of ten decimal digits. Numbers are assigned to the parts of the store in which the various packets of information are stored, in some systematic manner. A typical instruction might say-
+
+"Add the number stored in position 6809 to that in 4302 and put the result back into the latter storage position."
+
+Needless to say it would not occur in the machine expressed in English. It would more likely be coded in a form such as 6809430217. Here 17 says which of various possible
+
+operations is to be performed on the two numbers. In this case the)e operation is that described above, viz., "Add the number. . . ." It will be noticed that the instruction takes up 10 digits and so forms one packet of information, very conveniently. The control will normally take the instructions to be obeyed in the order of the positions in which they are stored, but occasionally an instruction such as
+
+"Now obey the instruction stored in position 5606, and continue from there"
+
+may be encountered, or again
+
+"If position 4505 contains 0 obey next the instruction stored in 6707, otherwise continue straight on."
+
+Instructions of these latter types are very important because they make it possible for a sequence of operations to be replaced over and over again until some condition is fulfilled, but in doing so to obey, not fresh instructions on each repetition, but the same ones over and over again. To take a domestic analogy. Suppose Mother wants Tommy to call at the cobbler's every morning on his way to school to see if her shoes are done, she can ask him afresh every morning. Alternatively she can stick up a notice once and for all in the hall which he will see when he leaves for school and which tells him to call for the shoes, and also to destroy the notice when he comes back if he has the shoes with him.
+
+The reader must accept it as a fact that digital computers can be constructed, and indeed have been constructed, according to the principles we have described, and that they can in fact mimic the actions of a human computer very closely.
+
+The book of rules which we have described our human computer as using is of course a convenient fiction. Actual human computers really remember what they have got to do. If one wants to make a machine mimic the behaviour of the human computer in some complex operation one has to ask him how it is done, and then translate the answer into the form of an instruction table. Constructing instruction tables is usually described as
+
+"programming." To "programme a machine to carry out the operation A" means to put the appropriate instruction table into the machine so that it will do A.
+
+An interesting variant on the idea of a digital computer is a "digital computer with a random element." These have instructions involving the throwing of a die or some equivalent electronic process; one such instruction might for instance be, "Throw the die and put the-resulting number into store 1000." Sometimes such a machine is described as having free will (though I would not use this phrase myself), It is not normally possible to determine from observing a machine whether it has a random element, for a similar effect can be produced by such devices as making the choices depend on the digits of the decimal for .
+
+Most actual digital computers have only a finite store. There is no theoretical difficulty in the idea of a computer with an unlimited store. Of course only a finite part can have been used at any one time. Likewise only a finite amount can have been constructed, but we
+
+can imagine more and more being added as required. Such computers have special theoretical interest and will be called infinitive capacity computers.
+
+The idea of a digital computer is an old one. Charles Babbage, Lucasian Professor of Mathematics at Cambridge from 1828 to 1839, planned such a machine, called the Analytical Engine, but it was never completed. Although Babbage had all the essential ideas, his machine was not at that time such a very attractive prospect. The speed which would have been available would be definitely faster than a human computer but something like I 00 times slower than the Manchester machine, itself one of the slower of the modern machines, The storage was to be purely mechanical, using wheels and cards.
+
+The fact that Babbage's Analytical Engine was to be entirely mechanical will help us to rid ourselves of a superstition. Importance is often attached to the fact that modern digital computers are electrical, and that the nervous system also is electrical. Since Babbage's machine was not electrical, and since all digital computers are in a sense equivalent, we see that this use of electricity cannot be of theoretical importance. Of course electricity usually comes in where fast signalling is concerned, so that it is not surprising that we find it in both these connections. In the nervous system chemical phenomena are at least as important as electrical. In certain computers the storage system is mainly acoustic. The feature of using electricity is thus seen to be only a very superficial similarity. If we wish to find such similarities we should took rather for mathematical analogies of function.
+
+
+
+
+
+5. Universality of Digital Computers
+
+
+The digital computers considered in the last section may be classified amongst the
+
+"discrete-state machines." These are the machines which move by sudden jumps or clicks from one quite definite state to another. These states are sufficiently different for the possibility of confusion between them to be ignored. Strictly speaking there, are no such machines. Everything really moves continuously. But there are many kinds of machine which can profitably be thought of as being discrete-state machines. For instance in considering the switches for a lighting system it is a convenient fiction that each switch must be definitely on or definitely off. There must be intermediate positions, but for most purposes we can forget about them. As an example of a discrete-state machine we might consider a wheel which clicks round through 120 once a second, but may be stopped by a
+
+]ever which can be operated from outside; in addition a lamp is to light in one of the positions of the wheel. This machine could be described abstractly as follows. The internal state of the machine (which is described by the position of the wheel) may be q1, q2 or q3. There is an input signal i0. or i1 (position of ]ever). The internal state at any moment is determined by the last state and input signal according to the table (TABLE DELETED)
+
+
+
+The output signals, the only externally visible indication of the internal state (the light) are described by the table
+
+State q1 q2 q3
+
+output o0 o0 o1
+
+This example is typical of discrete-state machines. They can be described by such tables provided they have only a finite number of possible states.
+
+It will seem that given the initial state of the machine and the input signals it is always possible to predict all future states, This is reminiscent of Laplace's view that from the complete state of the universe at one moment of time, as described by the positions and velocities of all particles, it should be possible to predict all future states. The prediction which we are considering is, however, rather nearer to practicability than that considered by Laplace. The system of the "universe as a whole" is such that quite small errors in the initial conditions can have an overwhelming effect at a later time. The displacement of a single electron by a billionth of a centimetre at one moment might make the difference between a man being killed by an avalanche a year later, or escaping. It is an essential property of the mechanical systems which we have called "discrete-state machines" that this phenomenon does not occur. Even when we consider the actual physical machines instead of the idealised machines, reasonably accurate knowledge of the state at one moment yields reasonably accurate knowledge any number of steps later.
+
+As we have mentioned, digital computers fall within the class of discrete-state machines.
+
+But the number of states of which such a machine is capable is usually enormously large.
+
+For instance, the number for the machine now working at Manchester is about 2 165,000, i.e., about 10 50,000. Compare this with our example of the clicking wheel described above, which had three states. It is not difficult to see why the number of states should be so immense. The computer includes a store corresponding to the paper used by a human computer. It must be possible to write into the store any one of the combinations of symbols which might have been written on the paper. For simplicity suppose that only digits from 0 to 9 are used as symbols. Variations in handwriting are ignored. Suppose the computer is allowed 100 sheets of paper each containing 50 lines each with room for 30 digits. Then the number of states is 10 100x50x30 i.e., 10 150,000 . This is about the number of states of three Manchester machines put together. The logarithm to the base two of the number of states is usually called the "storage capacity" of the machine. Thus the Manchester machine has a storage capacity of about 165,000 and the wheel machine of our example about 1.6. If two machines are put together their capacities must be added to obtain the capacity of the resultant machine. This leads to the possibility of statements such as "The Manchester machine contains 64 magnetic tracks each with a capacity of 2560, eight electronic tubes with a capacity of 1280. Miscellaneous storage amounts to about 300 making a total of 174,380."
+
+Given the table corresponding to a discrete-state machine it is possible to predict what it will do. There is no reason why this calculation should not be carried out by means of a digital computer. Provided it could be carried out sufficiently quickly the digital computer could mimic the behavior of any discrete-state machine. The imitation game could then be played with the machine in question (as B) and the mimicking digital
+
+computer (as A) and the interrogator would be unable to distinguish them. Of course the digital computer must have an adequate storage capacity as well as working sufficiently fast. Moreover, it must be programmed afresh for each new machine which it is desired to mimic.
+
+This special property of digital computers, that they can mimic any discrete-state machine, is described by saying that they are universal machines. The existence of machines with this property has the important consequence that, considerations of speed apart, it is unnecessary to design various new machines to do various computing processes. They can all be done with one digital computer, suitably programmed for each case. It 'ill be seen that as a consequence of this all digital computers are in a sense equivalent.
+
+We may now consider again the point raised at the end of §3. It was suggested tentatively that the question, "Can machines think?" should be replaced by "Are there imaginable digital computers which would do well in the imitation game?" If we wish we can make this superficially more general and ask "Are there discrete-state machines which would do well?" But in view of the universality property we see that either of these questions is equivalent to this, "Let us fix our attention on one particular digital computer C. Is it true that by modifying this computer to have an adequate storage, suitably increasing its speed of action, and providing it with an appropriate programme, C can be made to play satisfactorily the part of A in the imitation game, the part of B being taken by a man?"
+
+6. Contrary Views on the Main Question
+
+We may now consider the ground to have been cleared and we are ready to proceed to the debate on our question, "Can machines think?" and the variant of it quoted at the end of the last section. We cannot altogether abandon the original form of the problem, for opinions will differ as to the appropriateness of the substitution and we must at least listen to what has to be said in this connexion.
+
+It will simplify matters for the reader if I explain first my own beliefs in the matter.
+
+Consider first the more accurate form of the question. I believe that in about fifty years'
+
+time it will be possible, to programme computers, with a storage capacity of about 109, to make them play the imitation game so well that an average interrogator will not have more than 70 per cent chance of making the right identification after five minutes of questioning. The original question, "Can machines think?" I believe to be too meaningless to deserve discussion. Nevertheless I believe that at the end of the century the use of words and general educated opinion will have altered so much that one will be able to speak of machines thinking without expecting to be contradicted. I believe further that no useful purpose is served by concealing these beliefs. The popular view that scientists proceed inexorably from well-established fact to well-established fact, never being influenced by any improved conjecture, is quite mistaken. Provided it is made clear which are proved facts and which are conjectures, no harm can result. Conjectures are of great importance since they suggest useful lines of research.
+
+I now proceed to consider opinions opposed to my own.
+
+(1) The Theological Objection
+
+Thinking is a function of man's immortal soul. God has given an immortal soul to every man and woman, but not to any other animal or to machines. Hence no animal or machine can think.
+
+I am unable to accept any part of this, but will attempt to reply in theological terms. I should find the argument more convincing if animals were classed with men, for there is a greater difference, to my mind, between the typical animate and the inanimate than there is between man and the other animals. The arbitrary character of the orthodox view becomes clearer if we consider how it might appear to a member of some other religious community. How do Christians regard the Moslem view that women have no souls? But let us leave this point aside and return to the main argument. It appears to me that the argument quoted above implies a serious restriction of the omnipotence of the Almighty.
+
+It is admitted that there are certain things that He cannot do such as making one equal to two, but should we not believe that He has freedom to confer a soul on an elephant if He sees fit? We might expect that He would only exercise this power in conjunction with a mutation which provided the elephant with an appropriately improved brain to minister to the needs of this sort[. An argument of exactly similar form may be made for the case of machines. It may seem different because it is more difficult to "swallow." But this really only means that we think it would be less likely that He would consider the circumstances suitable for conferring a soul. The circumstances in question are discussed in the rest of this paper. In attempting to construct such machines we should not be irreverently usurping His power of creating souls, any more than we are in the procreation of children: rather we are, in either case, instruments of His will providing
+
+.mansions for the souls that He creates.
+
+However, this is mere speculation. I am not very impressed with theological arguments whatever they may be used to support. Such arguments have often been found unsatisfactory in the past. In the time of Galileo it was argued that the texts, "And the sun stood still . . . and hasted not to go down about a whole day" (Joshua x. 13) and "He laid the foundations of the earth, that it should not move at any time" (Psalm cv. 5) were an adequate refutation of the Copernican theory. With our present knowledge such an argument appears futile. When that knowledge was not available it made a quite different impression.
+
+(2) The "Heads in the Sand" Objection
+
+The consequences of machines thinking would be too dreadful. Let us hope and believe that they cannot do so."
+
+This argument is seldom expressed quite so openly as in the form above. But it affects most of us who think about it at all. We like to believe that Man is in some subtle way superior to the rest of creation. It is best if he can be shown to be necessarily superior, for
+
+then there is no danger of him losing his commanding position. The popularity of the theological argument is clearly connected with this feeling. It is likely to be quite strong in intellectual people, since they value the power of thinking more highly than others, and are more inclined to base their belief in the superiority of Man on this power.
+
+I do not think that this argument is sufficiently substantial to require refutation.
+
+Consolation would be more appropriate: perhaps this should be sought in the transmigration of souls.
+
+(3) The Mathematical Objection
+
+There are a number of results of mathematical logic which can be used to show that there are limitations to the powers of discrete-state machines. The best known of these results is known as Godel's theorem ( 1931 ) and shows that in any sufficiently powerful logical system statements can be formulated which can neither be proved nor disproved within the system, unless possibly the system itself is inconsistent. There are other, in some respects similar, results due to Church (1936), Kleene (1935), Rosser, and Turing (1937).
+
+The latter result is the most convenient to consider, since it refers directly to machines, whereas the others can only be used in a comparatively indirect argument: for instance if Godel's theorem is to be used we need in addition to have some means of describing logical systems in terms of machines, and machines in terms of logical systems. The result in question refers to a type of machine which is essentially a digital computer with an infinite capacity. It states that there are certain things that such a machine cannot do. If it is rigged up to give answers to questions as in the imitation game, there will be some questions to which it will either give a wrong answer, or fail to give an answer at all however much time is allowed for a reply. There may, of course, be many such questions, and questions which cannot be answered by one machine may be satisfactorily answered by another. We are of course supposing for the present that the questions are of the kind to which an answer "Yes" or "No" is appropriate, rather than questions such as "What do you think of Picasso?" The questions that we know the machines must fail on are of this type, "Consider the machine specified as follows. . . . Will this machine ever answer 'Yes'
+
+to any question?" The dots are to be replaced by a description of some machine in a standard form, which could be something like that used in §5. When the machine described bears a certain comparatively simple relation to the machine which is under interrogation, it can be shown that the answer is either wrong or not forthcoming. This is the mathematical result: it is argued that it proves a disability of machines to which the human intellect is not subject.
+
+The short answer to this argument is that although it is established that there are limitations to the Powers If any particular machine, it has only been stated, without any sort of proof, that no such limitations apply to the human intellect. But I do not think this view can be dismissed quite so lightly. Whenever one of these machines is asked the appropriate critical question, and gives a definite answer, we know that this answer must be wrong, and this gives us a certain feeling of superiority. Is this feeling illusory? It is no doubt quite genuine, but I do not think too much importance should be attached to it. We too often give wrong answers to questions ourselves to be justified in being very pleased
+
+at such evidence of fallibility on the part of the machines. Further, our superiority can only be felt on such an occasion in relation to the one machine over which we have scored our petty triumph. There would be no question of triumphing simultaneously over all machines. In short, then, there might be men cleverer than any given machine, but then again there might be other machines cleverer again, and so on.
+
+Those who hold to the mathematical argument would, I think, mostly he willing to accept the imitation game as a basis for discussion, Those who believe in the two previous objections would probably not be interested in any criteria.
+
+(4) The Argument from Consciousness
+
+This argument is very, well expressed in Professor Jefferson's Lister Oration for 1949, from which I quote. "Not until a machine can write a sonnet or compose a concerto because of thoughts and emotions felt, and not by the chance fall of symbols, could we agree that machine equals brain-that is, not only write it but know that it had written it.
+
+No mechanism could feel (and not merely artificially signal, an easy contrivance) pleasure at its successes, grief when its valves fuse, be warmed by flattery, be made miserable by its mistakes, be charmed by sex, be angry or depressed when it cannot get what it wants."
+
+This argument appears to be a denial of the validity of our test. According to the most extreme form of this view the only way by which one could be sure that machine thinks is to be the machine and to feel oneself thinking. One could then describe these feelings to the world, but of course no one would be justified in taking any notice. Likewise according to this view the only way to know that a man thinks is to be that particular man. It is in fact the solipsist point of view. It may be the most logical view to hold but it makes communication of ideas difficult. A is liable to believe "A thinks but B does not"
+
+whilst B believes "B thinks but A does not." instead of arguing continually over this point it is usual to have the polite convention that everyone thinks.
+
+I am sure that Professor Jefferson does not wish to adopt the extreme and solipsist point of view. Probably he would be quite willing to accept the imitation game as a test. The game (with the player B omitted) is frequently used in practice under the name of viva voce to discover whether some one really understands something or has "learnt it parrot fashion." Let us listen in to a part of such a viva voce: Interrogator: In the first line of your sonnet which reads "Shall I compare thee to a summer's day," would not "a spring day" do as well or better?
+
+Witness: It wouldn't scan.
+
+Interrogator: How about "a winter's day," That would scan all right.
+
+Witness: Yes, but nobody wants to be compared to a winter's day.
+
+Interrogator: Would you say Mr. Pickwick reminded you of Christmas?
+
+Witness: In a way.
+
+Interrogator: Yet Christmas is a winter's day, and I do not think Mr. Pickwick would mind the comparison.
+
+Witness: I don't think you're serious. By a winter's day one means a typical winter's day, rather than a special one like Christmas.
+
+And so on, What would Professor Jefferson say if the sonnet-writing machine was able to answer like this in the viva voce? I do not know whether he would regard the machine as
+
+"merely artificially signalling" these answers, but if the answers were as satisfactory and sustained as in the above passage I do not think he would describe it as "an easy contrivance." This phrase is, I think, intended to cover such devices as the inclusion in the machine of a record of someone reading a sonnet, with appropriate switching to turn it on from time to time.
+
+In short then, I think that most of those who support the argument from consciousness could be persuaded to abandon it rather than be forced into the solipsist position. They will then probably be willing to accept our test.
+
+I do not wish to give the impression that I think there is no mystery about consciousness.
+
+There is, for instance, something of a paradox connected with any attempt to localise it.
+
+But I do not think these mysteries necessarily need to be solved before we can answer the question with which we are concerned in this paper.
+
+(5) Arguments from Various Disabilities
+
+These arguments take the form, "I grant you that you can make machines do all the things you have mentioned but you will never be able to make one to do X." Numerous features X are suggested in this connexion I offer a selection:
+
+Be kind, resourceful, beautiful, friendly, have initiative, have a sense of humour, tell right from wrong, make mistakes, fall in love, enjoy strawberries and cream, make some one fall in love with it, learn from experience, use words properly, be the subject of its own thought, have as much diversity of behaviour as a man, do something really new.
+
+No support is usually offered for these statements. I believe they are mostly founded on the principle of scientific induction. A man has seen thousands of machines in his lifetime. From what he sees of them he draws a number of general conclusions. They are ugly, each is designed for a very limited purpose, when required for a minutely different purpose they are useless, the variety of behaviour of any one of them is very small, etc., etc. Naturally he concludes that these are necessary properties of machines in general.
+
+Many of these limitations are associated with the very small storage capacity of most machines. (I am assuming that the idea of storage capacity is extended in some way to
+
+cover machines other than discrete-state machines. The exact definition does not matter as no mathematical accuracy is claimed in the present discussion,) A few years ago, when very little had been heard of digital computers, it was possible to elicit much incredulity concerning them, if one mentioned their properties without describing their construction.
+
+That was presumably due to a similar application of the principle of scientific induction.
+
+These applications of the principle are of course largely unconscious. When a burnt child fears the fire and shows that he fears it by avoiding it, f should say that he was applying scientific induction. (I could of course also describe his behaviour in many other ways.) The works and customs of mankind do not seem to be very suitable material to which to apply scientific induction. A very large part of space-time must be investigated, if reliable results are to be obtained. Otherwise we may (as most English 'Children do) decide that everybody speaks English, and that it is silly to learn French.
+
+There are, however, special remarks to be made about many of the disabilities that have been mentioned. The inability to enjoy strawberries and cream may have struck the reader as frivolous. Possibly a machine might be made to enjoy this delicious dish, but any attempt to make one do so would be idiotic. What is important about this disability is that it contributes to some of the other disabilities, e.g., to the difficulty of the same kind of friendliness occurring between man and machine as between white man and white man, or between black man and black man.
+
+The claim that "machines cannot make mistakes" seems a curious one. One is tempted to retort, "Are they any the worse for that?" But let us adopt a more sympathetic attitude, and try to see what is really meant. I think this criticism can be explained in terms of the imitation game. It is claimed that the interrogator could distinguish the machine from the man simply by setting them a number of problems in arithmetic. The machine would be unmasked because of its deadly accuracy. The reply to this is simple. The machine (programmed for playing the game) would not attempt to give the right answers to the arithmetic problems. It would deliberately introduce mistakes in a manner calculated to confuse the interrogator. A mechanical fault would probably show itself through an unsuitable decision as to what sort of a mistake to make in the arithmetic. Even this interpretation of the criticism is not sufficiently sympathetic. But we cannot afford the space to go into it much further. It seems to me that this criticism depends on a confusion between two kinds of mistake, We may call them "errors of functioning" and "errors of conclusion." Errors of functioning are due to some mechanical or electrical fault which causes the machine to behave otherwise than it was designed to do. In philosophical discussions one likes to ignore the possibility of such errors; one is therefore discussing
+
+"abstract machines." These abstract machines are mathematical fictions rather than physical objects. By definition they are incapable of errors of functioning. In this sense we can truly say that "machines can never make mistakes." Errors of conclusion can only arise when some meaning is attached to the output signals from the machine. The machine might, for instance, type out mathematical equations, or sentences in English.
+
+When a false proposition is typed we say that the machine has committed an error of conclusion. There is clearly no reason at all for saying that a machine cannot make this kind of mistake. It might do nothing but type out repeatedly "O = I." To take a less
+
+perverse example, it might have some method for drawing conclusions by scientific induction. We must expect such a method to lead occasionally to erroneous results.
+
+The claim that a machine cannot be the subject of its own thought can of course only be answered if it can be shown that the machine has some thought with some subject matter.
+
+Nevertheless, "the subject matter of a machine's operations" does seem to mean something, at least to the people who deal with it. If, for instance, the machine was trying to find a solution of the equation x2 - 40x - 11 = 0 one would be tempted to describe this equation as part of the machine's subject matter at that moment. In this sort of sense a machine undoubtedly can be its own subject matter. It may be used to help in making up its own programmes, or to predict the effect of alterations in its own structure. By observing the results of its own behaviour it can modify its own programmes so as to achieve some purpose more effectively. These are possibilities of the near future, rather than Utopian dreams.
+
+The criticism that a machine cannot have much diversity of behaviour is just a way of saying that it cannot have much storage capacity. Until fairly recently a storage capacity of even a thousand digits was very rare.
+
+The criticisms that we are considering here are often disguised forms of the argument from consciousness, Usually if one maintains that a machine can do one of these things, and describes the kind of method that the machine could use, one will not make much of an impression. It is thought that tile method (whatever it may be, for it must be mechanical) is really rather base. Compare the parentheses in Jefferson's statement quoted on page 22.
+
+(6) Lady Lovelace's Objection
+
+Our most detailed information of Babbage's Analytical Engine comes from a memoir by Lady Lovelace ( 1842). In it she states, "The Analytical Engine has no pretensions to originate anything. It can do whatever we know how to order it to perform" (her italics).
+
+This statement is quoted by Hartree ( 1949) who adds: "This does not imply that it may not be possible to construct electronic equipment which will 'think for itself,' or in which, in biological terms, one could set up a conditioned reflex, which would serve as a basis for 'learning.' Whether this is possible in principle or not is a stimulating and exciting question, suggested by some of these recent developments But it did not seem that the machines constructed or projected at the time had this property."
+
+I am in thorough agreement with Hartree over this. It will be noticed that he does not assert that the machines in question had not got the property, but rather that the evidence available to Lady Lovelace did not encourage her to believe that they had it. It is quite possible that the machines in question had in a sense got this property. For suppose that some discrete-state machine has the property. The Analytical Engine was a universal digital computer, so that, if its storage capacity and speed were adequate, it could by suitable programming be made to mimic the machine in question. Probably this argument
+
+did not occur to the Countess or to Babbage. In any case there was no obligation on them to claim all that could be claimed.
+
+This whole question will be considered again under the heading of learning machines.
+
+A variant of Lady Lovelace's objection states that a machine can "never do anything really new." This may be parried for a moment with the saw, "There is nothing new under the sun." Who can be certain that "original work" that he has done was not simply the growth of the seed planted in him by teaching, or the effect of following well-known general principles. A better variant of the objection says that a machine can never "take us by surprise." This statement is a more direct challenge and can be met directly.
+
+Machines take me by surprise with great frequency. This is largely because I do not do sufficient calculation to decide what to expect them to do, or rather because, although I do a calculation, I do it in a hurried, slipshod fashion, taking risks. Perhaps I say to myself, "I suppose the Voltage here ought to he the same as there: anyway let's assume it is." Naturally I am often wrong, and the result is a surprise for me for by the time the experiment is done these assumptions have been forgotten. These admissions lay me open to lectures on the subject of my vicious ways, but do not throw any doubt on my credibility when I testify to the surprises I experience.
+
+I do not expect this reply to silence my critic. He will probably say that h surprises are due to some creative mental act on my part, and reflect no credit on the machine. This leads us back to the argument from consciousness, and far from the idea of surprise. It is a line of argument we must consider closed, but it is perhaps worth remarking that the appreciation of something as surprising requires as much of a "creative mental act"
+
+whether the surprising event originates from a man, a book, a machine or anything else.
+
+The view that machines cannot give rise to surprises is due, I believe, to a fallacy to which philosophers and mathematicians are particularly subject. This is the assumption that as soon as a fact is presented to a mind all consequences of that fact spring into the mind simultaneously with it. It is a very useful assumption under many circumstances, but one too easily forgets that it is false. A natural consequence of doing so is that one then assumes that there is no virtue in the mere working out of consequences from data and general principles.
+
+(7) Argument from Continuity in the Nervous System
+
+The nervous system is certainly not a discrete-state machine. A small error in the information about the size of a nervous impulse impinging on a neuron, may make a large difference to the size of the outgoing impulse. It may be argued that, this being so, one cannot expect to be able to mimic the behaviour of the nervous system with a discrete-state system.
+
+It is true that a discrete-state machine must be different from a continuous machine. But if we adhere to the conditions of the imitation game, the interrogator will not be able to take any advantage of this difference. The situation can be made clearer if we consider sonic
+
+other simpler continuous machine. A differential analyser will do very well. (A differential analyser is a certain kind of machine not of the discrete-state type used for some kinds of calculation.) Some of these provide their answers in a typed form, and so are suitable for taking part in the game. It would not be possible for a digital computer to predict exactly what answers the differential analyser would give to a problem, but it would be quite capable of giving the right sort of answer. For instance, if asked to give the value of (actually about 3.1416) it would be reasonable to choose at random between the values 3.12, 3.13, 3.14, 3.15, 3.16 with the probabilities of 0.05, 0.15, 0.55, 0.19, 0.06
+
+(say). Under these circumstances it would be very difficult for the interrogator to distinguish the differential analyser from the digital computer.
+
+(8) The Argument from Informality of Behaviour
+
+It is not possible to produce a set of rules purporting to describe what a man should do in every conceivable set of circumstances. One might for instance have a rule that one is to stop when one sees a red traffic light, and to go if one sees a green one, but what if by some fault both appear together? One may perhaps decide that it is safest to stop. But some further difficulty may well arise from this decision later. To attempt to provide rules of conduct to cover every eventuality, even those arising from traffic lights, appears to be impossible. With all this I agree.
+
+From this it is argued that we cannot be machines. I shall try to reproduce the argument, but I fear I shall hardly do it justice. It seems to run something like this. "if each man had a definite set of rules of conduct by which he regulated his life he would be no better than a machine. But there are no such rules, so men cannot be machines." The undistributed middle is glaring. I do not think the argument is ever put quite like this, but I believe this is the argument used nevertheless. There may however be a certain confusion between
+
+"rules of conduct" and "laws of behaviour" to cloud the issue. By "rules of conduct" I mean precepts such as "Stop if you see red lights," on which one can act, and of which one can be conscious. By "laws of behaviour" I mean laws of nature as applied to a man's body such as "if you pinch him he will squeak." If we substitute "laws of behaviour which regulate his life" for "laws of conduct by which he regulates his life" in the argument quoted the undistributed middle is no longer insuperable. For we believe that it is not only true that being regulated by laws of behaviour implies being some sort of machine (though not necessarily a discrete-state machine), but that conversely being such a machine implies being regulated by such laws. However, we cannot so easily convince ourselves of the absence of complete laws of behaviour as of complete rules of conduct.
+
+The only way we know of for finding such laws is scientific observation, and we certainly know of no circumstances under which we could say, "We have searched enough. There are no such laws."
+
+We can demonstrate more forcibly that any such statement would be unjustified. For suppose we could be sure of finding such laws if they existed. Then given a discrete-state machine it should certainly be possible to discover by observation sufficient about it to predict its future behaviour, and this within a reasonable time, say a thousand years. But this does not seem to be the case. I have set up on the Manchester computer a small
+
+programme using only 1,000 units of storage, whereby the machine supplied with one sixteen-figure number replies with another within two seconds. I would defy anyone to learn from these replies sufficient about the programme to be able to predict any replies to untried values.
+
+(9) The Argument from Extrasensory Perception
+
+I assume that the reader is familiar with the idea of extrasensory perception, and the meaning of the four items of it, viz., telepathy, clairvoyance, precognition and psychokinesis. These disturbing phenomena seem to deny all our usual scientific ideas.
+
+How we should like to discredit them! Unfortunately the statistical evidence, at least for telepathy, is overwhelming. It is very difficult to rearrange one's ideas so as to fit these new facts in. Once one has accepted them it does not seem a very big step to believe in ghosts and bogies. The idea that our bodies move simply according to the known laws of physics, together with some others not yet discovered but somewhat similar, would be one of the first to go.
+
+This argument is to my mind quite a strong one. One can say in reply that many scientific theories seem to remain workable in practice, in spite of clashing with ESP; that in fact one can get along very nicely if one forgets about it. This is rather cold comfort, and one fears that thinking is just the kind of phenomenon where ESP may be especially relevant.
+
+A more specific argument based on ESP might run as follows: "Let us play the imitation game, using as witnesses a man who is good as a telepathic receiver, and a digital computer. The interrogator can ask such questions as 'What suit does the card in my right hand belong to?' The man by telepathy or clairvoyance gives the right answer 130 times out of 400 cards. The machine can only guess at random, and perhaps gets 104 right, so the interrogator makes the right identification." There is an interesting possibility which opens here. Suppose the digital computer contains a random number generator. Then it will be natural to use this to decide what answer to give. But then the random number generator will be subject to the psychokinetic powers of the interrogator. Perhaps this psychokinesis might cause the machine to guess right more often than would be expected on a probability calculation, so that the interrogator might still be unable to make the right identification. On the other hand, he might be able to guess right without any questioning, by clairvoyance. With ESP anything may happen.
+
+If telepathy is admitted it will be necessary to tighten our test up. The situation could be regarded as analogous to that which would occur if the interrogator were talking to himself and one of the competitors was listening with his ear to the wall. To put the competitors into a "telepathy-proof room" would satisfy all requirements.
+
+
+
+
+
+7. Learning Machines
+
+
+The reader will have anticipated that I have no very convincing arguments of a positive nature to support my views. If I had I should not have taken such pains to point out the fallacies in contrary views. Such evidence as I have I shall now give.
+
+Let us return for a moment to Lady Lovelace's objection, which stated that the machine can only do what we tell it to do. One could say that a man can "inject" an idea into the machine, and that it will respond to a certain extent and then drop into quiescence, like a piano string struck by a hammer. Another simile would be an atomic pile of less than critical size: an injected idea is to correspond to a neutron entering the pile from without.
+
+Each such neutron will cause a certain disturbance which eventually dies away. If, however, the size of the pile is sufficiently increased, tire disturbance caused by such an incoming neutron will very likely go on and on increasing until the whole pile is destroyed. Is there a corresponding phenomenon for minds, and is there one for machines? There does seem to be one for the human mind. The majority of them seem to be "subcritical," i.e., to correspond in this analogy to piles of subcritical size. An idea presented to such a mind will on average give rise to less than one idea in reply. A smallish proportion are supercritical. An idea presented to such a mind that may give rise to a whole "theory" consisting of secondary, tertiary and more remote ideas. Animals minds seem to be very definitely subcritical. Adhering to this analogy we ask, "Can a machine be made to be supercritical?"
+
+The "skin-of-an-onion" analogy is also helpful. In considering the functions of the mind or the brain we find certain operations which we can explain in purely mechanical terms.
+
+This we say does not correspond to the real mind: it is a sort of skin which we must strip off if we are to find the real mind. But then in what remains we find a further skin to be stripped off, and so on. Proceeding in this way do we ever come to the "real" mind, or do we eventually come to the skin which has nothing in it? In the latter case the whole mind is mechanical. (It would not be a discrete-state machine however. We have discussed this.)
+
+These last two paragraphs do not claim to be convincing arguments. They should rather be described as "recitations tending to produce belief."
+
+The only really satisfactory support that can be given for the view expressed at the beginning of §6, will be that provided by waiting for the end of the century and then doing the experiment described. But what can we say in the meantime? What steps should be taken now if the experiment is to be successful?
+
+As I have explained, the problem is mainly one of programming. Advances in engineering will have to be made too, but it seems unlikely that these will not be adequate for the requirements. Estimates of the storage capacity of the brain vary from 1010 to 1015 binary digits. I incline to the lower values and believe that only a very small fraction is used for the higher types of thinking. Most of it is probably used for the retention of visual impressions, I should be surprised if more than 109 was required for satisfactory playing of the imitation game, at any rate against a blind man. (Note: The capacity of the Encyclopaedia Britannica, 11th edition, is 2 X 109) A storage capacity of 107, would be a very practicable possibility even by present techniques. It is probably not necessary to increase the speed of operations of the machines at all. Parts of modern machines which can be regarded as analogs of nerve cells work about a thousand times faster than the latter. This should provide a "margin of safety" which could cover losses
+
+of speed arising in many ways, Our problem then is to find out how to programme these machines to play the game. At my present rate of working I produce about a thousand digits of progratiirne a day, so that about sixty workers, working steadily through the fifty years might accomplish the job, if nothing went into the wastepaper basket. Some more expeditious method seems desirable.
+
+In the process of trying to imitate an adult human mind we are bound to think a good deal about the process which has brought it to the state that it is in. We may notice three components.
+
+(a) The initial state of the mind, say at birth,
+
+(b) The education to which it has been subjected,
+
+(c) Other experience, not to be described as education, to which it has been subjected.
+
+Instead of trying to produce a programme to simulate the adult mind, why not rather try to produce one which simulates the child's? If this were then subjected to an appropriate course of education one would obtain the adult brain. Presumably the child brain is something like a notebook as one buys it from the stationer's. Rather little mechanism, and lots of blank sheets. (Mechanism and writing are from our point of view almost synonymous.) Our hope is that there is so little mechanism in the child brain that something like it can be easily programmed. The amount of work in the education we can assume, as a first approximation, to be much the same as for the human child.
+
+We have thus divided our problem into two parts. The child programme and the education process. These two remain very closely connected. We cannot expect to find a good child machine at the first attempt. One must experiment with teaching one such machine and see how well it learns. One can then try another and see if it is better or worse. There is an obvious connection between this process and evolution, by the identifications
+
+Structure of the child machine = hereditary material
+
+Changes of the child machine = mutation,
+
+Natural selection = judgment of the experimenter
+
+One may hope, however, that this process will be more expeditious than evolution. The survival of the fittest is a slow method for measuring advantages. The experimenter, by the exercise of intelligence, should he able to speed it up. Equally important is the fact that he is not restricted to random mutations. If he can trace a cause for some weakness he can probably think of the kind of mutation which will improve it.
+
+It will not be possible to apply exactly the same teaching process to the machine as to a normal child. It will not, for instance, be provided with legs, so that it could not be asked
+
+to go out and fill the coal scuttle. Possibly it might not have eyes. But however well these deficiencies might be overcome by clever engineering, one could not send the creature to school without the other children making excessive fun of it. It must be given some tuition. We need not be too concerned about the legs, eyes, etc. The example of Miss Helen Keller shows that education can take place provided that communication in both directions between teacher and pupil can take place by some means or other.
+
+We normally associate punishments and rewards with the teaching process. Some simple child machines can be constructed or programmed on this sort of principle. The machine has to be so constructed that events which shortly preceded the occurrence of a punishment signal are unlikely to be repeated, whereas a reward signal increased the probability of repetition of the events which led up to it. These definitions do not presuppose any feelings on the part of the machine, I have done some experiments with one such child machine, and succeeded in teaching it a few things, but the teaching method was too unorthodox for the experiment to be considered really successful.
+
+The use of punishments and rewards can at best be a part of the teaching process.
+
+Roughly speaking, if the teacher has no other means of communicating to the pupil, the amount of information which can reach him does not exceed the total number of rewards and punishments applied. By the time a child has learnt to repeat "Casabianca" he would probably feel very sore indeed, if the text could only be discovered by a "Twenty Questions" technique, every "NO" taking the form of a blow. It is necessary therefore to have some other "unemotional" channels of communication. If these are available it is possible to teach a machine by punishments and rewards to obey orders given in some language, e.g., a symbolic language. These orders are to be transmitted through the
+
+"unemotional" channels. The use of this language will diminish greatly the number of punishments and rewards required.
+
+Opinions may vary as to the complexity which is suitable in the child machine. One might try to make it as simple as possible consistently with the general principles.
+
+Alternatively one might have a complete system of logical inference "built in."' In the latter case the store would be largely occupied with definitions and propositions. The propositions would have various kinds of status, e.g., well-established facts, conjectures, mathematically proved theorems, statements given by an authority, expressions having the logical form of proposition but not belief-value. Certain propositions may be described as "imperatives." The machine should be so constructed that as soon as an imperative is classed as "well established" the appropriate action automatically takes place. To illustrate this, suppose the teacher says to the machine, "Do your homework now." This may cause "Teacher says 'Do your homework now' " to be included amongst the well-established facts. Another such fact might be, "Everything that teacher says is true." Combining these may eventually lead to the imperative, "Do your homework now,"
+
+being included amongst the well-established facts, and this, by the construction of the machine, will mean that the homework actually gets started, but the effect is very satisfactory. The processes of inference used by the machine need not be such as would satisfy the most exacting logicians. There might for instance be no hierarchy of types. But this need not mean that type fallacies will occur, any more than we are bound to fall over
+
+unfenced cliffs. Suitable imperatives (expressed within the systems, not forming part of the rules of the system) such as "Do not use a class unless it is a subclass of one which has been mentioned by teacher" can have a similar effect to "Do not go too near the edge."
+
+The imperatives that can be obeyed by a machine that has no limbs are bound to be of a rather intellectual character, as in the example (doing homework) given above. important amongst such imperatives will be ones which regulate the order in which the rules of the logical system concerned are to be applied, For at each stage when one is using a logical system, there is a very large number of alternative steps, any of which one is permitted to apply, so far as obedience to the rules of the logical system is concerned. These choices make the difference between a brilliant and a footling reasoner, not the difference between a sound and a fallacious one. Propositions leading to imperatives of this kind might be "When Socrates is mentioned, use the syllogism in Barbara" or "If one method has been proved to be quicker than another, do not use the slower method." Some of these may be "given by authority," but others may be produced by the machine itself, e.g.
+
+by scientific induction.
+
+The idea of a learning machine may appear paradoxical to some readers. How can the rules of operation of the machine change? They should describe completely how the machine will react whatever its history might be, whatever changes it might undergo. The rules are thus quite time-invariant. This is quite true. The explanation of the paradox is that the rules which get changed in the learning process are of a rather less pretentious kind, claiming only an ephemeral validity. The reader may draw a parallel with the Constitution of the United States.
+
+An important feature of a learning machine is that its teacher will often be very largely ignorant of quite what is going on inside, although he may still be able to some extent to predict his pupil's behavior. This should apply most strongly to the later education of a machine arising from a child machine of well-tried design (or programme). This is in clear contrast with normal procedure when using a machine to do computations one's object is then to have a clear mental picture of the state of the machine at each moment in the computation. This object can only be achieved with a struggle. The view that "the machine can only do what we know how to order it to do,"' appears strange in face of this. Most of the programmes which we can put into the machine will result in its doing something that we cannot make sense (if at all, or which we regard as completely random behaviour. Intelligent behaviour presumably consists in a departure from the completely disciplined behaviour involved in computation, but a rather slight one, which does not give rise to random behaviour, or to pointless repetitive loops. Another important result of preparing our machine for its part in the imitation game by a process of teaching and learning is that "human fallibility" is likely to be omitted in a rather natural way, i.e., without special "coaching." (The reader should reconcile this with the point of view on pages 23 and 24.) Processes that are learnt do not produce a hundred per cent certainty of result; if they did they could not be unlearnt.
+
+It is probably wise to include a random element in a learning machine. A random element is rather useful when we are searching for a solution of some problem. Suppose for instance we wanted to find a number between 50 and 200 which was equal to the square of the sum of its digits, we might start at 51 then try 52 and go on until we got a number that worked. Alternatively we might choose numbers at random until we got a good one.
+
+This method has the advantage that it is unnecessary to keep track of the values that have been tried, but the disadvantage that one may try the same one twice, but this is not very important if there are several solutions. The systematic method has the disadvantage that there may be an enormous block without any solutions in the region which has to be investigated first, Now the learning process may be regarded as a search for a form of behaviour which will satisfy the teacher (or some other criterion). Since there is probably a very large number of satisfactory solutions the random method seems to be better than the systematic. It should be noticed that it is used in the analogous process of evolution.
+
+But there the systematic method is not possible. How could one keep track of the different genetical combinations that had been tried, so as to avoid trying them again?
+
+We may hope that machines will eventually compete with men in all purely intellectual fields. But which are the best ones to start with? Even this is a difficult decision. Many people think that a very abstract activity, like the playing of chess, would be best. It can also be maintained that it is best to provide the machine with the best sense organs that money can buy, and then teach it to understand and speak English. This process could follow the normal teaching of a child. Things would be pointed out and named, etc.
+
+Again I do not know what the right answer is, but I think both approaches should be tried.
+
+We can only see a short distance ahead, but we can see plenty there that needs to be done.
+
+
+
+
+

examples/HFblog-An Introduction to Q-Learning Part 1.txt

@@ -0,0 +1,290 @@
+---
+created: 2022-05-23T01:23:41 (UTC +02:00)
+tags: []
+source: https://huggingface.co/blog/deep-rl-q-part1
+author: ThomasSimonini
+            Thomas Simonini
+---
+
+# An Introduction to Q-Learning Part 1
+
+> ## Excerpt
+> We’re on a journey to advance and democratize artificial intelligence through open source and open science.
+
+---
+Back to blog
+
+## Unit 2, part 1 of the Deep Reinforcement Learning Class with Hugging Face 🤗
+
+## _This article is part of the Deep Reinforcement Learning Class. A free course from beginner to expert. Check the syllabus here._
+
+In the first chapter of this class, we learned about Reinforcement Learning (RL), the RL process, and the different methods to solve an RL problem. We also trained our first lander agent to **land correctly on the Moon 🌕 and uploaded it to the Hugging Face Hub.**
+
+So today, we're going to **dive deeper into one of the Reinforcement Learning methods: value-based methods** and study our first RL algorithm: **Q-Learning.**
+
+We'll also **implement our first RL agent from scratch**: a Q-Learning agent and will train it in two environments:
+
+1.  Frozen-Lake-v1 (non-slippery version): where our agent will need to **go from the starting state (S) to the goal state (G)** by walking only on frozen tiles (F) and avoiding holes (H).
+2.  An autonomous taxi will need **to learn to navigate** a city to **transport its passengers from point A to point B.**
+
+This unit is divided into 2 parts:
+
+In the first part, we'll **learn about the value-based methods and the difference between Monte Carlo and Temporal Difference Learning.**
+
+And in the second part, **we'll study our first RL algorithm: Q-Learning, and implement our first RL Agent.**
+
+This unit is fundamental **if you want to be able to work on Deep Q-Learning** (unit 3): the first Deep RL algorithm that was able to play Atari games and **beat the human level on some of them** (breakout, space invaders…).
+
+So let's get started!
+
+-   What is RL? A short recap
+-   The two types of value-based methods
+    -   The State-Value function
+    -   The Action-Value function
+-   The Bellman Equation: simplify our value estimation
+-   Monte Carlo vs Temporal Difference Learning
+    -   Monte Carlo: learning at the end of the episode
+    -   Temporal Difference Learning: learning at each step
+
+## **What is RL? A short recap**
+
+In RL, we build an agent that can **make smart decisions**. For instance, an agent that **learns to play a video game.** Or a trading agent that **learns to maximize its benefits** by making smart decisions on **what stocks to buy and when to sell.**
+
+But, to make intelligent decisions, our agent will learn from the environment by **interacting with it through trial and error** and receiving rewards (positive or negative) **as unique feedback.**
+
+Its goal **is to maximize its expected cumulative reward** (because of the reward hypothesis).
+
+**The agent's decision-making process is called the policy π:** given a state, a policy will output an action or a probability distribution over actions. That is, given an observation of the environment, a policy will provide an action (or multiple probabilities for each action) that the agent should take.
+
+**Our goal is to find an optimal policy π**\*, aka., a policy that leads to the best expected cumulative reward.
+
+And to find this optimal policy (hence solving the RL problem), there **are two main types of RL methods**:
+
+-   _Policy-based methods_: **Train the policy directly** to learn which action to take given a state.
+-   _Value-based methods_: **Train a value function** to learn **which state is more valuable** and use this value function **to take the action that leads to it.**
+
+And in this chapter, **we'll dive deeper into the Value-based methods.**
+
+## **The two types of value-based methods**
+
+In value-based methods, **we learn a value function** that **maps a state to the expected value of being at that state.**
+
+The value of a state is the **expected discounted return** the agent can get if it **starts at that state and then acts according to our policy.**
+
+If you forgot what discounting is, you can read this section.
+
+> But what means acting according to our policy? We don't have a policy in value-based methods since we train a value function and not a policy?
+
+Remember that the goal of an **RL agent is to have an optimal policy π.**
+
+To find it, we learned that there are two different methods:
+
+-   _Policy-based methods:_ **Directly train the policy** to select what action to take given a state (or a probability distribution over actions at that state). In this case, we **don't have a value function.**
+
+The policy takes a state as input and outputs what action to take at that state (deterministic policy).
+
+And consequently, **we don't define by hand the behavior of our policy; it's the training that will define it.**
+
+-   _Value-based methods:_ **Indirectly, by training a value function** that outputs the value of a state or a state-action pair. Given this value function, our policy **will take action.**
+
+But, because we didn't train our policy, **we need to specify its behavior.** For instance, if we want a policy that, given the value function, will take actions that always lead to the biggest reward, **we'll create a Greedy Policy.**
+
+Given a state, our action-value function (that we train) outputs the value of each action at that state, then our greedy policy (that we defined) selects the action with the biggest state-action pair value.
+
+Consequently, whatever method you use to solve your problem, **you will have a policy**, but in the case of value-based methods you don't train it, your policy **is just a simple function that you specify** (for instance greedy policy) and this policy **uses the values given by the value-function to select its actions.**
+
+So the difference is:
+
+-   In policy-based, **the optimal policy is found by training the policy directly.**
+-   In value-based, **finding an optimal value function leads to having an optimal policy.**
+
+In fact, most of the time, in value-based methods, you'll use **an Epsilon-Greedy Policy** that handles the exploration/exploitation trade-off; we'll talk about it when we talk about Q-Learning in the second part of this unit.
+
+So, we have two types of value-based functions:
+
+### **The State-Value function**
+
+We write the state value function under a policy π like this:
+
+For each state, the state-value function outputs the expected return if the agent **starts at that state,** and then follow the policy forever after (for all future timesteps if you prefer).
+
+If we take the state with value -7: it's the expected return starting at that state and taking actions according to our policy (greedy policy), so right, right, right, down, down, right, right.
+
+### **The Action-Value function**
+
+In the Action-value function, for each state and action pair, the action-value function **outputs the expected return** if the agent starts in that state and takes action, and then follows the policy forever after.
+
+The value of taking action an in state s under a policy π is:
+
+We see that the difference is:
+
+-   In state-value function, we calculate **the value of a state (St).**
+-   In action-value function, we calculate **the value of the state-action pair (St, At) hence the value of taking that action at that state.**
+
+Note: We didn't fill all the state-action pairs for the example of Action-value function
+
+In either case, whatever value function we choose (state-value or action-value function), **the value is the expected return.**
+
+However, the problem is that it implies that **to calculate EACH value of a state or a state-action pair, we need to sum all the rewards an agent can get if it starts at that state.**
+
+This can be a tedious process, and that's **where the Bellman equation comes to help us.**
+
+## **The Bellman Equation: simplify our value estimation**
+
+The Bellman equation **simplifies our state value or state-action value calculation.**
+
+With what we learned from now, we know that if we calculate the V(St) (value of a state), we need to calculate the return starting at that state and then follow the policy forever after. **(Our policy that we defined in the following example is a Greedy Policy, and for simplification, we don't discount the reward).**
+
+So to calculate V(St), we need to make the sum of the expected rewards. Hence:
+
+To calculate the value of State 1: the sum of rewards \*\*if the agent started in that state\*\* and then followed the \*\*greedy policy (taking actions that leads to the best states values) for all the time steps.\*\*
+
+Then, to calculate the V(St+1), we need to calculate the return starting at that state St+1.
+
+To calculate the value of State 2: the sum of rewards \*\*if the agent started in that state,\*\* and then followed the \*\*policy for all the time steps.\*\*
+
+So you see, that's a pretty tedious process if you need to do it for each state value or state-action value.
+
+Instead of calculating the expected return for each state or each state-action pair, **we can use the Bellman equation.**
+
+The Bellman equation is a recursive equation that works like this: instead of starting for each state from the beginning and calculating the return, we can consider the value of any state as:
+
+**The immediate reward (Rt+1) + the discounted value of the state that follows (gamma \* V(St+1)).**
+
+For simplification here we don’t discount so gamma = 1.
+
+If we go back to our example, the value of State 1= expected cumulative return if we start at that state.
+
+To calculate the value of State 1: the sum of rewards **if the agent started in that state 1** and then followed the **policy for all the time steps.**
+
+Which is equivalent to V(St) = Immediate reward (Rt+1) + Discounted value of the next state (Gamma \* V(St+1))
+
+For simplification, here we don't discount, so gamma = 1.
+
+-   The value of V(St+1) = Immediate reward (Rt+2) + Discounted value of the St+2 (Gamma \* V(St+2)).
+-   And so on.
+
+To recap, the idea of the Bellman equation is that instead of calculating each value as the sum of the expected return, **which is a long process.** This is equivalent **to the sum of immediate reward + the discounted value of the state that follows.**
+
+## **Monte Carlo vs Temporal Difference Learning**
+
+The last thing we need to talk about before diving into Q-Learning is the two ways of learning.
+
+Remember that an RL agent **learns by interacting with its environment.** The idea is that **using the experience taken**, given the reward it gets, will **update its value or policy.**
+
+Monte Carlo and Temporal Difference Learning are two different **strategies on how to train our value function or our policy function.** Both of them **use experience to solve the RL problem.**
+
+On one hand, Monte Carlo uses **an entire episode of experience before learning.** On the other hand, Temporal Difference uses **only a step (St, At, Rt+1, St+1) to learn.**
+
+We'll explain both of them **using a value-based method example.**
+
+### **Monte Carlo: learning at the end of the episode**
+
+Monte Carlo waits until the end of the episode, calculates Gt (return) and uses it as **a target for updating V(St).**
+
+So it requires a **complete entire episode of interaction before updating our value function.**
+
+If we take an example:
+
+-   We always start the episode **at the same starting point.**
+    
+-   **The agent takes actions using the policy**. For instance, using an Epsilon Greedy Strategy, a policy that alternates between exploration (random actions) and exploitation.
+    
+-   We get **the reward and the next state.**
+    
+-   We terminate the episode if the cat eats the mouse or if the mouse moves > 10 steps.
+    
+-   At the end of the episode, **we have a list of State, Actions, Rewards, and Next States**
+    
+-   **The agent will sum the total rewards Gt** (to see how well it did).
+    
+-   It will then **update V(st) based on the formula**
+    
+
+-   Then **start a new game with this new knowledge**
+
+By running more and more episodes, **the agent will learn to play better and better.**
+
+For instance, if we train a state-value function using Monte Carlo:
+
+-   We just started to train our Value function, **so it returns 0 value for each state**
+-   Our learning rate (lr) is 0.1 and our discount rate is 1 (= no discount)
+-   Our mouse **explores the environment and takes random actions**
+
+-   The mouse made more than 10 steps, so the episode ends .
+
+-   We have a list of state, action, rewards, next\_state, **we need to calculate the return Gt**
+-   $$G\_t = R\_{t+1} + R\_{t+2} + R\_{t+3} ...$$
+-   Gt = Rt+1 + Rt+2 + Rt+3… (for simplicity we don’t discount the rewards).
+-   Gt = 1 + 0 + 0 + 0+ 0 + 0 + 1 + 1+ 0 + 0
+-   Gt= 3
+-   We can now update V(S0):
+
+-   New V(S0) = V(S0) + lr \* \[Gt — V(S0)\]
+-   New V(S0) = 0 + 0.1 \* \[3 –0\]
+-   The new V(S0) = 0.3
+
+### **Temporal Difference Learning: learning at each step**
+
+-   **Temporal difference, on the other hand, waits for only one interaction (one step) St+1**
+-   to form a TD target and update V(St) using Rt+1 and gamma \* V(St+1).
+
+The idea with **TD is to update the V(St) at each step.**
+
+But because we didn't play during an entire episode, we don't have Gt (expected return). Instead, **we estimate Gt by adding Rt+1 and the discounted value of the next state.**
+
+We speak about **bootstrap because TD bases its update part on an existing estimate V(St+1) and not a complete sample Gt.**
+
+This method is called TD(0) or **one-step TD (update the value function after any individual step).**
+
+If we take the same example,
+
+-   We just started to train our Value function, so it returns 0 value for each state.
+-   Our learning rate (lr) is 0.1, and our discount rate is 1 (no discount).
+-   Our mouse explore the environment and take a random action: **going to the left**
+-   It gets a reward Rt+1 = 1 since **it eats a piece of cheese**
+
+We can now update V(S0):
+
+New V(S0) = V(S0) + lr \* \[R1 + gamma \* V(S1) — V(S0)\]
+
+New V(S0) = 0 + 0.1 \* \[1 + 0.99 \* 0–0\]
+
+The new V(S0) = 0.1
+
+So we just updated our value function for State 0.
+
+Now we **continue to interact with this environment with our updated value function.**
+
+If we summarize:
+
+-   With Monte Carlo, we update the value function from a complete episode, and so we **use the actual accurate discounted return of this episode.**
+-   With TD learning, we update the value function from a step, so we replace Gt that we don't have with **an estimated return called TD target.**
+
+So now, before diving on Q-Learning, let's summarise what we just learned:
+
+We have two types of value-based functions:
+
+-   State-Value function: outputs the expected return if **the agent starts at a given state and acts accordingly to the policy forever after.**
+-   Action-Value function: outputs the expected return if **the agent starts in a given state, takes a given action at that state** and then acts accordingly to the policy forever after.
+-   In value-based methods, **we define the policy by hand** because we don't train it, we train a value function. The idea is that if we have an optimal value function, we **will have an optimal policy.**
+
+There are two types of methods to learn a policy or a value function:
+
+-   With _the Monte Carlo method_, we update the value function from a complete episode, and so we **use the actual accurate discounted return of this episode.**
+-   With _the TD Learning method,_ we update the value function from a step, so we replace Gt that we don't have with **an estimated return called TD target.**
+
+---
+
+So that’s all for today. Congrats on finishing this first part of the chapter! There was a lot of information.
+
+**That’s normal if you still feel confused with all these elements**. This was the same for me and for all people who studied RL.
+
+**Take time to really grasp the material before continuing**. In the second part (that we will publish this Friday 📆), we’ll study our first RL algorithm: Q-Learning, and implement our first RL Agent in two environments:
+
+1.  Frozen-Lake-v1 (non-slippery version): where our agent will need to **go from the starting state (S) to the goal state (G)** by walking only on frozen tiles (F) and avoiding holes (H).
+2.  An autonomous taxi will need **to learn to navigate** a city to **transport its passengers from point A to point B.**
+
+And don't forget to share with your friends who want to learn 🤗 !
+
+### Keep learning, stay awesome,

examples/HFblog-Introducing Decision Transformers.txt

@@ -0,0 +1,236 @@
+---
+created: 2022-05-23T01:23:57 (UTC +02:00)
+tags: []
+source: https://huggingface.co/blog/decision-transformers
+author: 
+---
+
+# Introducing Decision Transformers on Hugging Face 🤗
+
+> ## Excerpt
+> We’re on a journey to advance and democratize artificial intelligence through open source and open science.
+
+---
+Back to blog
+
+At Hugging Face, we are contributing to the ecosystem for Deep Reinforcement Learning researchers and enthusiasts. Recently, we have integrated Deep RL frameworks such as Stable-Baselines3.
+
+And today we are happy to announce that we integrated the Decision Transformer, an Offline Reinforcement Learning method, into the 🤗 transformers library and the Hugging Face Hub. We have some exciting plans for improving accessibility in the field of Deep RL and we are looking forward to sharing them with you over the coming weeks and months.
+
+-   What is Offline Reinforcement Learning?
+-   Introducing Decision Transformers
+-   Using the Decision Transformer in 🤗 Transformers
+-   Conclusion
+-   What's next?
+-   References
+
+## What is Offline Reinforcement Learning?
+
+Deep Reinforcement Learning (RL) is a framework to build decision-making agents. These agents aim to learn optimal behavior (policy) by interacting with the environment through trial and error and receiving rewards as unique feedback.
+
+The agent’s goal is to maximize **its cumulative reward, called return.** Because RL is based on the reward hypothesis: **all goals can be described as the maximization of the expected cumulative reward.**
+
+Deep Reinforcement Learning agents **learn with batches of experience.** The question is, how do they collect it?:
+
+_A comparison between Reinforcement Learning in an Online and Offline setting, figure taken from this post_
+
+In online reinforcement learning, **the agent gathers data directly**: it collects a batch of experience by interacting with the environment. Then, it uses this experience immediately (or via some replay buffer) to learn from it (update its policy).
+
+But this implies that either you train your agent directly in the real world or have a simulator. If you don’t have one, you need to build it, which can be very complex (how to reflect the complex reality of the real world in an environment?), expensive, and insecure since if the simulator has flaws, the agent will exploit them if they provide a competitive advantage.
+
+On the other hand, in offline reinforcement learning, the agent only uses data collected from other agents or human demonstrations. **It does not interact with the environment**.
+
+The process is as follows:
+
+1.  Create a dataset using one or more policies and/or human interactions.
+2.  Run offline RL on this dataset to learn a policy
+
+This method has one drawback: the counterfactual queries problem. What do we do if our agent decides to do something for which we don’t have the data? For instance, turning right on an intersection but we don’t have this trajectory.
+
+There’s already exists some solutions on this topic, but if you want to know more about offline reinforcement learning you can watch this video
+
+## Introducing Decision Transformers
+
+The Decision Transformer model was introduced by “Decision Transformer: Reinforcement Learning via Sequence Modeling” by Chen L. et al. It abstracts Reinforcement Learning as a **conditional-sequence modeling problem**.
+
+The main idea is that instead of training a policy using RL methods, such as fitting a value function, that will tell us what action to take to maximize the return (cumulative reward), we use a sequence modeling algorithm (Transformer) that, given a desired return, past states, and actions, will generate future actions to achieve this desired return. It’s an autoregressive model conditioned on the desired return, past states, and actions to generate future actions that achieve the desired return.
+
+This is a complete shift in the Reinforcement Learning paradigm since we use generative trajectory modeling (modeling the joint distribution of the sequence of states, actions, and rewards) to replace conventional RL algorithms. It means that in Decision Transformers, we don’t maximize the return but rather generate a series of future actions that achieve the desired return.
+
+The process goes this way:
+
+1.  We feed the last K timesteps into the Decision Transformer with 3 inputs:
+    -   Return-to-go
+    -   State
+    -   Action
+2.  The tokens are embedded either with a linear layer if the state is a vector or CNN encoder if it’s frames.
+3.  The inputs are processed by a GPT-2 model which predicts future actions via autoregressive modeling.
+
+ _Decision Transformer architecture. States, actions, and returns are fed into modality specific linear embeddings and a positional episodic timestep encoding is added. Tokens are fed into a GPT architecture which predicts actions autoregressively using a causal self-attention mask. Figure from \[1\]._
+
+## Using the Decision Transformer in 🤗 Transformers
+
+The Decision Transformer model is now available as part of the 🤗 transformers library. In addition, we share nine pre-trained model checkpoints for continuous control tasks in the Gym environment.
+
+_An “expert” Decision Transformers model, learned using offline RL in the Gym Walker2d environment._
+
+### Install the package
+
+```
+pip install git+https://github.com/huggingface/transformers
+```
+
+### Loading the model
+
+Using the Decision Transformer is relatively easy, but as it is an autoregressive model, some care has to be taken in order to prepare the model’s inputs at each time-step. We have prepared both a Python script and a Colab notebook that demonstrates how to use this model.
+
+Loading a pretrained Decision Transformer is simple in the 🤗 transformers library:
+
+```
+from transformers import DecisionTransformerModel
+
+model_name = "edbeeching/decision-transformer-gym-hopper-expert"
+model = DecisionTransformerModel.from_pretrained(model_name)
+```
+
+### Creating the environment
+
+We provide pretrained checkpoints for the Gym Hopper, Walker2D and Halfcheetah. Checkpoints for Atari environments will soon be available.
+
+```
+import gym
+env = gym.make("Hopper-v3")
+state_dim = env.observation_space.shape[0] # state size
+act_dim = env.action_space.shape[0] # action size
+```
+
+### Autoregressive prediction function
+
+The model performs an autoregressive prediction; that is to say that predictions made at the current time-step **t** are sequentially conditioned on the outputs from previous time-steps. This function is quite meaty, so we will aim to explain it in the comments.
+
+```
+# Function that gets an action from the model using autoregressive prediction 
+# with a window of the previous 20 timesteps.
+def get_action(model, states, actions, rewards, returns_to_go, timesteps):
+    # This implementation does not condition on past rewards
+    
+    states = states.reshape(1, -1, model.config.state_dim)
+    actions = actions.reshape(1, -1, model.config.act_dim)
+    returns_to_go = returns_to_go.reshape(1, -1, 1)
+    timesteps = timesteps.reshape(1, -1)
+    
+    # The prediction is conditioned on up to 20 previous time-steps
+    states = states[:, -model.config.max_length :]
+    actions = actions[:, -model.config.max_length :]
+    returns_to_go = returns_to_go[:, -model.config.max_length :]
+    timesteps = timesteps[:, -model.config.max_length :]
+    
+    # pad all tokens to sequence length, this is required if we process batches
+    padding = model.config.max_length - states.shape[1]
+    attention_mask = torch.cat([torch.zeros(padding), torch.ones(states.shape[1])])
+    attention_mask = attention_mask.to(dtype=torch.long).reshape(1, -1)
+    states = torch.cat([torch.zeros((1, padding, state_dim)), states], dim=1).float()
+    actions = torch.cat([torch.zeros((1, padding, act_dim)), actions], dim=1).float()
+    returns_to_go = torch.cat([torch.zeros((1, padding, 1)), returns_to_go], dim=1).float()
+    timesteps = torch.cat([torch.zeros((1, padding), dtype=torch.long), timesteps], dim=1)
+    
+    # perform the prediction
+    state_preds, action_preds, return_preds = model(
+            states=states,
+            actions=actions,
+            rewards=rewards,
+            returns_to_go=returns_to_go,
+            timesteps=timesteps,
+            attention_mask=attention_mask,
+            return_dict=False,)
+    return action_preds[0, -1]
+```
+
+### Evaluating the model
+
+In order to evaluate the model, we need some additional information; the mean and standard deviation of the states that were used during training. Fortunately, these are available for each of the checkpoint’s model card on the Hugging Face Hub!
+
+We also need a target return for the model. This is the power of Offline Reinforcement Learning: we can use the target return to control the performance of the policy. This could be really powerful in a multiplayer setting, where we would like to adjust the performance of an opponent bot to be at a suitable difficulty for the player. The authors show a great plot of this in their paper!
+
+ _Sampled (evaluation) returns accumulated by Decision Transformer when conditioned on the specified target (desired) returns. Top: Atari. Bottom: D4RL medium-replay datasets. Figure from \[1\]._
+
+```
+TARGET_RETURN = 3.6 # This was normalized during training
+MAX_EPISODE_LENGTH = 1000 
+
+state_mean = np.array(
+    [1.3490015,  -0.11208222, -0.5506444,  -0.13188992, -0.00378754,  2.6071432,
+     0.02322114, -0.01626922, -0.06840388, -0.05183131,  0.04272673,])
+
+state_std = np.array(
+    [0.15980862, 0.0446214,  0.14307782, 0.17629202, 0.5912333,  0.5899924,
+         1.5405099,  0.8152689,  2.0173461,  2.4107876,  5.8440027,])
+
+state_mean = torch.from_numpy(state_mean)
+state_std = torch.from_numpy(state_std)
+
+state = env.reset()
+target_return = torch.tensor(TARGET_RETURN).float().reshape(1, 1)
+states = torch.from_numpy(state).reshape(1, state_dim).float()
+actions = torch.zeros((0, act_dim)).float()
+rewards = torch.zeros(0).float()
+timesteps = torch.tensor(0).reshape(1, 1).long()
+
+# take steps in the environment
+for t in range(max_ep_len):
+    # add zeros for actions as input for the current time-step
+    actions = torch.cat([actions, torch.zeros((1, act_dim))], dim=0)
+    rewards = torch.cat([rewards, torch.zeros(1)])
+
+    # predicting the action to take
+    action = get_action(model,
+                        (states - state_mean) / state_std,
+                        actions,
+                        rewards,
+                        target_return,
+                        timesteps)
+    actions[-1] = action
+    action = action.detach().numpy()
+
+    # interact with the environment based on this action
+    state, reward, done, _ = env.step(action)
+    
+    cur_state = torch.from_numpy(state).reshape(1, state_dim)
+    states = torch.cat([states, cur_state], dim=0)
+    rewards[-1] = reward
+    
+    pred_return = target_return[0, -1] - (reward / scale)
+    target_return = torch.cat([target_return, pred_return.reshape(1, 1)], dim=1)
+    timesteps = torch.cat([timesteps, torch.ones((1, 1)).long() * (t + 1)], dim=1)
+    
+    if done:
+        break
+```
+
+You will find a more detailed example, with the creation of videos of the agent in our Colab notebook.
+
+## Conclusion
+
+In addition to Decision Transformers, we want to support more use cases and tools from the Deep Reinforcement Learning community. Therefore, it would be great to hear your feedback on the Decision Transformer model, and more generally anything we can build with you that would be useful for RL. Feel free to **reach out to us**.
+
+## What’s next?
+
+In the coming weeks and months, we plan on supporting other tools from the ecosystem:
+
+-   Integrating **RL-baselines3-zoo**
+-   Uploading **RL-trained-agents models** into the Hub: a big collection of pre-trained Reinforcement Learning agents using stable-baselines3
+-   Integrating other Deep Reinforcement Learning libraries
+-   Implementing Convolutional Decision Transformers For Atari
+-   And more to come 🥳
+
+The best way to keep in touch is to **join our discord server** to exchange with us and with the community.
+
+## References
+
+\[1\] Chen, Lili, et al. "Decision transformer: Reinforcement learning via sequence modeling." _Advances in neural information processing systems_ 34 (2021).
+
+\[2\] Agarwal, Rishabh, Dale Schuurmans, and Mohammad Norouzi. "An optimistic perspective on offline reinforcement learning." _International Conference on Machine Learning_. PMLR, 2020.
+
+### Acknowledgements
+
+We would like to thank the paper’s first authors, Kevin Lu and Lili Chen, for their constructive conversations.

examples/HFblog-Introducing Hugging Face for Education.txt

@@ -0,0 +1,76 @@
+---
+created: 2022-05-23T01:23:51 (UTC +02:00)
+tags: []
+source: https://huggingface.co/blog/education
+author: Violette
+            Violette Lepercq
+---
+
+# Introducing Hugging Face for Education 🤗
+
+> ## Excerpt
+> We’re on a journey to advance and democratize artificial intelligence through open source and open science.
+
+---
+Back to blog
+
+Given that machine learning will make up the overwhelming majority of software development and that non-technical people will be exposed to AI systems more and more, one of the main challenges of AI is adapting and enhancing employee skills. It is also becoming necessary to support teaching staff in proactively taking AI's ethical and critical issues into account.
+
+As an open-source company democratizing machine learning, Hugging Face believes it is essential to educate people from all backgrounds worldwide.
+
+We launched the ML demo.cratization tour in March 2022, where experts from Hugging Face taught hands-on classes on Building Machine Learning Collaboratively to more than 1000 students from 16 countries. Our new goal: **to teach machine learning to 5 million people by the end of 2023**.
+
+_This blog post provides a high-level description of how we will reach our goals around education._
+
+## 🤗 **Education for All**
+
+🗣️ Our goal is to make the potential and limitations of machine learning understandable to everyone. We believe that doing so will help evolve the field in a direction where the application of these technologies will lead to net benefits for society as a whole.
+
+Some examples of our existing efforts:
+
+-   we describe in a very accessible way different uses of ML models (summarization, text generation, object detection…),
+-   we allow everyone to try out models directly in their browser through widgets in the model pages, hence lowering the need for technical skills to do so (example),
+-   we document and warn about harmful biases identified in systems (like GPT-2).
+-   we provide tools to create open-source ML apps that allow anyone to understand the potential of ML in one click.
+
+## 🤗 **Education for Beginners**
+
+🗣️ We want to lower the barrier to becoming a machine learning engineer by providing online courses, hands-on workshops, and other innovative techniques.
+
+-   We provide a free course about natural language processing (NLP) and more domains (soon) using free tools and libraries from the Hugging Face ecosystem. It’s completely free and without ads. The ultimate goal of this course is to learn how to apply Transformers to (almost) any machine learning problem!
+-   We provide a free course about Deep Reinforcement Learning. In this course, you can study Deep Reinforcement Learning in theory and practice, learn to use famous Deep RL libraries, train agents in unique environments, publish your trained agents in one line of code to the Hugging Face Hub, and more!
+-   We provide a free course on how to build interactive demos for your machine learning models. The ultimate goal of this course is to allow ML developers to easily present their work to a wide audience including non-technical teams or customers, researchers to more easily reproduce machine learning models and behavior, end users to more easily identify and debug failure points of models, and more!
+-   Experts at Hugging Face wrote a book on Transformers and their applications to a wide range of NLP tasks.
+
+Apart from those efforts, many team members are involved in other educational efforts such as:
+
+-   Participating in meetups, conferences and workshops.
+-   Creating podcasts, YouTube videos, and blog posts.
+-   Organizing events in which free GPUs are provided for anyone to be able to train and share models and create demos for them.
+
+## 🤗 **Education for Instructors**
+
+🗣️ We want to empower educators with tools and offer collaborative spaces where students can build machine learning using open-source technologies and state-of-the-art machine learning models.
+
+-   We provide to educators free infrastructure and resources to quickly introduce real-world applications of ML to theirs students and make learning more fun and interesting. By creating a classroom for free from the hub, instructors can turn their classes into collaborative environments where students can learn and build ML-powered applications using free open-source technologies and state-of-the-art models. 
+    
+-   We’ve assembled a free toolkit translated to 8 languages that instructors of machine learning or Data Science can use to easily prepare labs, homework, or classes. The content is self-contained so that it can be easily incorporated into an existing curriculum. This content is free and uses well-known Open Source technologies (🤗 transformers, gradio, etc). Feel free to pick a tutorial and teach it!
+    
+    1️⃣ A Tour through the Hugging Face Hub
+    
+    2️⃣ Build and Host Machine Learning Demos with Gradio & Hugging Face
+    
+    3️⃣ Getting Started with Transformers
+    
+-   We're organizing a dedicated, free workshop (June 6) on how to teach our educational resources in your machine learning and data science classes. Do not hesitate to register.
+    
+-   We are currently doing a worldwide tour in collaboration with university instructors to teach more than 10000 students one of our core topics: How to build machine learning collaboratively? You can request someone on the Hugging Face team to run the session for your class via the ML demo.cratization tour initiative**.**
+    
+
+## 🤗 **Education Events & News**
+
+-   **05/13**\[NEWS\]: Are you studying machine learning? Do you want to be a part of our ML democratization efforts and show your campus community how to build ML models with Hugging Face? We want to support you in your journey! You have until June 13th to apply to 🤗 Student Application Program.
+-   **06/06**\[EVENT\]: How to Teach Open-Source Machine Learning Tools. Register
+-   **09/08**\[EVENT\]: ML Demo.cratization tour in Argentina at 2pm (GMT-3). Link coming soon
+
+🔥 We are currently working on more content in the course, and more! Stay tuned!

examples/LOTR-S-The Music of the Ainur.txt

@@ -0,0 +1,49 @@
+There was Eru, the One, who in Arda is called Ilúvatar; and he made first the Ainur, the Holy Ones, that were the offspring of his thought, and they were with him before aught else was made. And he spoke to them, propounding to them themes of music; and they sang before him, and he was glad. But for a long while they sang only each alone, or but few together, while the rest hearkened; for each comprehended only that part of me mind of Ilúvatar from which he came, and in the understanding of their brethren they grew but slowly. Yet ever as they listened they came to deeper understanding, and increased in unison and harmony.
+
+And it came to pass that Ilúvatar called together all the Ainur and declared to them a mighty theme, unfolding to them things greater and more wonderful than he had yet revealed; and the glory of its beginning and the splendour of its end amazed the Ainur, so that they bowed before Ilúvatar and were silent.
+
+Then Ilúvatar said to them: 'Of the theme that I have declared to you, I will now that ye make in harmony together a Great Music. And since I have kindled you with the Flame Imperishable, ye shall show forth your powers in adorning this theme, each with his own thoughts and devices, if he will. But I win sit and hearken, and be glad that through you great beauty has been wakened into song.'
+
+Then the voices of the Ainur, like unto harps and lutes, and pipes and trumpets, and viols and organs, and like unto countless choirs singing with words, began to fashion the theme of Ilúvatar to a great music; and a sound arose of endless interchanging melodies woven in harmony that passed beyond hearing into the depths and into the heights, and the places of the dwelling of Ilúvatar were filled to overflowing, and the music and the echo of the music went out into the Void, and it was not void. Never since have the Ainur made any music like to this music, though it has been said that a greater still shall be made before Ilúvatar by the choirs of the Ainur and the Children of Ilúvatar after the end of days. Then the themes of Ilúvatar shall be played aright, and take Being in the moment of their utterance, for all shall then understand fully his intent in their part, and each shall know the comprehension of each, and Ilúvatar shall give to their thoughts the secret fire, being well pleased.
+
+But now Ilúvatar sat and hearkened, and for a great while it seemed good to him, for in the music there were no flaws. But as the theme progressed, it came into the heart of Melkor to interweave matters of his own imagining that were not in accord with the theme of Ilúvatar, for he sought therein to increase the power and glory of the part assigned to himself. To Melkor among the Ainur had been given the greatest gifts of power and knowledge, and he had a share in all the gifts of his brethren. He had gone often alone into the void places seeking the Imperishable Flame; for desire grew hot within him to bring into Being things of his own, and it seemed to him that Ilúvatar took no thought for the Void, and he was impatient of its emptiness. Yet he found not the Fire, for it is with Ilúvatar. But being alone he had begun to conceive thoughts of his own unlike those of his brethren.
+
+Some of these thoughts he now wove into his music, and straightway discord arose about him, and many that sang nigh him grew despondent, and their thought was disturbed and their music faltered; but some began to attune their music to his rather than to the thought which they had at first. Then the discord of Melkor spread ever wider, and the melodies which had been heard before foundered in a sea of turbulent sound. But Ilúvatar sat and hearkened until it seemed that about his throne there was a raging storm, as of dark waters that made war one upon another in an endless wrath that would not be assuaged.
+
+Then Ilúvatar arose, and the Ainur perceived that he smiled; and he lifted up his left hand, and a new theme began amid the storm, like and yet unlike to the former theme, and it gathered power and had new beauty. But the discord of Melkor rose in uproar and contended with it, and again there was a war of sound more violent than before, until many of the Ainur were dismayed and sang no longer, and Melkor had the mastery. Then again Ilúvatar arose, and the Ainur perceived that his countenance was stern; and he lifted up his right hand, and behold! a third theme grew amid the confusion, and it was unlike the others. For it seemed at first soft and sweet, a mere rippling of gentle sounds in delicate melodies; but it could not be quenched, and it took to itself power and profundity. And it seemed at last that there were two musics progressing at one time before the seat of Ilúvatar, and they were utterly at variance. The one was deep and wide and beautiful, but slow and blended with an immeasurable sorrow, from which its beauty chiefly came. The other had now achieved a unity of its own; but it was loud, and vain, and endlessly repeated; and it had little harmony, but rather a clamorous unison as of many trumpets braying upon a few notes. And it essayed to drown the other music by the violence of its voice, but it seemed that its most triumphant notes were taken by the other and woven into its own solemn pattern.
+
+In the midst of this strife, whereat the halls of Ilúvatar shook and a tremor ran out into the silences yet unmoved, Ilúvatar arose a third time, and his face was terrible to behold. Then he raised up both his hands, and in one chord, deeper than the Abyss, higher than the Firmament, piercing as the light of the eye of Ilúvatar, the Music ceased.
+
+Then Ilúvatar spoke, and he said: 'Mighty are the Ainur, and mightiest among them is Melkor; but that he may know, and all the Ainur, that I am Ilúvatar, those things that ye have sung, I will show them forth, that ye may see what ye have done. And thou, Melkor, shalt see that no theme may be played that hath not its uttermost source in me, nor can any alter the music in my despite. For he that attempteth this shall prove but mine instrument in the devising of things more wonderful, which he himself hath not imagined.'
+
+Then the Ainur were afraid, and they did not yet comprehend the words that were said to them; and Melkor was filled with shame, of which came secret anger. But Ilúvatar arose in splendour, and he went forth from the fair regions that he had made for the Ainur; and the Ainur followed him.
+
+But when they were come into the Void, Ilúvatar said to them: 'Behold your Music!' And he showed to them a vision, giving to them sight where before was only hearing; arid they saw a new World made visible before them, and it was globed amid the Void, and it was sustained therein, but was not of it. And as they looked and wondered this World began to unfold its history, and it seemed to them that it lived and grew. And when the Ainur had gazed for a while and were silent, Ilúvatar said again: 'Behold your Music! This is your minstrelsy; and each of you shall find contained herein, amid the design that I set before you, all those things which it may seem that he himself devised or added. And thou, Melkor, wilt discover all the secret thoughts of thy mind, and wilt perceive that they are but a part of the whole and tributary to its glory.'
+
+And many other things Ilúvatar spoke to the Ainur at that time, and because of their memory of his words, and the knowledge that each has of the music that he himself made, the Ainur know much of what was, and is, and is to come, and few things are unseen by them. Yet some things there are that they cannot see, neither alone nor taking counsel together; for to none but himself has Ilúvatar revealed all that he has in store, and in every age there come forth things that are new and have no foretelling, for they do not proceed from the past. And so it was that as this vision of the World was played before them, the Ainur saw that it contained things which they had not thought. And they saw with amazement the coming of the Children of Ilúvatar, and the habitation that was prepared for them; and they perceived that they themselves in the labour of their music had been busy with the preparation of this dwelling, and yet knew not that it had any purpose beyond its own beauty. For the Children of Ilúvatar were conceived by him alone; and they came with the third theme, and were not in the theme which Ilúvatar propounded at the beginning, and none of the Ainur had part in their making. Therefore when they beheld them, the more did they love them, being things other than themselves, strange and free, wherein they saw the mind of Ilúvatar reflected anew, and learned yet a little more of his wisdom, which otherwise had been hidden even from the Ainur.
+
+Now the Children of Ilúvatar are Elves and Men, the Firstborn and the Followers. And amid all the splendours of the World, its vast halls and spaces, and its wheeling fires, Ilúvatar chose a place for their habitation in the Deeps of Time and in the midst of the innumerable stars. And this habitation might seem a little thing to those who consider only the majesty of the Ainur, and not their terrible sharpness; as who should take the whole field of Arda for the foundation of a pillar and so raise it until the cone of its summit were more bitter than a needle; or who consider only the immeasurable vastness of the World, which still the Ainur are shaping, and not the minute precision to which they shape all things therein. But when the Ainur had beheld this habitation in a vision and had seen the Children of Ilúvatar arise therein, then many of the most mighty among them bent all their thought and their desire towards that place. And of these Melkor was the chief, even as he was in the beginning the greatest of the Ainur who took part in the Music. And he feigned, even to himself at first, that he desired to go thither and order all things for the good of the Children of Ilúvatar, controlling the turmoils of the heat and the cold that had come to pass through him. But he desired rather to subdue to his will both Elves and Men, envying the gifts with which Ilúvatar promised to endow them; and he wished himself to have subject and servants, and to be called Lord, and to be a master over other wills.
+
+But the other Ainur looked upon this habitation set within the vast spaces of the World, which the Elves call Arda, the Earth; and their hearts rejoiced in light, and their eyes beholding many colours were filled with gladness; but because of the roaring of the sea they felt a great unquiet. And they observed the winds and the air, and the matters of which Arda was made, of iron and stone and silver and gold and many substances: but of all these water they most greatly praised. And it is said by the Eldar that in water there lives yet the echo of the Music of the Ainur more than in any substance else that is in this Earth; and many of the Children of Ilúvatar hearken still unsated to the voices of the Sea, and yet know not for what they listen.
+
+Now to water had that Ainu whom the Elves can Ulmo turned his thought, and of all most deeply was he instructed by Ilúvatar in music. But of the airs and winds Manwë most had pondered, who is the noblest of the Ainur. Of the fabric of Earth had Aulë thought, to whom Ilúvatar had given skin and knowledge scarce less than to Melkor; but the delight and pride of Aulë is in the deed of making, and in the thing made, and neither in possession nor in his own mastery; wherefore he gives and hoards not, and is free from care, passing ever on to some new work.
+
+And Ilúvatar spoke to Ulmo, and said: 'Seest thou not how here in this little realm in the Deeps of Time Melkor hath made war upon thy province? He hath bethought him of bitter cold immoderate, and yet hath not destroyed the beauty of thy fountains, nor of my clear pools. Behold the snow, and the cunning work of frost! Melkor hath devised heats and fire without restraint, and hath not dried up thy desire nor utterly quelled the music of the sea. Behold rather the height and glory of the clouds, and the everchanging mists; and listen to the fall of rain upon the Earth! And in these clouds thou art drawn nearer to Manwë, thy friend, whom thou lovest.'
+
+Then Ulmo answered: 'Truly, Water is become now fairer than my heart imagined, neither had my secret thought conceived the snowflake, nor in all my music was contained the falling of the rain. I will seek Manwë, that he and I may make melodies for ever to my delight!' And Manwë and Ulmo have from the beginning been allied, and in all things have served most faithfully the purpose of Ilúvatar.
+
+But even as Ulmo spoke, and while the Ainur were yet gazing upon this vision, it was taken away and hidden from their sight; and it seemed to them that in that moment they perceived a new thing, Darkness, which they had not known before except in thought. But they had become enamoured of the beauty of the vision and engrossed in the unfolding of the World which came there to being, and their minds were filled with it; for the history was incomplete and the circles of time not full-wrought when the vision was taken away. And some have said that the vision ceased ere the fulfilment of the Dominion of Men and the fading of the Firstborn; wherefore, though the Music is over all, the Valar have not seen as with sight the Later Ages or the ending of the World.
+
+Then there was unrest among the Ainur; but Ilúvatar called to them, and said: 'I know the desire of your minds that what ye have seen should verily be, not only in your thought, but even as ye yourselves are, and yet other. Therefore I say: Eä! Let these things Be! And I will send forth into the Void the Flame Imperishable, and it shall be at the heart of the World, and the World shall Be; and those of you that will may go down into it. And suddenly the Ainur saw afar off a light, as it were a cloud with a living heart of flame; and they knew that this was no vision only, but that Ilúvatar had made a new thing: Eä, the World that Is.
+
+Thus it came to pass that of the Ainur some abode still with Ilúvatar beyond the confines of the World; but others, and among them many of the greatest and most fair, took the leave of Ilúvatar and descended into it. But this condition Ilúvatar made, or it is the necessity of their love, that their power should thenceforward be contained and bounded in the World, to be within it for ever, until it is complete, so that they are its life and it is theirs. And therefore they are named the Valar, the Powers of the World.
+
+But when the Valar entered into Eä they were at first astounded and at a loss, for it was as if naught was yet made which they had seen in vision, and all was but on point to begin and yet unshaped, and it was dark. For the Great Music had been but the growth and flowering of thought in the Tuneless Halls, and the Vision only a foreshowing; but now they had entered in at the beginning of Time, and the Valar perceived that the World had been but foreshadowed and foresung, and they must achieve it. So began their great labours in wastes unmeasured and unexplored, and in ages uncounted and forgotten, until in the Deeps of Time and in the midst of the vast halls of Eä there came to be that hour and that place where was made the habitation of the Children of Ilúvatar. And in this work the chief part was taken by Manwë and Aulë and Ulmo; but Melkor too was there from the first, and he meddled in all that was done, turning it if he might to his own desires and purposes; and he kindled great fires. When therefore Earth was yet young and full of flame Melkor coveted it, and he said to the other Valar: 'This shall be my own kingdom; and I name it unto myself!'
+
+But Manwë was the brother of Melkor in the mind of Ilúvatar, and he was the chief instrument of the second theme that Ilúvatar had raised up against the discord of Melkor; and he called unto himself many spirits both greater and less, and they came down into the fields of Arda and aided Manwë, lest Melkor should hinder the fulfilment of their labour for ever, and Earth should wither ere it flowered. And Manwë said unto Melkor: 'This kingdom thou shalt not take for thine own, wrongfully, for many others have laboured here do less than thou.' And there was strife between Melkor and the other Valar; and for that time Melkor withdrew and departed to other regions and did there what he would; but he did not put the desire of the Kingdom of Arda from his heart.
+
+Now the Valar took to themselves shape and hue; and because they were drawn into the World by love of the Children of Ilúvatar, for whom they hoped, they took shape after that manner which they had beheld in the Vision of Ilúvatar, save only in majesty and splendour. Moreover their shape comes of their knowledge of the visible World, rather than of the World itself; and they need it not, save only as we use raiment, and yet we may be naked and suffer no loss of our being. Therefore the Valar may walk, if they will, unclad, and then even the Eldar cannot clearly perceive them, though they be present. But when they desire to clothe themselves the Valar take upon them forms some as of male and some as of female; for that difference of temper they had even from their beginning, and it is but bodied forth in the choice of each, not made by the choice, even as with us male and female may be shown by the raiment but is not made thereby. But the shapes wherein the Great Ones array themselves are not at all times like to the shapes of the kings and queens of the Children of Ilúvatar; for at times they may clothe themselves in their own thought, made visible in forms of majesty and dread.
+
+And the Valar drew unto them many companions, some less, some well nigh as great as themselves, and they laboured together in the ordering of the Earth and the curbing of its tumults. Then Melkor saw what was done, and that the Valar walked on Earth as powers visible, clad in the raiment of the World, and were lovely and glorious to see, and blissful, and that the Earth was becoming as a garden for their delight, for its turmoils were subdued. His envy grew then the greater within him; and he also took visible form, but because of his mood and the malice that burned in him that form was dark and terrible. And he descended upon Arda in power and majesty greater than any other of the Valar, as a mountain that wades in the sea and has its head above the clouds and is clad in ice and crowned with smoke and fire; and the light of the eyes of Melkor was like a flame that withers with heat and pierces with a deadly cold.
+
+Thus began the first battle of the Valar with Melkor for the dominion of Arda; and of those tumults the Elves know but little. For what has here been declared is come from the Valar themselves, with whom the Eldalië spoke in the land of Valinor, and by whom they were instructed; but little would the Valar ever tell of the wars before the coming of the Elves. Yet it is told among the Eldar that the Valar endeavoured ever, in despite of Melkor, to rule the Earth and to prepare it for the coming of the Firstborn; and they built lands and Melkor destroyed them; valleys they delved and Melkor raised them up; mountains they carved and Melkor threw them down; seas they hollowed and Melkor spilled them; and naught might have peace or come to lasting growth, for as surely as the Valar began a labour so would Melkor undo it or corrupt it. And yet their labour was not all in vain; and though nowhere and in no work was their will and purpose wholly fulfilled, and all things were in hue and shape other than the Valar had at first intended, slowly nonetheless the Earth was fashioned and made firm. And thus was the habitation of the Children of Ilúvatar established at the last in the Deeps of Time and amidst the innumerable stars.

examples/LOTR-S-VALAQUENTA.txt

@@ -0,0 +1,61 @@
+Account of the Valar and Maiar according to the lore of the Eldar
+In the beginning Eru, the One, who in the Elvish tongue is named Ilúvatar, made the Ainur of his thought; and they made a great Music before him. In this Music the World was begun; for Ilúvatar made visible the song of the Ainur, and they beheld it as a light in the darkness. And many among them became enamoured of its beauty, and of its history which they saw beginning and unfolding as in a vision. Therefore Ilúvatar gave to their vision Being, and set it amid the Void, and the Secret Fire was sent to burn at the heart of the World; and it was called Eä.
+
+Then those of the Ainur who desired it arose and entered into the World at the beginning of Time; and it was their task to achieve it, and by their labours to fulfil the vision which they had seen. Long they laboured in the regions of Eä, which are vast beyond the thought of Elves and Men, until in the time appointed was made Arda, the Kingdom of Earth. Then they put on the raiment of Earth and descended into it, and dwelt therein.
+
+Of the Valar
+The Great among these spirits the Elves name the Valar, the Powers of Arda, and Men have often called them gods. The Lords of the Valar are seven; and the Valier, the Queens of the Valar, are seven also. These were their names in the Elvish tongue as it was spoken in Valinor, though they have other names in the speech of the Elves in Middle-earth, and their names among Men are manifold. The names of the Lords in due order are: Manwë, Ulmo, Aulë, Oromë, Mandos, Lórien, and Tulkas; and the names of the Queens are: Varda, Yavanna, Nienna, Estë, Vairë, Vána, and Nessa. Melkor is counted no longer among the Valar, and his name is not spoken upon Earth.
+
+Manwë and Melkor were brethren in the thought of Ilúvatar. The mightiest of those Ainur who came into the World was in his beginning Melkor; but Manwë is dearest to Ilúvatar and understands most clearly his purposes. He was appointed to be, in the fullness of time, the first of all Kings: lord of the realm of Arda and ruler of all that dwell therein. In Arda his delight is in the winds and the clouds, and in all the regions of the air, from the heights to the depths, from the utmost borders of the Veil of Arda to the breezes that blow in the grass. Súlimo he is surnamed, Lord of the Breath of Arda. All swift birds, strong of wing, he loves, and they come and go at his bidding.
+
+With Manwë dwells Varda, Lady of the Stars, who knows all the regions of Eä. Too great is her beauty to be declared in the words of Men or of Elves; for the light of Ilúvatar lives still in her face. In light is her power and her joy. Out of the deeps of Eä she came to the aid of Manwë; for Melkor she knew from before the making of the Music and rejected him, and he hated her, and feared her more than all others whom Eru made. Manwë and Varda are seldom parted, and they remain in Valinor. Their halls are above the everlasting snow, upon Oiolossë, the uttermost tower of Taniquetil, tallest of all the mountains upon Earth. When Manwë there ascends his throne and looks forth, if Varda is beside him, he sees further than all other eyes, through mist, and through darkness, and over the leagues of the sea. And if Manwë is with her, Varda hears more clearly than all other ears the sound of voices that cry from east to west, from the hills and the valleys, and from the dark places that Melkor has made upon Earth. Of all the Great Ones who dwell in this world the Elves hold Varda most in reverence and love. Elbereth they name her, and they call upon her name out of the shadows of Middle-earth, and uplift it in song at the rising of the stars.
+
+Ulmo is the Lord of Waters. He is alone. He dwells nowhere long, but moves as he will in all the deep waters about the Earth or under the Earth. He is next in might to Manwë, and before Valinor was made he was closest to him in friendship; but thereafter he went seldom to the councils of the Valar, unless great matters were in debate. For he kept all Arda in thought, and he has no need of any resting-place. Moreover he does not love to walk upon land, and will seldom clothe himself in a body after the manner of his peers. If the Children of Eru beheld him they were filled with a great dread; for the arising of the King of the Sea was terrible, as a mounting wave that strides to the land, with dark helm foam-crested and raiment of mail shimmering from silver down into shadows of green. The trumpets of Manwë are loud, but Ulmo's voice is deep as the deeps of the ocean which he only has seen.
+
+Nonetheless Ulmo loves both Elves and Men, and never abandoned them, not even when they lay under the wrath of the Valar. At times he win come unseen to the shores of Middle-earth, or pass far inland up firths of the sea, and there make music upon his great horns, the Ulumúri, that are wrought of white shell; and those to whom that music comes hear it ever after in their hearts, and longing for the sea never leaves them again. But mostly Ulmo speaks to those who dwell in Middle-earth with voices that are heard only as the music of water. For all seas, lakes, rivers, fountains and springs are in his government; so that the Elves say that the spirit of Ulmo runs in all the veins of the world. Thus news comes to Ulmo, even in the deeps, of all the needs and griefs of Arda, which otherwise would be hidden from Manwë.
+
+Aulë has might little less than Ulmo. His lordship is over all the substances of which Arda is made. In the beginning he wrought much in fellowship with Manwë and Ulmo; and the fashioning of all lands was his labour. He is a smith and a master of all crafts, and he delights in works of skill, however small, as much as in the mighty building of old. His are the gems that lie deep in the Earth and the gold that is fair in the hand, no less than the walls of the mountains and the basins of the sea. The Noldor learned most of him, and he was ever their friend. Melkor was jealous of him, for Aulë was most like himself in thought and in powers; and there was long strife between them, in which Melkor ever marred or undid the works of Aulë, and Aulë grew weary in repairing the tumults and disorders of Melkor. Both, also, desired to make things of their own that should be new and unthought of by others, and delighted in the praise of their skill. But Aulë remained faithful to Eru and submitted all that he did to his will; and he did not envy the works of others, but sought and gave counsel. Whereas Melkor spent his spirit in envy and hate, until at last he could make nothing save in mockery of the thought of others, and all their works he destroyed if he could.
+
+The spouse of Aulë is Yavanna, the Giver of Fruits. She is the lover of all things that grow in the earth, and all their countless forms she holds in her mind, from the trees like towers in forests long ago to the moss upon stones or the small and secret things in the mould. In reverence Yavanna is next to Varda among the Queens of the Valar. In the form of a woman she is tall, and robed in green; but at times she takes other shapes. Some there are who have seen her standing like a tree under heaven, crowned with the Sun; and from all its branches there spilled a golden dew upon the barren earth, and it grew green with corn; but the roots of the tree were in the waters of Ulmo, and the winds of Manwë spoke in its leaves. Kementári, Queen of the Earth, she is surnamed in the Eldarin tongue.
+
+The Fëanturi, masters of spirits, are brethren, and they are called most often Mandos and Lórien. Yet these are rightly the names of the places of their dwelling, and their true names are Námo and Irmo.
+
+Námo the elder dwells in Mandos, which is westward in Valinor. He is the keeper of the Houses of the Dead, and the summoner of the spirits of the slain. He forgets nothing; and he knows all things that shall be, save only those that lie still in the freedom of Ilúvatar. He is the Doomsman of the Valar; but he pronounces his dooms and his Judgements only at the bidding of Manwë. Vairë the Weaver is his spouse, who weaves all things that have ever been in Time into her storied webs, and the halls of Mandos that ever widen as the ages pass are clothed with them.
+
+Irmo the younger is the master of visions and dreams. In Lórien are his gardens in the land of the Valar, and they are the fairest of all places in the world, filled with many spirits. Estë the gentle, healer of hurts and of weariness, is his spouse. Grey is her raiment; and rest is her gift. She walks not by day, but sleeps upon an island in the tree-shadowed lake of Lórellin. From the fountains of Irmo and Estë all those who dwell in Valinor draw refreshment; and often the Valar come themselves to Lórien and there find repose and easing of the burden of Arda.
+
+Mightier than Estë is Nienna, sister of the Fëanturi; she dwells alone. She is acquainted with grief, and mourns for every wound that Arda has suffered in the marring of Melkor. So great was her sorrow, as the Music unfolded, that her song turned to lamentation long before its end, and the sound of mourning was woven into the themes of the World before it began. But she does not weep for herself; and those who hearken to her learn pity, and endurance in hope. Her halls are west of West, upon the borders of the world; and she comes seldom to the city of Valimar where all is glad. She goes rather to the halls of Mandos, which are near to her own; and all those who wait in Mandos cry to her, for she brings strength to the spirit and turns sorrow to wisdom. The windows of her house look outward from the walls of the world.
+
+Greatest in strength and deeds of prowess is Tulkas, who is surnamed Astaldo, the Valiant. He came last to Arda, to aid the Valar in the first battles with Melkor. He delights in wrestling and in contests of strength; and he rides no steed, for he can outrun all things that go on feet, and he is tireless. His hair and beard are golden, and his flesh ruddy; his weapons are his hands. He has little heed for either the past or the future, and is of no avail as a counsellor, but is a hardy friend. His spouse is Nessa, the sister of Oromë, and she also is lithe and fleetfooted. Deer she loves, and they follow her train whenever she goes in the wild; but she can outrun them, swift as an arrow with the wind in her hair. In dancing she delights, and she dances in Valimar on lawns of never-fading green.
+
+Oromë is a mighty lord. If he is less strong than Tulkas, he is more dreadful in anger; whereas Tulkas laughs ever, in sport or in war, and even in the face of Melkor he laughed in battles before the Elves were born. Oromë loved the lands of Middle-earth, and he left them unwillingly and came last to Valinor; and often of old he passed back east over the mountains and returned with his host to the hills and the plains. He is a hunter of monsters and fell beasts, and he delights in horses and in hounds; and all trees he loves, for which reason he is called Aldaron, and by the Sindar Tauron, the Lord of Forests. Nahar is the name of his horse, white in the sun, and shining silver at night. The Valaróma is the name of his great horn, the sound of which is like the upgoing of the Sun in scarlet, or the sheer lightning cleaving the clouds. Above all the horns of his host it was heard in the woods that Yavanna brought forth in Valinor; for there Oromë would train his folk and his beasts for the pursuit of the evil creatures of Melkor. The spouse of Oromë is Vána, the Ever-young; she is the younger sister of Yavanna. All flowers spring as she passes and open if she glances upon them; and all birds sing at her coming.
+
+These are the names of the Valar and the Valier, and here is told in brief their likenesses, such as the Eldar beheld them in Aman. But fair and noble as were the forms in which they were manifest to the Children of Ilúvatar, they were but a veil upon their beauty and their power. And if little is here said of all that the Eldar once knew, that is as nothing compared with their true being, which goes back into regions and ages far beyond our thought. Among them Nine were of chief power and reverence; but one is removed from their number, and Eight remain, the Aratar, the High Ones of Arda: Manwë and Varda, Ulmo, Yavanna and Aulë, Mandos, Nienna, and Oromë. Though Manwë is their King and holds their allegiance under Eru, in majesty they are peers, surpassing beyond compare all others, whether of the Valar and the Maiar, or of any other order that Ilúvatar has sent into Eä.
+
+Of the Maiar
+With the Valar came other spirits whose being also began before the World, of the same order as the Valar but of less degree. These are the Maiar, the people of the Valar, and their servants and helpers. Their number is not known to the Elves, and few have names in any of the tongues of the Children of Ilúvatar; for though it is otherwise in Aman, in Middle-earth the Maiar have seldom appeared in form visible to Elves and Men.
+
+Chief among the Maiar of Valinor whose names are remembered in the histories of the Elder Days are Ilmarë, the handmaid of Varda, and Eönwë, the banner-bearer and herald of Manwë, whose might in arms is surpassed by none in Arda. But of all the Maiar Ossë and Uinen are best known to the Children of Ilúvatar.
+
+Ossë is a vassal of Ulmo, and he is master of the seas that wash the shores of Middle-earth. He does not go in the deeps, but loves the coasts and the isles, and rejoices in the winds of Manwë; for in storm he delights, and laughs amid the roaring of the waves. His spouse is Uinen, the Lady of the Seas, whose hair lies spread through all waters under sky. All creatures she loves that live in the salt streams, and all weeds that grow there; to her mariners cry, for she can lay calm upon the waves, restraining the wildness of Ossë. The Númenóreans lived long in her protection, and held her in reverence equal to the Valar.
+
+Melkor hated the Sea, for he could not subdue it. It is said that in the making of Arda he endeavoured to draw Ossë to his allegiance, promising to him all the realm and power of Ulmo, if he would serve him. So it was that long ago there arose great tumults in the sea that wrought ruin to the lands. But Uinen, at the prayer of Aulë, restrained Ossë and brought him before Ulmo; and he was pardoned and returned to his allegiance, to which he has remained faithful. For the most part; for the delight in violence has never wholly departed from him, and at times he will rage in his wilfulness without any command from Ulmo his lord. Therefore those who dwell by the sea or go up in ships may love him, but they do not trust him.
+
+Melian was the name of a Maia who served both Vána and Estë; she dwelt long in Lórien, tending the trees that flower in the gardens of Irmo, ere she came to Middle-earth. Nightingales sang about her wherever she went.
+
+Wisest of the Maiar was Olórin. He too dwelt in Lórien, but his ways took him often to the house of Nienna, and of her he learned pity and patience.
+
+Of Melian much is told in the Quenta Silmarillion. But of Olórin that tale does not speak; for though he loved the Elves, he walked among them unseen, or in form as one of them, and they did not know whence came the fair visions or the promptings of wisdom that he put into their hearts. In later days he was the friend of all the Children of Ilúvatar, and took pity on their sorrows; and those who listened to him awoke from despair and put away the imaginations of darkness.
+
+Of the Enemies
+Last of all is set the name of Melkor, He who arises in Might. But that name he has forfeited; and the Noldor, who among the Elves suffered most from his malice, will not utter it, and they name him Morgoth, the Dark Enemy of the World. Great might was given to him by Ilúvatar, and he was coeval with Manwë. In the powers and knowledge of all the other Valar he had part, but he turned them to evil purposes, and squandered his strength in violence and tyranny. For he coveted Arda and all that was in it, desiring the kingship of Manwë and dominion over the realms of his peers.
+
+From splendour he fell through arrogance to contempt for all things save himself, a spirit wasteful and pitiless. Understanding he turned to subtlety in perverting to his own will all that he would use, until he became a liar without shame. He began with the desire of Light, but when he could not possess it for himself alone, he descended through fire and wrath into a great burning, down into Darkness. And darkness he used most in his evil works upon Arda, and filled it with fear for all living things.
+
+Yet so great was the power of his uprising that in ages forgotten he contended with Manwë and all the Valar, and through long years in Arda held dominion over most of the lands of the Earth. But he was not alone. For of the Maiar many were drawn to his splendour in the days of his greatness, and remained in that allegiance down into his darkness; and others he corrupted afterwards to his service with lies and treacherous gifts. Dreadful among these spirits were the Valaraukar, the scourges of fire that in Middle-earth were called the Balrogs, demons of terror.
+
+Among those of his servants that have names the greatest was that spirit whom the Eldar called Sauron, or Gorthaur the Cruel. In his beginning he was of the Maiar of Aulë, and he remained mighty in the lore of that people. In all the deeds of Melkor the Morgoth upon Arda, in his vast works and in the deceits of his cunning, Sauron had a part, and was only less evil than his master in that for long he served another and not himself. But in after years he rose like a shadow of Morgoth and a ghost of his malice, and walked behind him on the same ruinous path down into the Void.
+
+HERE ENDS THE VALAQUENTA
+
+ 

pdf2text.py

@@ -0,0 +1,346 @@
+# -*- coding: utf-8 -*-
+"""
+pdf2text.py - convert pdf files to text files using OCR
+"""
+import logging
+import os
+import re
+import shutil
+import time
+from datetime import date
+from os.path import basename, dirname, join
+from pathlib import Path
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s %(levelname)s %(message)s",
+    datefmt="%m/%d/%Y %I:%M:%S",
+)
+
+
+os.environ["USE_TORCH"] = "1"
+
+from cleantext import clean
+from doctr.io import DocumentFile
+from doctr.models import ocr_predictor
+from spellchecker import SpellChecker
+
+
+def simple_rename(filepath, target_ext=".txt"):
+    """simple_rename - get a new str to rename a file"""
+    _fp = Path(filepath)
+    basename = _fp.stem
+    return f"OCR_{basename}_{target_ext}"
+
+
+def rm_local_text_files(name_contains="RESULT_"):
+    """
+    rm_local_text_files - remove local text files
+    """
+    files = [
+        f
+        for f in Path.cwd().iterdir()
+        if f.is_file() and f.suffix == ".txt" and name_contains in f.name
+    ]
+    logging.info(f"removing {len(files)} text files")
+    for f in files:
+        os.remove(f)
+    logging.info("done")
+
+
+def corr(
+    s: str,
+    add_space_when_numerics=False,
+    exceptions=["e.g.", "i.e.", "etc.", "cf.", "vs.", "p."],
+) -> str:
+    """corrects spacing in a string
+
+    Args:
+        s (str): the string to correct
+        add_space_when_numerics (bool, optional): [add a space when a period is between two numbers, example 5.73]. Defaults to False.
+        exceptions (list, optional): [do not change these substrings]. Defaults to ['e.g.', 'i.e.', 'etc.', 'cf.', 'vs.', 'p.'].
+
+    Returns:
+        str: the corrected string
+    """
+    if add_space_when_numerics:
+        s = re.sub(r"(\d)\.(\d)", r"\1. \2", s)
+
+    s = re.sub(r"\s+", " ", s)
+    s = re.sub(r'\s([?.!"](?:\s|$))', r"\1", s)
+
+    # fix space before apostrophe
+    s = re.sub(r"\s\'", r"'", s)
+    # fix space after apostrophe
+    s = re.sub(r"'\s", r"'", s)
+    # fix space before comma
+    s = re.sub(r"\s,", r",", s)
+
+    for e in exceptions:
+        expected_sub = re.sub(r"\s", "", e)
+        s = s.replace(expected_sub, e)
+
+    return s
+
+
+def fix_punct_spaces(string: str) -> str:
+    """
+    fix_punct_spaces - fix spaces around punctuation
+
+    :param str string: input string
+    :return str: string with spaces fixed
+    """
+
+    fix_spaces = re.compile(r"\s*([?!.,]+(?:\s+[?!.,]+)*)\s*")
+    string = fix_spaces.sub(lambda x: "{} ".format(x.group(1).replace(" ", "")), string)
+    string = string.replace(" ' ", "'")
+    string = string.replace(' " ', '"')
+    return string.strip()
+
+
+def clean_OCR(ugly_text: str) -> str:
+    """
+    clean_OCR - clean up the OCR text
+
+    :param str ugly_text: input text to be cleaned
+    :return str: cleaned text
+    """
+    # Remove all the newlines.
+    cleaned_text = ugly_text.replace("\n", " ")
+    # Remove all the tabs.
+    cleaned_text = cleaned_text.replace("\t", " ")
+    # Remove all the double spaces.
+    cleaned_text = cleaned_text.replace("  ", " ")
+    # Remove all the spaces at the beginning of the text.
+    cleaned_text = cleaned_text.lstrip()
+    # remove all instances of "- " and " - "
+    cleaned_text = cleaned_text.replace("- ", "")
+    cleaned_text = cleaned_text.replace(" -", "")
+    return fix_punct_spaces(cleaned_text)
+
+
+def move2completed(
+    from_dir, filename, new_folder: str = "completed", verbose: bool = False
+):
+    """
+    move2completed - move a file to a new folder
+    """
+    old_filepath = join(from_dir, filename)
+
+    new_filedirectory = join(from_dir, new_folder)
+
+    if not os.path.isdir(new_filedirectory):
+        os.mkdir(new_filedirectory)
+        if verbose:
+            print("created new directory for files at: \n", new_filedirectory)
+    new_filepath = join(new_filedirectory, filename)
+
+    try:
+        shutil.move(old_filepath, new_filepath)
+        logging.info("successfully moved the file {} to */completed.".format(filename))
+    except:
+        logging.info(
+            "ERROR! unable to move file to \n{}. Please investigate".format(
+                new_filepath
+            )
+        )
+
+
+custom_replace_list = {
+    "t0": "to",
+    "'$": "'s",
+    ",,": ", ",
+    "_ ": " ",
+    " '": "'",
+}
+
+replace_corr_exceptions = {
+    "i. e.": "i.e.",
+    "e. g.": "e.g.",
+    "e. g": "e.g.",
+    " ,": ",",
+}
+
+
+spell = SpellChecker()
+
+
+def check_word_spelling(word: str) -> bool:
+    """
+    check_word_spelling - check the spelling of a word
+
+    Args:
+        word (str): word to check
+
+    Returns:
+        bool: True if word is spelled correctly, False if not
+    """
+
+    misspelled = spell.unknown([word])
+
+    return len(misspelled) == 0
+
+
+def eval_and_replace(text: str, match_token: str = "- ") -> str:
+    """
+    eval_and_replace  - conditionally replace all instances of a substring in a string based on whether the eliminated substring results in a valid word
+
+    Args:
+        text (str): text to evaluate
+        match_token (str, optional): token to replace. Defaults to "- ".
+
+    Returns:
+        str:  text with replaced tokens
+    """
+
+    if match_token not in text:
+        return text
+    else:
+        while True:
+            full_before_text = text.split(match_token, maxsplit=1)[0]
+            before_text = [
+                char for char in full_before_text.split()[-1] if char.isalpha()
+            ]
+            before_text = "".join(before_text)
+            full_after_text = text.split(match_token, maxsplit=1)[-1]
+            after_text = [char for char in full_after_text.split()[0] if char.isalpha()]
+            after_text = "".join(after_text)
+            full_text = before_text + after_text
+            if check_word_spelling(full_text):
+                text = full_before_text + full_after_text
+            else:
+                text = full_before_text + " " + full_after_text
+            if match_token not in text:
+                break
+        return text
+
+
+def cleantxt_ocr(ugly_text, lower=False, lang: str = "en") -> str:
+    """
+    cleantxt_ocr - clean text from OCR
+
+        https://pypi.org/project/clean-text/
+    Args:
+        ugly_text (str): text to clean
+        lower (bool, optional): lowercase text. Defaults to False.
+        lang (str, optional): language of text. Defaults to "en".
+
+    Returns:
+        str: cleaned text
+    """
+
+    cleaned_text = clean(
+        ugly_text,
+        fix_unicode=True,  # fix various unicode errors
+        to_ascii=True,  # transliterate to closest ASCII representation
+        lower=lower,  # lowercase text
+        no_line_breaks=True,  # fully strip line breaks as opposed to only normalizing them
+        no_urls=True,  # replace all URLs with a special token
+        no_emails=True,  # replace all email addresses with a special token
+        no_phone_numbers=True,  # replace all phone numbers with a special token
+        no_numbers=False,  # replace all numbers with a special token
+        no_digits=False,  # replace all digits with a special token
+        no_currency_symbols=False,  # replace all currency symbols with a special token
+        no_punct=False,  # remove punctuations
+        replace_with_punct="",  # instead of removing punctuations you may replace them
+        replace_with_url="this url",
+        replace_with_email="this email",
+        replace_with_phone_number="this phone number",
+        lang=lang,  # set to 'de' for German special handling
+    )
+
+    return cleaned_text
+
+
+def format_ocr_out(OCR_data):
+    """format OCR output to text"""
+    if isinstance(OCR_data, list):
+        text = " ".join(OCR_data)
+    else:
+        text = str(OCR_data)
+    _clean = cleantxt_ocr(text)
+    return corr(_clean)
+
+
+def postprocess(text: str) -> str:
+    """to be used after recombining the lines"""
+
+    proc = corr(cleantxt_ocr(text))
+
+    for k, v in custom_replace_list.items():
+        proc = proc.replace(str(k), str(v))
+
+    proc = corr(proc)
+
+    for k, v in replace_corr_exceptions.items():
+        proc = proc.replace(str(k), str(v))
+
+    return eval_and_replace(proc)
+
+
+def result2text(result, as_text=False) -> str or list:
+    """Convert OCR result to text"""
+
+    full_doc = []
+    for i, page in enumerate(result.pages, start=1):
+        text = ""
+        for block in page.blocks:
+            text += "\n\t"
+            for line in block.lines:
+                for word in line.words:
+                    # print(dir(word))
+                    text += word.value + " "
+        full_doc.append(text)
+
+    return "\n".join(full_doc) if as_text else full_doc
+
+
+def convert_PDF_to_Text(
+    PDF_file,
+    ocr_model=None,
+    max_pages: int = 20,
+) -> str:
+    """
+    convert_PDF_to_Text - convert a PDF file to text
+
+    :param str PDF_file: path to PDF file
+    :param ocr_model: model to use for OCR, defaults to None (uses the default model)
+    :param int max_pages: maximum number of pages to process, defaults to 20
+    :return str: text from PDF
+    """
+    st = time.perf_counter()
+    PDF_file = Path(PDF_file)
+    ocr_model = ocr_predictor(pretrained=True) if ocr_model is None else ocr_model
+    logging.info(f"starting OCR on {PDF_file.name}")
+    doc = DocumentFile.from_pdf(PDF_file)
+    truncated = False
+    if len(doc) > max_pages:
+        logging.warning(
+            f"PDF has {len(doc)} pages, which is more than {max_pages}.. truncating"
+        )
+        doc = doc[:max_pages]
+        truncated = True
+
+    # Analyze
+    logging.info(f"running OCR on {len(doc)} pages")
+    result = ocr_model(doc)
+    raw_text = result2text(result)
+    proc_text = [format_ocr_out(r) for r in raw_text]
+    fin_text = [postprocess(t) for t in proc_text]
+
+    ocr_results = "\n\n".join(fin_text)
+
+    fn_rt = time.perf_counter() - st
+
+    logging.info("OCR complete")
+
+    results_dict = {
+        "num_pages": len(doc),
+        "runtime": round(fn_rt, 2),
+        "date": str(date.today()),
+        "converted_text": ocr_results,
+        "truncated": truncated,
+        "length": len(ocr_results),
+    }
+
+    return results_dict

requirements.txt

@@ -0,0 +1,11 @@
+accelerate
+clean-text[gpl]
+gradio
+natsort
+nltk
+pyspellchecker
+python-doctr[torch]
+rapidfuzz==2.13.7
+torch
+tqdm
+transformers

summarize.py

@@ -0,0 +1,172 @@
+"""
+summarize - a module for summarizing text using a model from the Hugging Face model hub
+"""
+import logging
+import pprint as pp
+
+logging.basicConfig(level=logging.INFO, format="%(asctime)s - %(message)s")
+
+import torch
+from tqdm.auto import tqdm
+from transformers import AutoModelForSeq2SeqLM, AutoTokenizer
+
+from utils import validate_pytorch2
+
+
+def load_model_and_tokenizer(model_name: str) -> tuple:
+    """
+    load_model_and_tokenizer - load a model and tokenizer from a model name/ID on the hub
+
+    :param str model_name: the model name/ID on the hub
+    :return tuple: a tuple containing the model and tokenizer
+    """
+    device = "cuda" if torch.cuda.is_available() else "cpu"
+    model = AutoModelForSeq2SeqLM.from_pretrained(
+        model_name,
+    ).to(device)
+    model = model.eval()
+
+    tokenizer = AutoTokenizer.from_pretrained(model_name)
+
+    logging.info(f"Loaded model {model_name} to {device}")
+
+    if validate_pytorch2():
+        try:
+            logging.info("Compiling model with Torch 2.0")
+            model = torch.compile(model)
+        except Exception as e:
+            logging.warning(f"Could not compile model with Torch 2.0: {e}")
+    else:
+        logging.info("Torch 2.0 not detected, skipping compilation")
+
+    return model, tokenizer
+
+
+def summarize_and_score(
+    ids, mask, model, tokenizer, is_general_attention_model=True, **kwargs
+) -> tuple:
+    """
+    summarize_and_score - given a batch of ids and a mask, return a summary and a score for the summary
+
+    Args:
+        ids (): the batch of ids
+        mask (): the attention mask for the batch
+        model   (): the model to use for summarization
+        tokenizer (): the tokenizer to use for summarization
+        is_general_attention_model (bool, optional): whether the model is a general attention model. Defaults to True.
+        **kwargs: any additional arguments to pass to the model
+    Returns:
+        tuple (str, float): the summary,  the score for the summary
+    """
+
+    ids = ids[None, :]
+    mask = mask[None, :]
+
+    input_ids = ids.to("cuda") if torch.cuda.is_available() else ids
+    attention_mask = mask.to("cuda") if torch.cuda.is_available() else mask
+
+    global_attention_mask = torch.zeros_like(attention_mask)
+    # put global attention on <s> token
+    global_attention_mask[:, 0] = 1
+
+    if is_general_attention_model:
+        summary_pred_ids = model.generate(
+            input_ids,
+            attention_mask=attention_mask,
+            output_scores=True,
+            return_dict_in_generate=True,
+            **kwargs,
+        )
+    else:
+        summary_pred_ids = model.generate(
+            input_ids,
+            attention_mask=attention_mask,
+            global_attention_mask=global_attention_mask,
+            output_scores=True,
+            return_dict_in_generate=True,
+            **kwargs,
+        )
+    summary = tokenizer.batch_decode(
+        summary_pred_ids.sequences,
+        skip_special_tokens=True,
+        remove_invalid_values=True,
+    )
+    score = round(summary_pred_ids.sequences_scores.cpu().numpy()[0], 4)
+
+    return summary, score
+
+
+def summarize_via_tokenbatches(
+    input_text: str,
+    model,
+    tokenizer,
+    batch_length=2048,
+    batch_stride=16,
+    min_batch_length=512,
+    **kwargs,
+) -> list:
+    """
+    summarize_via_tokenbatches - summarize a long string via batches of tokens
+
+    Args:
+        input_text (str): the text to summarize
+        model (): the model to use for summarization
+        tokenizer (): the tokenizer to use for summarization
+        batch_length (int, optional): the length of each batch. Defaults to 2048.
+        batch_stride (int, optional): the stride of each batch. Defaults to 16. The stride is the number of tokens that overlap between batches.
+        min_batch_length (int, optional): the minimum length of each batch. Defaults to 512.
+
+        **kwargs: any additional arguments to pass to the model for inference
+    Returns:
+        list: a list of dictionaries containing the input tokens, the summary, and the summary score
+    """
+
+    logger = logging.getLogger(__name__)
+    # log all input parameters
+    if batch_length < min_batch_length:
+        logger.warning(
+            f"batch_length must be at least {min_batch_length}. Setting batch_length to {min_batch_length}"
+        )
+        batch_length = min_batch_length
+
+    logger.info(f"input parameters:\n{pp.pformat(kwargs)}")
+    logger.info(f"batch_length: {batch_length}, batch_stride: {batch_stride}")
+
+    encoded_input = tokenizer(
+        input_text,
+        padding="max_length",
+        truncation=True,
+        max_length=batch_length,
+        stride=batch_stride,
+        return_overflowing_tokens=True,
+        add_special_tokens=False,
+        return_tensors="pt",
+    )
+
+    in_id_arr, att_arr = encoded_input.input_ids, encoded_input.attention_mask
+    gen_summaries = []
+
+    pbar = tqdm(total=len(in_id_arr))
+
+    for _id, _mask in zip(in_id_arr, att_arr):
+        result, score = summarize_and_score(
+            ids=_id,
+            mask=_mask,
+            model=model,
+            tokenizer=tokenizer,
+            **kwargs,
+        )
+        score = round(float(score), 4)
+        _sum = {
+            "input_tokens": _id,
+            "summary": result,
+            "summary_score": score,
+        }
+        gen_summaries.append(_sum)
+        logger.debug(f"Score for batch: {score}. num chars: {len(repr(result))}")
+        logger.debug(f"Summary:\n\t{result}")
+        pbar.update()
+
+    pbar.close()
+
+    return gen_summaries

utils.py

@@ -0,0 +1,452 @@
+"""
+    utils.py - Utility functions for the project.
+"""
+import logging
+import os
+import re
+import string
+import subprocess
+from collections import defaultdict, deque
+from datetime import datetime, timedelta
+from itertools import combinations, islice
+from pathlib import Path
+from typing import List
+
+logging.basicConfig(
+    format="%(asctime)s - %(levelname)s - %(name)s - %(message)s",
+    level=logging.INFO,
+)
+
+import torch
+from natsort import natsorted
+from nltk.tokenize import WhitespaceTokenizer, sent_tokenize, word_tokenize
+from rapidfuzz import fuzz
+
+STOPWORDS = set(
+    "a about above after again all also am an and any are aren't as at back be because been before being below between both but by can't cannot could couldn't did didn't do does doesn't doing don't down during each few for from further had hadn't has hasn't have haven't having he'd he'll he's hence her here here's hers herself him himself his how how's however i'd i'll i'm i've if in into is isn't it's its itself just let's me more moreover most mustn't my myself new nor now of off on once only or other ought our ours ourselves out over own really same shan't she'd she'll she's should shouldn't so some such than that that's the their theirs them themselves then there there's therefore these they they'd they'll they're they've this those through thus to too under until up use used using very was wasn't we we'd we'll we're we've were weren't what what's when when's where where's which while who who's whom why why's with won't would wouldn't you'd you'll you're you've your yours yourself yourselves".split()
+)
+
+
+def contraction_aware_tokenize(text: str) -> List[str]:
+    """contraction_aware_tokenize - merges words containing apostrophes as one token."""
+
+    # Tokenize the text using the WhitespaceTokenizer
+    tokenizer = WhitespaceTokenizer()
+    tokens = tokenizer.tokenize(text)
+
+    merged_tokens = []
+    merged_token = ""
+
+    for token in tokens:
+        if re.search(r"\w+'\w+", token):
+            # Token contains an apostrophe, merge with previous token
+            merged_token += token
+        else:
+            # no apostrophe, add previous merged token (if any) and current
+            if merged_token:
+                merged_tokens.append(merged_token)
+                merged_token = ""
+            merged_tokens.append(token)
+
+    # Add the last merged token (if any)
+    if merged_token:
+        merged_tokens.append(merged_token)
+
+    return merged_tokens
+
+
+def remove_stopwords(
+    text: str, stopwords: List[str] = STOPWORDS, contraction_tokenize: bool = True
+) -> str:
+    """
+    remove_stopwords - Remove stopwords from text.
+
+    :param str text: input text
+    :param List[str] stopwords: list of stopwords, defaults to STOPWORDS
+    :param bool contraction_tokenize: use custom apostrophe tokenizer, defaults to True
+    :return str: text with stopwords removed
+    """
+    lines = text.split("\n")
+    filtered_lines = []
+
+    def fix_commas(text: str) -> str:
+        """fixes commas in text to have a space after them"""
+        spaced_text = text.replace(",", ", ")
+        return spaced_text.replace("  ", " ").strip()
+
+    for line in lines:
+        sentences = sent_tokenize(line)
+        filtered_sentences = []
+
+        for sentence in sentences:
+            # Add space around punctuations for the regex to work correctly, only if they are followed by a letter
+            sentence_with_spaces = re.sub(r"([.,!?])(\w)", r"\1 \2", sentence[:-1])
+
+            words = (
+                contraction_aware_tokenize(sentence_with_spaces)
+                if contraction_tokenize
+                else word_tokenize(sentence_with_spaces)
+            )
+
+            filtered_words = []
+            for word in words:
+                if word.lower() not in stopwords:
+                    filtered_words.append(word)
+
+            filtered_sentence = " ".join(filtered_words)
+            # Restore original spaces around punctuation marks
+            filtered_sentence = re.sub(r"([.,!?])\s*", r"\1", filtered_sentence)
+
+            filtered_sentences.append(filtered_sentence + sentence[-1])
+
+        filtered_line = " ".join(filtered_sentences)
+
+        # Replace multiple consecutive whitespaces with a single space
+        filtered_line = re.sub(r"\s+", " ", filtered_line)
+        filtered_line = fix_commas(filtered_line.strip())
+
+        filtered_lines.append(filtered_line)
+
+    filtered_text = "\n".join(filtered_lines)
+
+    return filtered_text
+
+
+def remove_stagnant_files(
+    freq: str = "hourly",
+    search_path: str = ".",
+    substring="DocSumm",
+    remove_suffix=".txt",
+):
+    """
+    remove_stagnant_files - Remove files that have not been modified in a certain amount of time.
+
+    :param str freq: frequency of file removal, defaults to "hourly"
+    :param str search_path: location to search for files, defaults to "."
+    :param str substring: substring to search for in file names, defaults to "DocSumm"
+    :param str remove_suffix: suffix of files to remove, defaults to ".txt"
+    :raises ValueError: if freq is not one of "hourly", "daily", or "weekly"
+    """
+    current_time = datetime.now()
+    search_path = Path(search_path)
+
+    if freq == "hourly":
+        time_threshold = current_time - timedelta(hours=1)
+    elif freq == "daily":
+        time_threshold = current_time - timedelta(days=1)
+    elif freq == "weekly":
+        time_threshold = current_time - timedelta(weeks=1)
+    else:
+        raise ValueError(
+            "Invalid frequency. Supported values are 'hourly', 'daily', and 'weekly'."
+        )
+
+    files_to_remove = []
+    potential_files = [
+        f for f in search_path.iterdir() if f.is_file() and f.suffix == remove_suffix
+    ]
+    logging.info(f"Found {len(potential_files)} files.")
+    for candidate in potential_files:
+        if (
+            candidate.is_file()
+            and substring in candidate.name
+            and candidate.stat().st_mtime < time_threshold.timestamp()
+        ):
+            files_to_remove.append(candidate)
+        logging.debug(f"File {candidate} last modified at {candidate.stat().st_mtime}")
+    logging.info(f"Removing {len(files_to_remove)} files.")
+    for file_path in files_to_remove:
+        file_path.unlink()
+    logging.debug(f"Removed files: {files_to_remove}")
+
+
+def compare_model_size(model_name: str, threshold: int = 500) -> bool:
+    """
+    compare_model_size - compare string representations of model size to a threshold
+
+    :param str model_name: the model name to compare
+    :param int threshold: the threshold to compare against in millions, defaults to 500
+    :return: True if the model size is greater than the threshold, False or None otherwise
+    """
+    pattern = r"(\d+)(M|G|k|b)?"  # param regex
+
+    matches = re.findall(pattern, model_name)
+    if not matches:
+        return None
+
+    # Extract the parameter count and unit
+    parameter_count, unit = matches[-1]
+    parameter_count = int(parameter_count)
+
+    # Convert to the standard form (M for million, G for billion, k for thousand)
+    if unit == "G" or unit == "b":
+        parameter_count *= 1000
+    elif unit == "M":
+        pass
+    elif unit == "k":
+        parameter_count /= 1000
+    else:
+        return None  # Unknown
+
+    return parameter_count > threshold
+
+
+def validate_pytorch2(torch_version: str = None) -> bool:
+    """
+    validate_pytorch2 - validate that the PyTorch version is 2.0 or greater
+
+    :param str torch_version: the PyTorch version to validate, defaults to None
+    :return: True if the PyTorch version is 2.0 or greater, False otherwise
+    """
+
+    torch_version = torch.__version__ if torch_version is None else torch_version
+
+    pattern = r"^2\.\d+(\.\d+)*"
+
+    return True if re.match(pattern, torch_version) else False
+
+
+def get_timestamp(detailed=False) -> str:
+    """
+    get_timestamp - get a timestamp for the current time
+    :param bool detailed: whether to include seconds and microseconds, defaults to False
+    :return: str, the timestamp
+    """
+    return (
+        datetime.now().strftime("%b%d%Y_%H%M%S%f")
+        if detailed
+        else datetime.now().strftime("%b%d%Y_%H")
+    )
+
+
+def truncate_word_count(text: str, max_words=1024) -> dict:
+    """
+    truncate_word_count - truncate a text to a maximum number of words
+    :param str text: the text to truncate
+    :param int max_words: the maximum number of words to keep, defaults to 1024
+    :return: dict, the processed text
+    """
+    words = contraction_aware_tokenize(str(text))
+    processed = {}
+    if len(words) > max_words:
+        processed["was_truncated"] = True
+        processed["processed_text"] = " ".join(words[:max_words])
+    else:
+        processed["was_truncated"] = False
+        processed["processed_text"] = text
+    return processed
+
+
+def load_examples(src, filetypes=[".txt", ".pdf"]):
+    """
+    load_examples - a helper function for the gradio module to load examples
+    :param str src: the path to the examples
+    """
+    src = Path(src)
+    src.mkdir(exist_ok=True)
+
+    pdf_url = (
+        "https://www.dropbox.com/s/y92xy7o5qb88yij/all_you_need_is_attention.pdf?dl=1"
+    )
+    subprocess.run(["wget", pdf_url, "-O", src / "all_you_need_is_attention.pdf"])
+    examples = [f for f in src.iterdir() if f.suffix in filetypes]
+    examples = natsorted(examples)
+    # load the examples into a list
+    text_examples = []
+    for example in examples:
+        with open(example, "r") as f:
+            text = f.read()
+            text_examples.append([text, "base", 2, 1024, 0.7, 3.5, 3])
+
+    return text_examples
+
+
+def load_example_filenames(example_path: str or Path):
+    """
+    load_example_filenames - a helper function for the gradio module to load examples
+    Returns:
+        dict, the examples (filename:full path)
+    """
+    example_path = Path(example_path)
+    # load the examples into a list
+    examples = {f.name: f for f in example_path.glob("*.txt")}
+    return examples
+
+
+def textlist2html(text_batches: List[str]) -> str:
+    """textlist2html - convert a list of text summaries into a single HTML string"""
+    # Step 1: Generate each summary batch as a string of HTML
+    formatted_batches = [
+        f"""
+        <div style="
+            margin-bottom: 20px;
+            font-size: 18px;
+            line-height: 1.5em;
+            color: #333;
+        ">
+            <h2 style="font-size: 22px; color: #555;">Batch {i}:</h2>
+            <p style="white-space: pre-line;">{s}</p>
+        </div>
+        """
+        for i, s in enumerate(text_batches, start=1)
+    ]
+
+    # Step 2: Join all the summary batches together into one string
+    joined_batches = "".join(formatted_batches)
+
+    # Step 3: Wrap the summary string in a larger div with background color, border, and padding
+    text_html_block = f"""
+    <div style="
+        border: 1px solid #ddd;
+        border-radius: 5px;
+        padding: 20px;
+    ">
+    {joined_batches}
+    </div>
+    """
+
+    return text_html_block
+
+
+def extract_batches(html_string: str, pattern=None, flags=None) -> list:
+    """
+    Extract batches of text from an HTML string.
+
+    Args:
+        html_string (str): The HTML string to extract batches from.
+        pattern (str, optional): The regular expression pattern to use. Defaults to a pattern that matches batches in the format provided.
+        flags (int, optional): The flags to use with the regular expression. Defaults to re.DOTALL.
+
+    Returns:
+        list: A list of dictionaries where each dictionary represents a batch and has 'title' and 'content' keys.
+    """
+    # Set default pattern if none provided
+    if pattern is None:
+        pattern = r'<h2 style="font-size: 22px; color: #555;">(.*?)</h2>\s*<p style="white-space: pre-line;">(.*?)</p>'
+
+    # Set default flags if none provided
+    if flags is None:
+        flags = re.DOTALL
+
+    try:
+        # Find all matches in the string
+        matches = re.findall(pattern, html_string, flags)
+
+        # Convert matches to a list of dictionaries
+        batches = [
+            {"title": title.strip(), "content": content.strip()}
+            for title, content in matches
+        ]
+
+        return batches
+    except re.error as e:
+        logging.error(f"An error occurred while trying to extract batches: {e}")
+        return []
+
+
+def extract_keywords(
+    text: str, num_keywords: int = 3, window_size: int = 5, kw_max_len: int = 20
+) -> List[str]:
+    """
+    Extracts keywords from a text using a simplified TextRank algorithm.
+
+    Args:
+        text: The text to extract keywords from.
+        num_keywords: The number of keywords to extract. Default: 3
+        window_size: The number of words considered for co-occurrence. Default: 5
+        kw_max_len: The maximum length of a keyword (truncate longer keywords to max). Default: 20
+    Returns:
+        A list of strings, where each string is a keyword extracted from the input text.
+    """
+    logger = logging.getLogger(__name__)
+    # Remove stopwords and tokenize the text into words
+    words = [
+        word
+        for word in re.findall(r"\b\w{3,}\b", text.lower())
+        if word not in STOPWORDS
+    ]
+
+    # Create a graph of word co-occurrences within a moving window of words
+    cooccur = defaultdict(lambda: defaultdict(int))
+    deque_words = deque(maxlen=window_size)
+    for word in words:
+        for w1, w2 in combinations(deque_words, 2):
+            cooccur[w1][w2] += 1
+            cooccur[w2][w1] += 1
+        deque_words.append(word)
+
+    # Assign scores to words using a simplified TextRank algorithm
+    scores = defaultdict(float)
+    for _ in range(10):
+        new_scores = defaultdict(float)
+        for word, co_words in cooccur.items():
+            new_scores[word] = 0.15 + 0.85 * sum(
+                cooccur[word][other] / sum(cooccur[other].values()) * scores[other]
+                for other in co_words
+            )
+        scores = new_scores
+
+    # Sort the words by score and return the top num_keywords keywords
+    keywords = sorted(scores, key=scores.get, reverse=True)[:num_keywords]
+    logger.debug(f"All keywords: {keywords}")
+    # Use fuzzy matching to remove similar keywords
+    final_keywords = []
+    for keyword in keywords:
+        if not any(fuzz.ratio(keyword, other) > 70 for other in final_keywords):
+            final_keywords.append(keyword[:kw_max_len])
+    logger.debug(f"Keywords (max len. {kw_max_len}):\t{final_keywords}")
+    return final_keywords
+
+
+def saves_summary(
+    summarize_output, outpath: str or Path = None, add_signature=True, **kwargs
+) -> Path:
+    """
+    saves_summary - save the summary generated from summarize_via_tokenbatches() to a text file
+
+    summarize_output: output from summarize_via_tokenbatches()
+    outpath: path to the output file
+    add_signature: whether to add a signature to the output file
+    kwargs: additional keyword arguments to include in the output file
+    """
+    logger = logging.getLogger(__name__)
+    sum_text = [f"{s['summary'][0]}\n" for s in summarize_output]
+    sum_scores = [f"\n - {round(s['summary_score'],4)}" for s in summarize_output]
+    scores_text = "\n".join(sum_scores)
+    full_summary = "\n".join(sum_text)
+
+    keywords = "_".join(extract_keywords(full_summary, kw_max_len=4))
+    logger.debug(f"kw:\t{keywords}")
+    outpath = (
+        Path.cwd() / f"DocSumm_{keywords}_{get_timestamp()}.txt"
+        if outpath is None
+        else Path(outpath)
+    )
+    logger.info(f"Saving summary to:\t{outpath.name}")
+    with open(
+        outpath,
+        "w",
+        encoding="utf-8",
+    ) as fo:
+        fo.writelines(full_summary)
+        fo.write("\n\n")
+        if add_signature:
+            fo.write("\n\n---\n\n")
+            fo.write("Generated with the Document Summarization space :)\n\n")
+            fo.write("https://hf.co/spaces/pszemraj/document-summarization\n\n")
+    with open(
+        outpath,
+        "a",
+        encoding="utf-8",
+    ) as fo:
+        fo.write("\n")
+        fo.write(f"## Section Scores:\n\n")
+        fo.writelines(scores_text)
+        fo.write("\n\n")
+        fo.write(f"Date: {get_timestamp()}\n\n")
+        if kwargs:
+            fo.write("---\n\n")
+            fo.write("## Parameters:\n\n")
+            for key, value in kwargs.items():
+                fo.write(f"{key}: {value}\n")
+    return outpath