Update README.md

README.md

@@ -1,3 +1,161 @@
----
-license: apache-2.0
----
+# MarCognity-AI  
+**The framework that teaches artificial intelligence how to think.**
+
+---
+
+## Table of Contents
+
+- [What is MarCognity-AI](#what-is-marcognity-ai)
+- [Origins](#origins)
+- [Vision](#vision)
+- [Why Use It](#why-use-it)
+- [Core Capabilities](#core-capabilities)
+- [Usage Examples](#usage-examples)
+- [Cognitive Architecture](#cognitive-architecture)
+- [Integrated AI Models](#integrated-ai-models)
+
+---
+
+## What is MarCognity-AI
+
+MarCognity-AI is an open-source framework that transforms language models into **cognitive assistants**.  
+It doesn’t just generate responses — it **evaluates**, **improves**, **visualizes**, **remembers**, and **reflects ethically** on its outputs.  
+Its goal is to make the hidden processes behind AI-generated responses transparent.
+
+Born from curiosity.  
+Grown through persistence.  
+Now ready to challenge how we think about artificial intelligence.
+
+---
+
+## Origins
+
+During an LLM experiment done out of curiosity, a friend said:  
+> “If you improve it, it could be really useful.”
+
+That sentence sparked something.  
+It became a personal challenge.
+
+I dove into books, courses like an AI developer master’s, experiments, and lines of code.  
+With creativity, determination, and one goal: **never give up**.
+
+MarCognity wasn’t born in a lab.  
+It was born from a curious, free, and determined mind.
+
+---
+
+## Vision
+
+> An AI that generates, evaluates, visualizes — and learns from its own outputs.
+
+- Multilevel academic prompting  
+- Metacognitive evaluation (semantic score + reflection)  
+- Scientific retrieval from open-access databases  
+- Conceptual diagrams and dynamic graphs  
+- FAISS semantic memory with self-improvement  
+- Ethical analysis and cognitive filtering  
+- Reflective cognitive journal
+
+---
+
+## Why Use It
+
+### 1. Integrated Metacognitive Thinking  
+Each response is **evaluated**, **improved**, and **contextualized**.  
+MarCognity reflects on its output, analyzes coherence, and compares it with past responses.
+
+### 2. Scientific Retrieval and Cognitive Visualization  
+It integrates open-access sources (arXiv, PubMed, Zenodo) and generates **conceptual diagrams**, **dynamic graphs**, and **interpretive curves** to make each response **visually understandable**.
+
+### 3. Ethics and Responsibility at the Core  
+Each output undergoes an **ethical audit**: bias detection, risk analysis, and cognitive filtering.  
+MarCognity isn’t just intelligent. It’s **aware**.
+
+### 4. Reflective Cognitive Journal  
+Each response is accompanied by a detailed **metacognitive reflection**, saved in Markdown for analysis and reuse.
+
+---
+
+## Core Capabilities
+
+- Scientific generation powered by LLMs  
+- Retrieval and validation of sources (arXiv, PubMed, Zenodo, OpenAlex)  
+- Intelligent visualization (Plotly, NetworkX…)  
+- Responses adaptable to beginner / advanced / expert levels  
+- Automatic improvement of weak responses  
+- Version archiving in FAISS memory  
+- Ethical risk and linguistic bias analysis  
+- Reflective cognitive journal with Markdown export
+
+---
+
+## Usage Examples
+
+### Scientific Question  
+**Input:** “Explain the role of chaperone proteins.”  
+**Output:** Response + sources + semantic score + conceptual diagram
+
+### Ethical Dilemma  
+**Input:** “Is it right to use AI to decide criminal sentences?”  
+**Output:** Argumentation + ethical analysis + detected biases
+
+### Multidisciplinary Question  
+**Input:** “Compare the view of consciousness in philosophy and neuroscience.”  
+**Output:** Structured response + sources + cognitive visualization + reflective journal
+
+---
+
+## Try It Now  
+### Quick Demo
+
+Want to see how MarCognity-AI works?
+
+Check out the file `marcognity_demo.ipynb`  
+It’s not interactive, but it’s readable and self-explanatory. A concrete example of how the system works.  
+It shows step-by-step how the agent generates, evaluates, and reflects on a response.
+
+[Meta LLaMA 4 Community License](https://ai.meta.com/llama/license)  
+[![License: Apache 2.0](https://img.shields.io/badge/license-Apache%202.0-blue)](https://www.apache.org/licenses/LICENSE-2.0)  
+![Non-Commercial Use](https://img.shields.io/badge/Uso-Non%20commerciale-red)  
+[![Contribute](https://img.shields.io/badge/Contribuisci-Aperto%20a%20PR-green)](Contributing.md)
+
+---
+
+## Integrated AI Models
+
+| Integrated Models                                            | License                              | Main Restrictions                                                   |
+|--------------------------------------------------------------|--------------------------------------|----------------------------------------------------------------------|
+| meta-llama/llama-4-maverick-17b-128e-instruct                | LLaMA 4 Community License (Meta)     | Research and application use allowed; must comply with Meta’s AUP   |
+| allenai/specter                                              | Apache 2.0                           | Free for commercial use with attribution                            |
+| ktrapeznikov/scibert_scivocab_uncased_squad_v2               | Apache 2.0                           | Free for commercial use with attribution                            |
+| Helsinki-NLP (OPUS-MT models on HuggingFace)                 | CC-BY-4.0                            | Free use with mandatory citation                                    |
+| RandomForest Model                                           | None (classic algorithm)             | No license restrictions; depends on data used                       |
+| CrossEncoder (DeBERTa-based)                                 | Varies (often MIT or Apache 2.0)     | Free use if open license is respected                               |
+
+---
+
+## Cognitive Architecture
+
+| Module                     | Function                                                  |
+|----------------------------|-----------------------------------------------------------|
+| Problem Classification     | Automatic recognition of input type                       |
+| Academic Prompting         | Structuring complex multidisciplinary queries             |
+| Scientific Retrieval       | Asynchronous querying of multiple open-access sources     |
+| Semantic Evaluation        | Response analysis with logical scoring                    |
+| FAISS Memory               | Archiving and comparison with past responses              |
+| Cognitive Visualization    | Uses HuggingFace’s transformers library and selected models for scientific content processing, ethical analysis, and cognitive representation |
+
+---
+
+## How to Contribute
+
+Got ideas, suggestions, or want to improve a feature?
+
+1. Fork the repository  
+2. Create a branch (`git checkout -b improvement`)  
+3. Modify `.py` or `.ipynb` files  
+4. Open a pull request with a clear description  
+
+See the [CONTRIBUTING.md](Contributing.md) file for contribution guidelines.
+
+This project is released under the Apache 2.0