# DISCOVERY.md
This document is automatically generated to provide an LLM with an easy way to discover the entire codebase. It includes the folder structure and detailed information about classes, methods, and functions within each relevant file.
---
## Folder Structure Overview
# Deckbuilder Folder Structure
This document provides an overview of the folder structure for the Deckbuilder project, explaining the purpose of key directories and files. It acts as a sitemap for the repository.
## Root Directory
The root directory contains project configuration, documentation, and top-level directories for source code, tests, and other assets.
- **`.github/`**: Contains GitHub-specific configurations.
- `ISSUE_TEMPLATE/`: Templates for creating new GitHub issues.
- `workflows/`: CI/CD pipeline configurations for GitHub Actions (e.g., testing, publishing).
- **`.vscode/`**: Holds VS Code workspace settings, launch configurations, and recommended extensions for a consistent development environment.
- **`assets/`**: Contains static assets used by the application, such as default templates.
- **`docs/`**: Project documentation.
- `Features/`: Detailed descriptions of implemented or planned features.
- `old_docs/`: Archived documentation.
- `CODE_REVIEW_DESIGN.md`, etc.: Design documents for various aspects of the project.
- **`output/`**: The default directory where generated presentations and other output files are saved.
- **`scripts/`**: A collection of utility and helper scripts for development and maintenance tasks (e.g., `check_no_os_environ.py`, `copy_golden_files.py`).
- **`src/`**: Contains all the source code for the project.
- **`templates/`**: A directory for user-supplied presentation templates that can be used by Deckbuilder.
- **`tests/`**: Contains all the automated tests for the project.
### Root Configuration Files
- **`.gitignore`**: A list of files and directories that Git should ignore (e.g., `__pycache__`, `.venv`).
- **`.pre-commit-config.yaml`**: Configuration for pre-commit hooks to enforce code style and quality before committing code.
- **`.python-version`**: Specifies the Python version used for this project, typically used by tools like `pyenv`.
- **`bandit.yaml`**: Configuration file for Bandit, a security linter for Python code.
- **`pyproject.toml`**: Defines project metadata and build dependencies for Python packaging (PEP 518). Used by tools like `pip` and `uv`.
- **`README.md`**: The main entry point for developers, providing an overview of the project, setup instructions, and usage examples.
- **`requirements.txt`**: Lists the Python dependencies for the project.
- **`TASK.md`**: A file for tracking development tasks and progress.
- **`uv.lock`**: A lock file generated by the `uv` package manager to ensure deterministic installation of dependencies.
## `src` Directory
The `src` directory is the heart of the project, containing the Python source code for the application and its components.
- **`deckbuilder/`**: The core Python package for the Deckbuilder application. This is where the main logic for creating presentations from Markdown and data resides.
- **`mcp_server/`**: A server component, likely standing for "Multi-Content Presentation" server, which provides content analysis and layout recommendations.
- **`placekitten/`**: A utility module for integrating with the `placekitten.com` service to provide placeholder images in presentations.
- **`shared/`**: A package for code that is shared across different parts of the application (e.g., `deckbuilder` and `mcp_server`).
### `src/deckbuilder`
This is the main application package, with a structure that separates concerns into the following functional subdirectories:
- **`__init__.py`**: Marks the directory as a Python package.
- **`cli.py`**: Legacy CLI entry point. The logic is being moved to the `cli/` directory.
- **`deckbuilder-completion.bash`**: Bash completion script for the CLI.
- **`layout_intelligence.json`**: Data file for layout intelligence.
- **`assets/`**: Contains assets specific to the `deckbuilder` package.
- `master_default_presentation.json`: Default presentation data.
- `master_default_presentation.md`: Default presentation content.
- `templates/`: Default templates.
- **`cli/`**: Contains all Command-Line Interface (CLI) logic.
- `__init__.py`: Package initializer.
- `main.py`: Main entry point for the CLI.
- `commands.py`: Defines the CLI commands.
- `naming_conventions.py`: Defines naming conventions for the CLI.
- **`content/`**: Handles all content processing.
- `__init__.py`: Package initializer.
- `converter.py`: Converts content between different formats.
- `formatter.py`: Formats content for presentation.
- `frontmatter.py`: Processes frontmatter from Markdown files.
- `matcher.py`: Matches content to slide layouts.
- `placeholder_types.py`: Defines different types of placeholders.
- `processor.py`: Main content processor.
- `formatting_support.py`: Helper functions for formatting.
- **`core/`**: Houses the core presentation generation engine.
- `__init__.py`: Package initializer.
- `engine.py`: The core presentation generation engine.
- `presentation_builder.py`: Builds the final presentation.
- `slide_builder.py`: Builds individual slides.
- `table_builder.py`: Builds tables in slides.
- `validation.py`: Validates presentation content.
- **`image/`**: Manages all image handling.
- `__init__.py`: Package initializer.
- `image_handler.py`: Handles image processing.
- `placeholder.py`: Manages image placeholders.
- `placekitten_integration.py`: Integration with the PlaceKitten service.
- **`language_mappings/`**: Contains language mapping files.
- **`structured_frontmatter_patterns/`**: Contains JSON schemas for structured frontmatter.
- **`templates/`**: Responsible for template management.
- `__init__.py`: Package initializer.
- `layout_analyzer.py`: Analyzes template layouts.
- `layout_intelligence.py`: Provides layout recommendations.
- `manager.py`: Manages templates.
- `metadata.py`: Handles template metadata.
- `pattern_loader.py`: Loads template patterns.
- `pattern_schema.py`: Defines the schema for template patterns.
- `recommendation_engine.py`: Recommends templates based on content.
- `table_styles.py`: Defines styles for tables.
- **`utils/`**: Contains shared utilities.
- `__init__.py`: Package initializer.
- `logging.py`: Logging configuration.
- `path.py`: Path management utilities.
### `src/mcp_server`
This package contains the source code for the MCP server.
- **`__init__.py`**: Package initializer.
- **`main.py`**: The main entry point for the server application.
- **`tools.py`**: Various tools for the server.
- **`content_analysis.py`**: Tools for analyzing content.
- **`content_first_tools.py`**: Tools that prioritize content.
- **`content_optimization.py`**: Tools for optimizing content.
- **`layout_recommendations.py`**: Logic for recommending slide layouts.
- **`README_CONTENT_FIRST_TOOLS.md`**: Documentation for the content-first tools.
### `src/placekitten`
This package provides functionality for using placeholder images from `placekitten.com`.
- **`__init__.py`**: Package initializer.
- **`core.py`**: Core logic for fetching and processing kitten images.
- **`filters.py`**: Image filters.
- **`processor.py`**: Image processor.
- **`smart_crop.py`**: Logic for intelligently cropping images.
- **`README.md`**: Documentation for the `placekitten` package.
- **`images/`**: Directory for storing kitten images.
### `src/shared`
This package contains code shared across the project.
- **`__init__.py`**: Package initializer.
## `tests` Directory
This directory contains the automated tests for the project, mirroring the structure of the `src` directory.
- **`deckbuilder/`**: Tests specifically for the `deckbuilder` package.
- **`mcp_server/`**: Tests for the `mcp_server`.n- **`placekitten/`**: Tests for the `placekitten` integration.
- **`fixtures/`**: Contains test fixtures, such as sample data, mock objects, and templates used in tests.
- **`utils/`**: Contains testing utilities, like content generators and validators.
- **`conftest.py`**: A pytest file for configuring tests and defining hooks and fixtures that are shared across multiple test files.
---
## File: `src/deckbuilder/cli.py`
#### Functions:
- `main`
---
## File: `src/deckbuilder/cli/main.py`
#### Classes:
- `DeckbuilderCLI`
#### Methods:
- `_validate_templates_folder`
- `_get_available_templates`
- `create_presentation`
- `analyze_template`
- `validate_template`
- `document_template`
- `enhance_template`
- `generate_placeholder_image`
- `smart_crop_image`
- `list_templates`
- `init_templates`
- `_copy_golden_files_as_examples`
- `get_config`
- `list_supported_languages`
- `validate_language_and_font`
- `remap_presentation`
- `list_patterns`
- `validate_patterns`
- `show_pattern_info`
- `copy_patterns`
- `show_completion_help`
#### Functions:
- `main`
- `create`
- `template`
- `analyze`
- `validate`
- `document`
- `enhance`
- `list_templates`
- `pattern`
- `list_patterns`
- `validate_pattern`
- `info`
- `copy`
- `image`
- `generate`
- `crop`
- `config_group`
- `show`
- `languages`
- `completion`
- `remap`
- `init`
---
## File: `src/deckbuilder/cli/commands.py`
#### Classes:
- `TemplateManager`
- `DocumentationGenerator`
#### Methods:
- `analyze_template`
- `document_template`
- `_generate_template_documentation`
- `validate_template`
- `_validate_template_file`
- `_validate_json_mapping`
- `_validate_placeholder_naming`
- `enhance_template`
- `_create_template_backup`
- `_modify_master_slide_placeholders`
- `_generate_convention_mapping`
- `_find_template_folder`
- `get_implemented_layouts`
- `generate_getting_started`
#### Functions:
- `main`
---
## File: `src/deckbuilder/cli/naming_conventions.py`
#### Classes:
- `PlaceholderContext`
- `SemanticInfo`
- `NamingConvention`
#### Methods:
- `generate_placeholder_name`
- `_detect_semantic_info`
- `_tier1_exact_mapping`
- `_tier2_powerpoint_types`
- `_tier3_universal_patterns`
- `_tier4_layout_inference`
- `_tier5_generic_fallback`
- `_infer_column_semantic`
- `_infer_comparison_semantic`
- `_infer_picture_semantic`
- `_infer_agenda_semantic`
- `_infer_position_from_layout`
- `_normalize_layout_name`
- `_build_layout_mappings`
- `_build_powerpoint_type_map`
- `_build_universal_patterns`
- `convert_template_to_conventions`
- `validate_naming_consistency`
- `_follows_convention_format`
- `_extract_naming_pattern`
#### Functions:
- `test_naming_convention`
---
## File: `src/deckbuilder/content/converter.py`
#### Classes:
- `FrontmatterConverter`
#### Methods:
- `_process_content_field`
- `_is_table_content`
- `_parse_markdown_table`
- `_parse_cell_formatting`
#### Functions:
- `_extract_table_from_content`
- `markdown_to_canonical_json`
- `_process_markdown_content`
---
## File: `src/deckbuilder/content/matcher.py`
#### Classes:
- `ContentTemplateMatcher`
#### Methods:
- `analyze_content_description`
- `match_content_to_templates`
---
## File: `src/deckbuilder/content/placeholder_types.py`
#### Functions:
- `get_placeholder_category`
- `is_title_placeholder`
- `is_subtitle_placeholder`
- `is_content_placeholder`
- `is_media_placeholder`
---
## File: `src/deckbuilder/content/processor.py`
#### Classes:
- `ContentProcessor`
#### Methods:
- `parse_markdown_with_frontmatter`
- `_parse_structured_frontmatter`
- `_parse_frontmatter_safe`
- `_parse_slide_content`
- `_parse_rich_content`
- `_parse_inline_formatting`
---
## File: `src/deckbuilder/content/formatting_support.py`
#### Classes:
- `FormattingSupport`
#### Methods:
- `get_supported_languages`
- `normalize_language_input`
- `validate_language_code`
- `validate_font_name`
- `apply_language_to_run`
- `apply_font_to_run`
- `load_language_mapping`
- `preserve_case`
- `is_context_exception`
- `apply_text_replacements`
- `process_text_frame`
- `process_shape`
- `update_theme_fonts`
- `update_presentation`
#### Functions:
- `get_default_language`
- `get_default_font`
- `print_supported_languages`
---
## File: `src/deckbuilder/core/engine.py`
#### Classes:
- `Deckbuilder`
#### Methods:
- `_initialize_presentation`
- `create_presentation`
- `write_presentation`
#### Functions:
- `singleton`
- `get_deckbuilder_client`
---
## File: `src/deckbuilder/core/presentation_builder.py`
#### Classes:
- `PresentationBuilder`
#### Methods:
- `layout_mapping`
- `clear_slides`
- `add_slide`
- `add_slide_with_direct_mapping`
---
## File: `src/deckbuilder/core/slide_builder.py`
#### Classes:
- `SlideBuilder`
#### Methods:
- `clear_slides`
- `add_slide`
- `add_speaker_notes`
- `add_slide_with_direct_mapping`
- `_copy_placeholder_names_from_mapping`
- `_apply_content_to_mapped_placeholders`
- `_resolve_field_name_variations`
- `_apply_content_to_placeholder_unified`
- `_apply_content_to_single_placeholder`
- `_process_nested_image_fields`
- `_process_table_data`
- `_clear_table_content_from_placeholders`
- `_contains_table_content`
---
## File: `src/deckbuilder/core/table_builder.py`
#### Classes:
- `TableBuilder`
#### Methods:
- `add_table_to_slide`
- `_apply_table_styling`
- `_apply_table_borders`
- `_set_cell_borders`
- `_parse_custom_color`
- `_parse_dimensions`
- `_calculate_content_offset`
- `_get_font_size`
- `_apply_column_widths`
- `_apply_row_heights`
---
## File: `src/deckbuilder/core/validation.py`
#### Classes:
- `ValidationError`
- `PresentationValidator`
#### Methods:
- `__init__`
- `_load_template_mapping`
- `validate_markdown_to_json`
- `validate_pre_generation`
- `_validate_slide_placeholders`
- `_can_resolve_field_name`
- `_resolve_field_name_variations`
- `validate_post_generation`
- `_validate_slide_content`
- `_validate_critical_placeholders`
- `_extract_shape_text`
- `_get_semantic_type`
- `_strip_formatting_markers`
- `_is_table_markdown`
- `_check_placeholder_has_image`
- `_parse_markdown_sections`
- `_validate_section_conversion`
---
## File: `src/deckbuilder/image/image_handler.py`
#### Classes:
- `ImageHandler`
#### Methods:
- `_ensure_cache_dir`
- `validate_image`
- `get_image_dimensions`
- `process_image`
- `_resize_with_aspect_ratio`
- `_generate_cache_key`
- `_get_cached_image`
- `_save_processed_image`
- `cleanup_cache`
- `get_cache_stats`
---
## File: `src/deckbuilder/image/placeholder.py`
#### Classes:
- `ImagePlaceholderHandler`
#### Methods:
- `handle_image_placeholder`
---
## File: `src/deckbuilder/image/placekitten_integration.py`
#### Classes:
- `PlaceKittenIntegration`
#### Methods:
- `is_available`
- `generate_fallback`
- `_create_fallback_image`
- `_apply_professional_styling`
- `_select_image_id`
- `_generate_fallback_cache_key`
- `_get_professional_styling`
- `get_fallback_info`
- `cleanup_fallback_cache`
---
## File: `src/deckbuilder/templates/layout_analyzer.py`
#### Classes:
- `LayoutCapabilityAnalyzer`
#### Methods:
- `analyze_layout_capabilities`
- `generate_layout_recommendations`
---
## File: `src/deckbuilder/templates/layout_intelligence.py`
#### Classes:
- `LayoutRecommendation`
- `ContentAnalysis`
- `LayoutIntelligence`
#### Methods:
- `_load_intelligence_data`
- `analyze_content`
- `recommend_layouts`
- `_detect_intent`
- `_detect_content_type`
- `_analyze_structure`
- `_find_keywords`
- `_count_content_blocks`
- `_has_image_content`
- `_has_numeric_content`
- `_score_layout`
- `_generate_placeholder_mapping`
- `_get_optimization_hints`
#### Functions:
- `test_layout_intelligence`
---
## File: `src/deckbuilder/templates/manager.py`
#### Classes:
- `TemplateManager`
#### Methods:
- `check_template_exists`
- `load_layout_mapping`
- `ensure_layout_mapping`
- `get_layout_mapping`
- `get_template_path`
- `prepare_template`
---
## File: `src/deckbuilder/templates/metadata.py`
#### Classes:
- `LayoutMetadata`
- `TemplateMetadata`
- `TemplateMetadataLoader`
#### Methods:
- `_get_default_template_folder`
- `load_template_metadata`
- `_parse_template_data`
- `_parse_enhanced_format`
- `_parse_legacy_format`
- `_extract_placeholder_names`
- `_technical_to_semantic`
- `_generate_layout_metadata`
- `_determine_layout_complexity`
- `_determine_content_type`
- `_generate_layout_description`
- `_generate_best_for`
- `_determine_required_placeholders`
- `_generate_template_description`
- `_generate_use_cases`
- `_determine_target_audience`
- `get_all_available_templates`
- `validate_template_exists`
- `get_template_names`
- `clear_cache`
- `get_enhanced_layout_metadata`
- `get_all_pattern_based_layouts`
- `create_template_metadata_from_patterns`
- `get_pattern_example`
- `get_layout_validation_info`
---
## File: `src/deckbuilder/templates/pattern_loader.py`
#### Classes:
- `PatternLoader`
#### Methods:
- `__init__`
- `load_patterns`
- `_load_builtin_patterns`
- `_load_user_patterns`
- `find_pattern_file_for_layout`
- `_load_pattern_file`
- `get_pattern_for_layout`
- `get_layout_names`
- `get_patterns_by_file_source`
- `clear_cache`
- `validate_all_patterns`
- `validate_pattern_file`
