| # 🛠️ helpers/ - Ferramentas de IA de Terceiros Adaptadas para ADUC-SDR | |
| Esta pasta contém implementações adaptadas de modelos e utilitários de IA de terceiros, que servem como "especialistas" ou "ferramentas" de baixo nível para a arquitetura ADUC-SDR. | |
| **IMPORTANTE:** O conteúdo desta pasta é de autoria de seus respectivos idealizadores e desenvolvedores originais. Esta pasta **NÃO FAZ PARTE** do projeto principal ADUC-SDR em termos de sua arquitetura inovadora. Ela serve como um repositório para as **dependências diretas e modificadas** que os `DeformesXDEngines` (os estágios do "foguete" ADUC-SDR) invocam para realizar tarefas específicas (geração de imagem, vídeo, áudio). | |
| As modificações realizadas nos arquivos aqui presentes visam principalmente: | |
| 1. **Adaptação de Interfaces:** Padronizar as interfaces para que se encaixem no fluxo de orquestração do ADUC-SDR. | |
| 2. **Gerenciamento de Recursos:** Integrar lógicas de carregamento/descarregamento de modelos (GPU management) e configurações via arquivos YAML. | |
| 3. **Otimização de Fluxo:** Ajustar as pipelines para aceitar formatos de entrada mais eficientes (ex: tensores pré-codificados em vez de caminhos de mídia, pulando etapas de codificação/decodificação redundantes). | |
| --- | |
| ## 📄 Licenciamento | |
| O conteúdo original dos projetos listados abaixo é licenciado sob a **Licença Apache 2.0**, ou outra licença especificada pelos autores originais. Todas as modificações e o uso desses arquivos dentro da estrutura `helpers/` do projeto ADUC-SDR estão em conformidade com os termos da **Licença Apache 2.0**. | |
| As licenças originais dos projetos podem ser encontradas nas suas respectivas fontes ou nos subdiretórios `incl_licenses/` dentro de cada módulo adaptado. | |
| --- | |
| ## 🛠️ API dos Helpers e Guia de Uso | |
| Esta seção detalha como cada helper (agente especialista) deve ser utilizado dentro do ecossistema ADUC-SDR. Todos os agentes são instanciados como **singletons** no `hardware_manager.py` para garantir o gerenciamento centralizado de recursos de GPU. | |
| ### **gemini_helpers.py (GeminiAgent)** | |
| * **Propósito:** Atua como o "Oráculo de Síntese Adaptativo", responsável por todas as tarefas de processamento de linguagem natural, como criação de storyboards, geração de prompts, e tomada de decisões narrativas. | |
| * **Singleton Instance:** `gemini_agent_singleton` | |
| * **Construtor:** `GeminiAgent()` | |
| * Lê `configs/gemini_config.yaml` para obter o nome do modelo, parâmetros de inferência e caminhos de templates de prompt. A chave da API é lida da variável de ambiente `GEMINI_API_KEY`. | |
| * **Métodos Públicos:** | |
| * `generate_storyboard(prompt: str, num_keyframes: int, ref_image_paths: list[str])` | |
| * **Inputs:** | |
| * `prompt`: A ideia geral do filme (string). | |
| * `num_keyframes`: O número de cenas a serem geradas (int). | |
| * `ref_image_paths`: Lista de caminhos para as imagens de referência (list[str]). | |
| * **Output:** `tuple[list[str], str]` (Uma tupla contendo a lista de strings do storyboard e um relatório textual da operação). | |
| * `select_keyframes_from_pool(storyboard: list, base_image_paths: list[str], pool_image_paths: list[str])` | |
| * **Inputs:** | |
| * `storyboard`: A lista de strings do storyboard gerado. | |
| * `base_image_paths`: Imagens de referência base (list[str]). | |
| * `pool_image_paths`: O "banco de imagens" de onde selecionar (list[str]). | |
| * **Output:** `tuple[list[str], str]` (Uma tupla contendo a lista de caminhos de imagens selecionadas e um relatório textual). | |
| * `get_anticipatory_keyframe_prompt(...)` | |
| * **Inputs:** Contexto narrativo e visual para gerar um prompt de imagem. | |
| * **Output:** `tuple[str, str]` (Uma tupla contendo o prompt gerado para o modelo de imagem e um relatório textual). | |
| * `get_initial_motion_prompt(...)` | |
| * **Inputs:** Contexto narrativo e visual para a primeira transição de vídeo. | |
| * **Output:** `tuple[str, str]` (Uma tupla contendo o prompt de movimento gerado e um relatório textual). | |
| * `get_transition_decision(...)` | |
| * **Inputs:** Contexto narrativo e visual para uma transição de vídeo intermediária. | |
| * **Output:** `tuple[dict, str]` (Uma tupla contendo um dicionário `{"transition_type": "...", "motion_prompt": "..."}` e um relatório textual). | |
| * `generate_audio_prompts(...)` | |
| * **Inputs:** Contexto narrativo global. | |
| * **Output:** `tuple[dict, str]` (Uma tupla contendo um dicionário `{"music_prompt": "...", "sfx_prompt": "..."}` e um relatório textual). | |
| ### **flux_kontext_helpers.py (FluxPoolManager)** | |
| * **Propósito:** Especialista em geração de imagens de alta qualidade (keyframes) usando a pipeline FluxKontext. Gerencia um pool de workers para otimizar o uso de múltiplas GPUs. | |
| * **Singleton Instance:** `flux_kontext_singleton` | |
| * **Construtor:** `FluxPoolManager(device_ids: list[str], flux_config_file: str)` | |
| * Lê `configs/flux_config.yaml`. | |
| * **Método Público:** | |
| * `generate_image(prompt: str, reference_images: list[Image.Image], width: int, height: int, seed: int = 42, callback: callable = None)` | |
| * **Inputs:** | |
| * `prompt`: Prompt textual para guiar a geração (string). | |
| * `reference_images`: Lista de objetos `PIL.Image` como referência visual. | |
| * `width`, `height`: Dimensões da imagem de saída (int). | |
| * `seed`: Semente para reprodutibilidade (int). | |
| * `callback`: Função de callback opcional para monitorar o progresso. | |
| * **Output:** `PIL.Image.Image` (O objeto da imagem gerada). | |
| ### **dreamo_helpers.py (DreamOAgent)** | |
| * **Propósito:** Especialista em geração de imagens de alta qualidade (keyframes) usando a pipeline DreamO, com capacidades avançadas de edição e estilo a partir de referências. | |
| * **Singleton Instance:** `dreamo_agent_singleton` | |
| * **Construtor:** `DreamOAgent(device_id: str = None)` | |
| * Lê `configs/dreamo_config.yaml`. | |
| * **Método Público:** | |
| * `generate_image(prompt: str, reference_images: list[Image.Image], width: int, height: int)` | |
| * **Inputs:** | |
| * `prompt`: Prompt textual para guiar a geração (string). | |
| * `reference_images`: Lista de objetos `PIL.Image` como referência visual. A lógica interna atribui a primeira imagem como `style` e as demais como `ip`. | |
| * `width`, `height`: Dimensões da imagem de saída (int). | |
| * **Output:** `PIL.Image.Image` (O objeto da imagem gerada). | |
| ### **ltx_manager_helpers.py (LtxPoolManager)** | |
| * **Propósito:** Especialista na geração de fragmentos de vídeo no espaço latente usando a pipeline LTX-Video. Gerencia um pool de workers para otimizar o uso de múltiplas GPUs. | |
| * **Singleton Instance:** `ltx_manager_singleton` | |
| * **Construtor:** `LtxPoolManager(device_ids: list[str], ltx_model_config_file: str, ltx_global_config_file: str)` | |
| * Lê o `ltx_global_config_file` e o `ltx_model_config_file` para configurar a pipeline. | |
| * **Método Público:** | |
| * `generate_latent_fragment(**kwargs)` | |
| * **Inputs:** Dicionário de keyword arguments (`kwargs`) contendo todos os parâmetros da pipeline LTX, incluindo: | |
| * `height`, `width`: Dimensões do vídeo (int). | |
| * `video_total_frames`: Número total de frames a serem gerados (int). | |
| * `video_fps`: Frames por segundo (int). | |
| * `motion_prompt`: Prompt de movimento (string). | |
| * `conditioning_items_data`: Lista de objetos `LatentConditioningItem` contendo os tensores latentes de condição. | |
| * `guidance_scale`, `stg_scale`, `num_inference_steps`, etc. | |
| * **Output:** `tuple[torch.Tensor, tuple]` (Uma tupla contendo o tensor latente gerado e os valores de padding utilizados). | |
| ### **mmaudio_helper.py (MMAudioAgent)** | |
| * **Propósito:** Especialista em geração de áudio para um determinado fragmento de vídeo. | |
| * **Singleton Instance:** `mmaudio_agent_singleton` | |
| * **Construtor:** `MMAudioAgent(workspace_dir: str, device_id: str = None, mmaudio_config_file: str)` | |
| * Lê `configs/mmaudio_config.yaml`. | |
| * **Método Público:** | |
| * `generate_audio_for_video(video_path: str, prompt: str, negative_prompt: str, duration_seconds: float)` | |
| * **Inputs:** | |
| * `video_path`: Caminho para o arquivo de vídeo silencioso (string). | |
| * `prompt`: Prompt textual para guiar a geração de áudio (string). | |
| * `negative_prompt`: Prompt negativo para áudio (string). | |
| * `duration_seconds`: Duração exata do vídeo (float). | |
| * **Output:** `str` (O caminho para o novo arquivo de vídeo com a faixa de áudio integrada). | |
| ### https://huggingface.co/spaces/ByteDance-Seed/SeedVR2-3B/tree/main | |
| --- | |
| ## 🔗 Projetos Originais e Atribuições | |
| (A seção de atribuições e licenças permanece a mesma que definimos anteriormente) | |
| ### DreamO | |
| * **Repositório Original:** [https://github.com/bytedance/DreamO](https://github.com/bytedance/DreamO) | |
| ... | |
| ### LTX-Video | |
| * **Repositório Original:** [https://github.com/Lightricks/LTX-Video](https://github.com/Lightricks/LTX-Video) | |
| ... | |
| ### MMAudio | |
| * **Repositório Original:** [https://github.com/hkchengrex/MMAudio](https://github.com/hkchengrex/MMAudio) | |
| ... |