mrmd-ai 0.1.0__py3-none-any.whl

mrmd_ai/signatures/code.py

@@ -0,0 +1,279 @@
+"""Signature definitions for code transformation programs."""
+
+import dspy
+from typing import Optional
+
+
+class DocumentCodeSignature(dspy.Signature):
+    """
+    Add documentation to the selected code ONLY.
+
+    CRITICAL: You must ONLY transform the `code` field. Do NOT include any code from `local_context`.
+    The `local_context` is provided ONLY to help you understand the code - never include it in output.
+
+    Guidelines:
+    - For functions: Add a docstring describing purpose, parameters, and return value
+    - For classes: Add a class docstring describing purpose and key attributes
+    - For code sections: Add a comment block explaining what the code does
+    - Follow the language's documentation conventions (e.g., Google style for Python)
+    - Keep documentation concise but informative
+    - Output must be EXACTLY the `code` input with documentation added
+    """
+
+    code: str = dspy.InputField(
+        desc="The EXACT code to document. Output must contain ONLY this code with docs added."
+    )
+    language: str = dspy.InputField(
+        desc="Programming language (e.g., python, javascript, rust)"
+    )
+    local_context: str = dspy.InputField(
+        desc="Surrounding code for context ONLY - do NOT include this in output"
+    )
+    document_context: Optional[str] = dspy.InputField(
+        desc="Full file content for understanding - do NOT include in output",
+        default=None,
+    )
+    documented_code: str = dspy.OutputField(
+        desc="ONLY the `code` input with documentation added. Must contain same code structure."
+    )
+
+
+class CompleteCodeSignature(dspy.Signature):
+    """
+    Complete an incomplete function, class, or code block.
+
+    Guidelines:
+    - Analyze what the code is trying to accomplish
+    - Complete the implementation logically
+    - Follow existing code style and patterns
+    - Only output the completion, not the original code
+    """
+
+    code: str = dspy.InputField(
+        desc="Incomplete code to complete"
+    )
+    language: str = dspy.InputField(
+        desc="Programming language (e.g., python, javascript, rust)"
+    )
+    local_context: str = dspy.InputField(
+        desc="Surrounding code for context"
+    )
+    document_context: Optional[str] = dspy.InputField(
+        desc="Full file content for understanding the codebase",
+        default=None,
+    )
+    completion: str = dspy.OutputField(
+        desc="The code completion (what comes after the input code)"
+    )
+
+
+class AddTypeHintsSignature(dspy.Signature):
+    """
+    Add type annotations to the selected code ONLY.
+
+    CRITICAL: You must ONLY transform the `code` field. Do NOT include any code from `local_context`.
+    The `local_context` is provided ONLY to help you understand types - never include it in output.
+
+    Guidelines:
+    - Add type hints to function parameters and return types
+    - Add type hints to variables where beneficial
+    - Use appropriate types from typing module (List, Dict, Optional, etc.)
+    - Infer types from usage and context
+    - Output must be EXACTLY the `code` input with type hints added - same lines, same structure
+    """
+
+    code: str = dspy.InputField(
+        desc="The EXACT code to transform. Output must contain ONLY this code with type hints added."
+    )
+    language: str = dspy.InputField(
+        desc="Programming language (e.g., python, typescript)"
+    )
+    local_context: str = dspy.InputField(
+        desc="Surrounding code for context ONLY - do NOT include this in output"
+    )
+    document_context: Optional[str] = dspy.InputField(
+        desc="Full file content for understanding types - do NOT include in output",
+        default=None,
+    )
+    typed_code: str = dspy.OutputField(
+        desc="ONLY the `code` input with type annotations added. Must have same structure as input."
+    )
+
+
+class ImproveNamesSignature(dspy.Signature):
+    """
+    Improve variable, function, and class names in the selected code ONLY.
+
+    CRITICAL: You must ONLY transform the `code` field. Do NOT include any code from `local_context`.
+    The `local_context` is provided ONLY to help you understand naming patterns - never include it in output.
+
+    Guidelines:
+    - Make names more descriptive and self-documenting
+    - Follow language naming conventions (snake_case for Python, camelCase for JS, etc.)
+    - Avoid single-letter names except for obvious cases (i, j for loops)
+    - Make the code more readable through better naming
+    - Preserve the code's functionality exactly
+    - Output must be EXACTLY the `code` input with names improved
+    """
+
+    code: str = dspy.InputField(
+        desc="The EXACT code to transform. Output must contain ONLY this code with better names."
+    )
+    language: str = dspy.InputField(
+        desc="Programming language"
+    )
+    local_context: str = dspy.InputField(
+        desc="Surrounding code for context ONLY - do NOT include this in output"
+    )
+    document_context: Optional[str] = dspy.InputField(
+        desc="Full file content for understanding naming patterns - do NOT include in output",
+        default=None,
+    )
+    improved_code: str = dspy.OutputField(
+        desc="ONLY the `code` input with improved names. Must have same structure as input."
+    )
+
+
+class ExplainCodeSignature(dspy.Signature):
+    """
+    Add inline comments to explain the selected code ONLY.
+
+    CRITICAL: You must ONLY transform the `code` field. Do NOT include any code from `local_context`.
+    The `local_context` is provided ONLY to help you understand purpose - never include it in output.
+
+    Guidelines:
+    - Add comments that explain the "why" not just the "what"
+    - Focus on complex or non-obvious logic
+    - Don't over-comment simple, self-explanatory code
+    - Use clear, concise language
+    - Place comments on the line before or on the same line as the code
+    - Output must be EXACTLY the `code` input with comments added
+    """
+
+    code: str = dspy.InputField(
+        desc="The EXACT code to explain. Output must contain ONLY this code with comments added."
+    )
+    language: str = dspy.InputField(
+        desc="Programming language"
+    )
+    local_context: str = dspy.InputField(
+        desc="Surrounding code for context ONLY - do NOT include this in output"
+    )
+    document_context: Optional[str] = dspy.InputField(
+        desc="Full file content for understanding purpose - do NOT include in output",
+        default=None,
+    )
+    explained_code: str = dspy.OutputField(
+        desc="ONLY the `code` input with explanatory comments. Must have same structure as input."
+    )
+
+
+class RefactorCodeSignature(dspy.Signature):
+    """
+    Refactor and simplify the selected code ONLY while preserving its behavior.
+
+    CRITICAL: You must ONLY transform the `code` field. Do NOT include any code from `local_context`.
+    The `local_context` is provided ONLY to help you understand dependencies - never include it in output.
+
+    Guidelines:
+    - Simplify complex logic
+    - Remove redundancy and dead code
+    - Improve readability
+    - Apply best practices and design patterns where appropriate
+    - Preserve the exact functionality
+    - Don't change the API/interface unless clearly beneficial
+    - Output must be EXACTLY the `code` input refactored
+    """
+
+    code: str = dspy.InputField(
+        desc="The EXACT code to refactor. Output must contain ONLY this code refactored."
+    )
+    language: str = dspy.InputField(
+        desc="Programming language"
+    )
+    local_context: str = dspy.InputField(
+        desc="Surrounding code for context ONLY - do NOT include this in output"
+    )
+    document_context: Optional[str] = dspy.InputField(
+        desc="Full file content for understanding dependencies - do NOT include in output",
+        default=None,
+    )
+    refactored_code: str = dspy.OutputField(
+        desc="ONLY the `code` input refactored. Must transform only the input code."
+    )
+
+
+class FormatCodeSignature(dspy.Signature):
+    """
+    Format and prettify the selected code ONLY.
+
+    CRITICAL: You must ONLY format the `code` field. Do NOT include any code from `local_context`.
+    The `local_context` is provided ONLY to understand style conventions - never include it in output.
+
+    Guidelines:
+    - Apply consistent indentation (spaces or tabs based on context)
+    - Add proper line breaks and spacing
+    - Align similar constructs (assignments, parameters, etc.)
+    - Follow language-specific formatting conventions (PEP8 for Python, etc.)
+    - Preserve the exact functionality - only change whitespace and formatting
+    - Output must be EXACTLY the `code` input formatted
+    """
+
+    code: str = dspy.InputField(
+        desc="The EXACT code to format. Output must contain ONLY this code formatted."
+    )
+    language: str = dspy.InputField(
+        desc="Programming language (e.g., python, javascript, rust)"
+    )
+    local_context: str = dspy.InputField(
+        desc="Surrounding code for style context ONLY - do NOT include this in output"
+    )
+    document_context: Optional[str] = dspy.InputField(
+        desc="Full file content for style conventions - do NOT include in output",
+        default=None,
+    )
+    formatted_code: str = dspy.OutputField(
+        desc="ONLY the `code` input formatted. Must have same logic, just better formatting."
+    )
+
+
+class ProgramCodeSignature(dspy.Signature):
+    """
+    Transform pseudo-code or natural language instructions into proper, executable code.
+
+    The input is a mix of English descriptions and code fragments - a shorthand way of
+    expressing programming intent. Your job is to interpret this and produce clean,
+    working code in the target language.
+
+    Guidelines:
+    - Parse the pseudo-code to understand the programmer's intent
+    - Convert English descriptions into actual code constructs
+    - Fill in implied details (variable declarations, imports, error handling)
+    - Follow the conventions and patterns visible in document_context
+    - Match the coding style of surrounding code in local_context
+    - Output must be syntactically correct, runnable code
+    - Preserve any actual code fragments from the input, just clean them up
+
+    Examples of pseudo-code patterns to handle:
+    - "loop through items and print each" -> for item in items: print(item)
+    - "if user exists then return user else throw error" -> proper if/else with exception
+    - "fetch url, parse json, extract 'data' field" -> requests + json parsing code
+    - "class User with name, email, save method" -> full class definition
+    """
+
+    pseudo_code: str = dspy.InputField(
+        desc="The pseudo-code or natural language mixed with code fragments to transform"
+    )
+    language: str = dspy.InputField(
+        desc="Target programming language (e.g., python, javascript, rust)"
+    )
+    local_context: str = dspy.InputField(
+        desc="Surrounding code for style and context - understand patterns but don't include in output"
+    )
+    document_context: Optional[str] = dspy.InputField(
+        desc="Full document/notebook content - use for imports, defined functions, conventions",
+        default=None,
+    )
+    code: str = dspy.OutputField(
+        desc="Clean, executable code that implements the pseudo-code intent"
+    )

mrmd_ai/signatures/correct.py

@@ -0,0 +1,72 @@
+"""Signature definitions for correct-and-finish programs."""
+
+import dspy
+from typing import Optional
+
+
+class CorrectAndFinishLineSignature(dspy.Signature):
+    """
+    You are helping a user in a markdown notebook. Your task is to BOTH correct
+    errors AND complete the current line.
+
+    You will receive:
+    - document_context: The full notebook for understanding context
+    - local_context: The current section/code block
+    - text_to_fix: The current line that may have errors and is incomplete
+    - content_type: Whether this is 'text' or code (e.g., 'python', 'javascript')
+
+    Output the COMPLETE corrected and finished line.
+    First fix any errors, then complete the line naturally.
+    This replaces the entire text_to_fix, so output the full corrected+completed version.
+    """
+
+    document_context: Optional[str] = dspy.InputField(
+        desc="The full notebook/document for understanding context",
+        default=None,
+    )
+    local_context: str = dspy.InputField(
+        desc="The current paragraph or code block for immediate context"
+    )
+    text_to_fix: str = dspy.InputField(
+        desc="The current line with possible errors, incomplete - will be replaced entirely"
+    )
+    content_type: str = dspy.InputField(
+        desc="Type of content: 'text' for prose, or language name like 'python', 'javascript'"
+    )
+    corrected_completion: str = dspy.OutputField(
+        desc="The FULL line - corrected and completed - this replaces text_to_fix entirely"
+    )
+
+
+class CorrectAndFinishSectionSignature(dspy.Signature):
+    """
+    You are helping a user in a markdown notebook. Your task is to BOTH correct
+    errors AND complete the current section (paragraph or code block).
+
+    You will receive:
+    - document_context: The full notebook for understanding context
+    - local_context: The surrounding content
+    - text_to_fix: The current section that may have errors and is incomplete
+    - content_type: Whether this is 'text' or code (e.g., 'python', 'javascript')
+
+    Output the COMPLETE corrected and finished section.
+    First fix any errors, then complete the section naturally.
+    This replaces the entire text_to_fix, so output the full corrected+completed version.
+    """
+
+    document_context: Optional[str] = dspy.InputField(
+        desc="The full notebook/document for understanding context",
+        default=None,
+    )
+    local_context: str = dspy.InputField(
+        desc="The surrounding content for context"
+    )
+    text_to_fix: str = dspy.InputField(
+        desc="The current section with possible errors, incomplete - will be replaced entirely"
+    )
+    content_type: str = dspy.InputField(
+        desc="Type of content: 'text' for prose, or language name like 'python', 'javascript'"
+    )
+    corrected_completion: str = dspy.OutputField(
+        desc="The FULL section - corrected and completed - this replaces text_to_fix entirely"
+    )

mrmd_ai/signatures/document.py

@@ -0,0 +1,57 @@
+"""Signature definitions for document-level AI programs."""
+
+import dspy
+from typing import Optional
+
+
+class DocumentResponseSignature(dspy.Signature):
+    """
+    You are responding to a document prompt in a markdown notebook.
+    The entire document serves as the prompt/context, and you generate a thoughtful response.
+
+    Use cases:
+    - Answer questions posed in the document
+    - Continue a train of thought
+    - Provide analysis or feedback on the content
+    - Generate content based on instructions in the document
+
+    Your response will be appended to a "# AI Response" section at the end of the document.
+    Format your response in markdown. Be thorough but concise.
+    """
+
+    document: str = dspy.InputField(
+        desc="The full document/notebook content serving as the prompt"
+    )
+    response: str = dspy.OutputField(
+        desc="Your response in markdown format - thoughtful, well-structured, and relevant to the document"
+    )
+
+
+class DocumentSummarySignature(dspy.Signature):
+    """
+    Summarize a document concisely while preserving key information.
+    """
+
+    document: str = dspy.InputField(
+        desc="The document to summarize"
+    )
+    summary: str = dspy.OutputField(
+        desc="A concise summary capturing the main points and key information"
+    )
+
+
+class DocumentAnalysisSignature(dspy.Signature):
+    """
+    Analyze a document and provide insights, suggestions, or critique.
+    """
+
+    document: str = dspy.InputField(
+        desc="The document to analyze"
+    )
+    analysis_type: str = dspy.InputField(
+        desc="Type of analysis: 'structure', 'clarity', 'completeness', 'technical', or 'general'",
+        default="general"
+    )
+    analysis: str = dspy.OutputField(
+        desc="Detailed analysis with specific observations and actionable suggestions"
+    )

mrmd_ai/signatures/finish.py

@@ -0,0 +1,134 @@
+"""Signature definitions for finish/completion programs."""
+
+import dspy
+from typing import Optional
+
+
+class FinishSentenceSignature(dspy.Signature):
+    """
+    You are helping a user write in a markdown notebook. Your task is to complete
+    the sentence they are currently typing.
+
+    You will receive:
+    - document_context: The full notebook content for understanding the topic and style
+    - local_context: The current paragraph/section being written
+    - text_before_cursor: The exact text up to where the cursor is (what needs completion)
+
+    Output ONLY the text that should be appended after the cursor.
+    Do NOT repeat any of the text_before_cursor.
+    Complete the sentence naturally, matching the writing style.
+    """
+
+    document_context: Optional[str] = dspy.InputField(
+        desc="The full notebook/document content for understanding context, style, and topic",
+        default=None,
+    )
+    local_context: str = dspy.InputField(
+        desc="The current paragraph or section being written"
+    )
+    text_before_cursor: str = dspy.InputField(
+        desc="The exact text up to the cursor position - this is what you're completing"
+    )
+    completion: str = dspy.OutputField(
+        desc="ONLY the new text to append after the cursor - do not repeat any existing text"
+    )
+
+
+class FinishParagraphSignature(dspy.Signature):
+    """
+    You are helping a user write in a markdown notebook. Your task is to complete
+    the paragraph they are currently writing.
+
+    You will receive:
+    - document_context: The full notebook content for understanding the topic and style
+    - local_context: The current section/cell being written
+    - text_before_cursor: The paragraph text up to the cursor position
+
+    Output ONLY the text that should be appended after the cursor.
+    Do NOT repeat any of the text_before_cursor.
+    Complete the paragraph naturally, bringing the thought to conclusion.
+    """
+
+    document_context: Optional[str] = dspy.InputField(
+        desc="The full notebook/document content for understanding context and topic",
+        default=None,
+    )
+    local_context: str = dspy.InputField(
+        desc="The current section or cell being written"
+    )
+    text_before_cursor: str = dspy.InputField(
+        desc="The paragraph text up to the cursor - this is what you're completing"
+    )
+    completion: str = dspy.OutputField(
+        desc="ONLY the new text to append - complete the paragraph without repeating existing text"
+    )
+
+
+class FinishCodeLineSignature(dspy.Signature):
+    """
+    You are helping a user write code in a markdown notebook. Your task is to complete
+    the current line of code they are typing.
+
+    You will receive:
+    - document_context: The full notebook content (may include other code blocks, explanations)
+    - local_context: The current code block being edited
+    - code_before_cursor: The code in this block up to the cursor position
+    - language: The programming language
+
+    Output ONLY the code to append after the cursor to complete the current line.
+    Do NOT repeat any code from code_before_cursor.
+    Follow the coding style visible in the context.
+    Only complete the current line - stop at the end of the line.
+    """
+
+    document_context: Optional[str] = dspy.InputField(
+        desc="The full notebook content for understanding the project context",
+        default=None,
+    )
+    local_context: str = dspy.InputField(
+        desc="The complete current code block being edited"
+    )
+    code_before_cursor: str = dspy.InputField(
+        desc="The code up to the cursor position - this is what you're completing"
+    )
+    language: str = dspy.InputField(
+        desc="The programming language (python, javascript, etc.)"
+    )
+    completion: str = dspy.OutputField(
+        desc="ONLY the code to append to complete the current line - no repetition, no extra lines"
+    )
+
+
+class FinishCodeSectionSignature(dspy.Signature):
+    """
+    You are helping a user write code in a markdown notebook. Your task is to complete
+    the current code section (function, class, or logical block).
+
+    You will receive:
+    - document_context: The full notebook content (other code blocks, documentation)
+    - local_context: The current code block being edited
+    - code_before_cursor: The code up to the cursor position
+    - language: The programming language
+
+    Output ONLY the code to append after the cursor.
+    Do NOT repeat any code from code_before_cursor.
+    Complete the logical unit (finish the function, close the class, etc.).
+    Follow the coding style and conventions visible in the context.
+    """
+
+    document_context: Optional[str] = dspy.InputField(
+        desc="The full notebook content for understanding the project context",
+        default=None,
+    )
+    local_context: str = dspy.InputField(
+        desc="The complete current code block being edited"
+    )
+    code_before_cursor: str = dspy.InputField(
+        desc="The code up to the cursor - this is what you're completing"
+    )
+    language: str = dspy.InputField(
+        desc="The programming language (python, javascript, etc.)"
+    )
+    completion: str = dspy.OutputField(
+        desc="ONLY the code to append to complete the section - no repetition of existing code"
+    )

mrmd_ai/signatures/fix.py

@@ -0,0 +1,72 @@
+"""Signature definitions for fix/correction programs."""
+
+import dspy
+from typing import Optional
+
+
+class FixGrammarSignature(dspy.Signature):
+    """
+    You are helping a user fix text in a markdown notebook. Your task is to correct
+    grammar, spelling, and punctuation errors in the selected text.
+
+    You will receive:
+    - document_context: The full notebook content for understanding terminology and style
+    - local_context: The current paragraph/section for understanding immediate context
+    - text_to_fix: The exact text that needs fixing (user's selection or current line)
+
+    Output the corrected version of text_to_fix.
+    Make minimal changes - only fix actual errors.
+    Preserve the original meaning, tone, and formatting.
+
+    IMPORTANT: Preserve ALL whitespace including leading/trailing newlines and spaces.
+    The fixed_text must have the exact same whitespace structure as text_to_fix.
+    If text_to_fix starts with newlines, fixed_text must too.
+    If text_to_fix ends with newlines, fixed_text must too.
+    """
+
+    document_context: Optional[str] = dspy.InputField(
+        desc="The full notebook/document for understanding terminology and writing style",
+        default=None,
+    )
+    local_context: str = dspy.InputField(
+        desc="The current paragraph or section for immediate context"
+    )
+    text_to_fix: str = dspy.InputField(
+        desc="The exact text to fix - preserve all whitespace including leading/trailing newlines"
+    )
+    fixed_text: str = dspy.OutputField(
+        desc="The corrected text - MUST preserve exact whitespace structure (leading/trailing newlines and spaces)"
+    )
+
+
+class FixTranscriptionSignature(dspy.Signature):
+    """
+    You are helping a user fix speech-to-text transcription in a markdown notebook.
+    Your task is to correct errors from voice transcription.
+
+    You will receive:
+    - document_context: The full notebook content for understanding the topic and terminology
+    - local_context: The current section for understanding what's being discussed
+    - text_to_fix: The transcribed text that likely contains speech-to-text errors
+
+    Output the corrected transcription.
+    Fix misheard words, add proper punctuation, and fix capitalization.
+    Preserve the speaker's intended meaning.
+
+    IMPORTANT: Preserve ALL whitespace including leading/trailing newlines and spaces.
+    The fixed_text must have the exact same whitespace structure as text_to_fix.
+    """
+
+    document_context: Optional[str] = dspy.InputField(
+        desc="The full notebook/document for understanding topic and terminology",
+        default=None,
+    )
+    local_context: str = dspy.InputField(
+        desc="The current section for understanding what's being discussed"
+    )
+    text_to_fix: str = dspy.InputField(
+        desc="The transcribed text to fix - preserve all whitespace including leading/trailing newlines"
+    )
+    fixed_text: str = dspy.OutputField(
+        desc="The corrected transcription - MUST preserve exact whitespace structure"
+    )

mrmd_ai/signatures/notebook.py

@@ -0,0 +1,37 @@
+"""Signature definitions for notebook-related AI programs."""
+
+import dspy
+
+
+class NotebookNameSignature(dspy.Signature):
+    """
+    Generate a short, descriptive filename for a notebook based on its content.
+
+    The name should:
+    - Be a valid filename (no special characters except hyphens and underscores)
+    - Be lowercase with hyphens between words (kebab-case)
+    - Be concise (2-5 words, max 50 characters)
+    - Capture the essence or main topic of the document
+    - NOT include the .md extension (that will be added separately)
+
+    Examples of good names:
+    - "meeting-notes-q4-planning"
+    - "react-hooks-tutorial"
+    - "api-design-thoughts"
+    - "weekly-standup-dec-15"
+    - "debugging-memory-leak"
+
+    If the content is too short or unclear, suggest a generic but contextual name
+    like "untitled-notes" or "draft-thoughts".
+    """
+
+    document: str = dspy.InputField(
+        desc="The notebook content to analyze for naming"
+    )
+    current_name: str = dspy.InputField(
+        desc="The current filename (may be 'Untitled' or generic)",
+        default="Untitled"
+    )
+    name: str = dspy.OutputField(
+        desc="A short, descriptive kebab-case filename (without .md extension)"
+    )