Update README.md

README.md

@@ -1,5 +1,5 @@
 ---
-title: MultiAgent System For Screenplay Creation
+title: Scriptura
 emoji: 🏆
 colorFrom: yellow
 colorTo: blue
@@ -8,130 +8,138 @@ sdk_version: 5.32.1
 app_file: app.py
 pinned: false
 license: mit
-tag: "agent-demo-track"
+tag: agent-demo-track
 ---
 
-# TODO NAME OF THE AGENT
+# Scriptura
 
-## Agent capabilities
+## Introduction
 
-TODO: BETTER INTRO
-The aim of our agent is to support authors in their creative process for scenarios and storyboards.
+**Scriptura** is a multi-agent AI system designed to assist authors in creating screenplays, storyboards, and soundtracks. Its main goal is to automate and accelerate the stages of analysis, summarization, and enrichment of narrative text, allowing screenwriters to focus on the creative aspects.
 
-### Agent Flow
+The core stack includes:
+- **DeepSeek (deepseek-ai/DeepSeek-R1)** as the base model for all text operations (analysis, summarization, generation) via APIs managed by Nebius AI.
+- **FLUX (black-forest-labs/FLUX.1-dev)** for image generation (storyboards, concept art) integrated into the narrative flow.
+- **MusicGen (facebook/musicgen-melody)** to create short audio tracks or sound effects, useful for prototyping or presenting.
+- Optional web search (integrated with DuckDuckGo API) to fetch external resources (original scripts, sound effects, reference materials).
 
-![image/png](https://cdn-uploads.huggingface.co/production/uploads/683ed65c9471bc9e3db5e4be/UkHpAimZUl8wIOP1qDuGB.png)
+**Scriptura** supports inputs in various formats:
+- **Text**: TXT, PDF, DOCX (automatically converted to structured plain text)  
+- **Images**: JPEG, PNG (for analyzing existing storyboards or screenshots)  
+- **Audio**: MP3, WAV (for transcribing dialogue or analyzing uploaded soundtracks)  
 
-**A**
+There are size and duration checks on uploaded files to prevent excessively large inputs.
 
-Starting the agent
-
-**B**
-  
-The agent receives as input a text file containing the script, 
-either in plain text format or in structured formats (e.g. PDF, DOCX), 
-which it then converts into plain text for processing.
-
-**C**
-
-The agent extracts a summary of the overall content of the scenario, 
-identifying the main narrative lines and the time frame.
-  
-This will help creating a big picture version of the draft for the next steps
-
-**D**
-
-The agent will identify the main entities (characters, locations, events) and key themes in the script.
-
-It will also generate a small abstract (~5 sentences) 
-with enough details to understand the overall plot and tone.
-
-**E**
-  
-The agent checks whether the input text matches a known or published script.
-  
-If it does, 
-it will check the license and availability of rights to understand if it is possible to operate on it.
-  
-In case of any limitations, the agent will warn the user about restrictions.
-  
-**F**
-
-The agent will perform an analysis of the main points of the sctipt:
-
-- Characters: extract and catalog the names of the characters, 
-classifying them by role (protagonist, antagonist, secondary characters), 
-gender and age/physical description.
-
-- Locations: Detect the places where the scenes take place 
-(interiors, exteriors, historical periods, geographical location) and catalogue them.
-
-- Plot points: Isolate key plot points
-
-- Vibes (Look and Feel): Understand the style (dramatic, comic, thriller, horror) 
-and the overall sensation (suspense, irony, melancholy).
-
-
-**G**
-
-Define the agent goal.
-
-Having achieved a comprehensive summary, the agent will ask for the final goal:
-
-- Remake / Rewrite
-- Change of medium (movie, tv series, ...)
-- Other purposes (Workshop, Interactive presentation, Didactic analysis, ...)
+---
 
+## Agent Capabilities
 
-**H**
+**Input File Parsing**  
+:  - **Formats accepted**: `TXT`, `PDF`, `DOCX`, `JPEG/PNG`, `MP3/WAV`  
+   - **Process**: PDF/DOCX → plain text; OCR on images; speech-to-text on audio.  
+   - **Why it matters**: Provides structured input for all downstream modules.
 
-Structural proposal.
+**Overall Plot Summary**  
+:  - **Model**: `DeepSeek-R1`  
+   - **Output**: 4–6 sentence summary of main narrative threads (timeframe, tone).  
+   - **Mechanics**: API calls to DeepSeek with retry logic for improved coherence.
 
-Coherently with the goal, 
-the agent will split the narrative structure into acts and scenes, 
-pointing to the reference text as well
+**Entity & Theme Extraction**  
+:  - **Technique**: Named Entity Recognition (via **DeepSeek**)  
+   - **Extracts**: Characters, locations, key events, recurring themes, narrative tone.  
+   - **Output**: JSON/CSV + ~5-sentence abstract.
 
-**I**
+**Rights & Licensing Verification**  
+:  - **Web Search ON**: Queries DuckDuckGo API → fetch license info if match.  
+   - **Web Search OFF**: May recognize very famous works internally (e.g. “Harry Potter”) but not guaranteed.  
+   - **If no match & search OFF**: No licensing check.
 
-Media generation.
+**Image Generation (Storyboard & Concept Art)**  
+:  - **Model**: `FLUX (black-forest-labs/FLUX.1-dev)`  
+   - **Trigger**: “Generate Image” / storyboard phase.  
+   - **Process**: DeepSeek crafts cinematic prompt → FLUX returns PNG/JPEG + caption.
 
-This phase consists of a series of steps focused on creating additional contents, 
-to support the textual part of the script:
+**Audio Generation (Music & Sound Effects)**  
+:  - **Model**: `MusicGen (facebook/musicgen-melody)`  
+   - **Trigger**: “Generate Audio.”  
+   - **Process**: Send prompt → receive MP3/WAV (standalone audio, no text/images).
 
-- Concept art
-- Storyboard for narrative keypoints
-- Images for plot points
+**In-Depth Analysis of Key Points**  
+:  - **Extracts**:  
+     - Characters (role, gender, description)  
+     - Locations (interior/exterior, period, geography)  
+     - Plot Points (crucial narrative beats via Story Understanding models)  
+   - **Extras**: Semantic toponym extraction → internal scene maps; detect transitions (“Suddenly,” “Meanwhile”).
 
+**Optional Web Search**  
+:  - **Checkbox** toggles DuckDuckGo API lookups.  
+   - **If Enabled**: search preconfigured sites (free & paid) for scripts, sound effects.  
+   - **Output**: List of links + short summaries.
 
-**TODO: add sound and bias analysis?**
 
+---
 
-**J**
+## Agent Flow
+
+```mermaid
+flowchart LR
+    A[Start Agent] --> B[Load Input (text, image, audio)]
+    B --> C[Preprocessing: PDF/DOCX → text, OCR, audio transcription]
+    C --> D[Generate Plot Summary (DeepSeek)]
+    D --> E[Extract Entities & Themes (DeepSeek)]
+    E --> F {Web Search Enabled?}
+    F -->|Yes| G[Web Search via DuckDuckGo API]
+    F -->|No| H[Continue Offline Analysis]
+    H --> I[Rights & Licensing Check]
+    I --> J[Deep Analysis: characters, locations, plot points]
+    J --> K {Image Generation Requested?}
+    K -->|Yes| L[API Call to FLUX for storyboard/concept art]
+    K -->|No| M[Skip Image Generation]
+    M --> N {Audio Generation Requested?}
+    N -->|Yes| O[API Call to MusicGen for audio tracks]
+    N -->|No| P[Skip Audio Generation]
+    L & O --> Q[Final Output: text, JSON/CSV, images, audio]
+```
+---
+## Deployment & Access and the Code Overview
 
-Final deliverable
+---
+## Use Cases
 
+**Independent Writer**  
+:  - Upload a screenplay and quickly get a summary, a list of characters, and locations.  
+   - Create visual storyboards of key narrative moments via FLUX (PNG/JPEG outputs).  
+   - Generate brief soundtracks or sound effects to accompany script presentations (MP3/WAV).
 
+**Film Production Company**  
+:  - Import multiple screenplays (PDF, DOCX) and automatically receive reports on characters, locations, and potential copyright issues.  
+   - Use the web search feature to find reference scripts or specific sound effects from free/paid sources.  
+   - Develop visual storyboards and audio prototypes to share with directors, artists, and investors.
 
-### Main Techniques
+**Translation and Adaptation Agency**  
+:  - Upload foreign-language scripts and obtain a structured text version with extracted entities (JSON/CSV).  
+   - Generate contextual images for cultural adaptation (e.g., images matching the original setting via FLUX).  
+   - Produce reference audio via MusicGen to test culturally appropriate music for the target audience.
 
-- Transformer-based NLP architectures (BERT, GPT-4) to produce a coherent text synthesis
-- Named Entity Recognition (NER) and context analysis, to identify human characters and their roles
-- Semantic analysis of textual descriptions, toponym extraction, creation of an internal scene map
-- Detection of text patterns (turning expressions such as “Suddenly”, “In the meantime”) 
-and classification using a Story Understanding model
-- Tone analysis and Sentiment analysis for understanding vibes
-- Image generation models (Stable Diffusion, DALL·E 3), with prompts generated by the model
+**Digital Humanities Course**  
+:  - Demonstrate how to build a text-mining tool applied to performing arts, combining NLP, image, and audio pipelines.  
+   - Allow students to analyze real scripts, generate abstracts, scene maps, and visual/audio prototypes in a hands-on environment.  
+   - Explore Transformer models (DeepSeek), OCR, speech-to-text, and AI-driven media generation as part of the curriculum.
 
+---
+## Credits
 
-### Code overview
 
+---
+## Acknowledgements
 
-### Use cases
 
+---
 ### Contributors: 
 - Code Implementation made by luke9705 and DDPM;
 - Ideas creation and testing conducted by OrianIce and Loren1214.
 
+---
 ### Sources
 
 - Russell, S., & Norvig, P. (2021). *Artificial Intelligence: A Modern Approach* (3rd ed.). Pearson.