> ## Documentation Index > Fetch the complete documentation index at: https://docs.magi-mda.org/llms.txt > Use this file to discover all available pages before exploring further. # Specification # MAGI Specification This document provides detailed specifications for the three optional components of MAGI (Markdown for Agent Guidance & Instruction): YAML Front Matter, `ai-script` Code Blocks, and Markdown Footnotes for Relationships. MAGI is designed to be saved in files with the `.mda` extension to clearly signal the presence of enhanced components. While standard Markdown files (`.md`) can contain MAGI elements for backward compatibility, processors optimized for MAGI might prioritize `.mda` files or treat `.md` files as standard Markdown, potentially ignoring `ai-script` blocks or footnote relationships unless explicitly configured to parse them. The MAGI format, represented as a string, is suitable for transmission via REST APIs, either as request payloads (e.g., sending content to be processed) or response bodies (e.g., returning processed or generated content in MAGI format). ## 1. Front Matter Schema Provides structured metadata using YAML syntax, enclosed by `---` delimiters at the very beginning of the `.mda` file. **Fields:** Field names use kebab-case (e.g., `doc-id`, `created-date`). | Field | Type | Description | Example | Required/Optional | Notes | | ---------------- | -------------- | ------------------------------------------------------------------------------------------------------ | ---------------------------------------- | ----------------- | ----------------------------------- | | `doc-id` | `string` | A unique identifier (UUID format recommended) for this document. Crucial for `footnote relationships`. | `"38f5a922-81b2-4f1a-8d8c-3a5be4ea7511"` | Optional | Strongly recommended for linking | | `title` | `string` | The main title of the document. | `"Introduction to MAGI"` | Optional | | | `description` | `string` | A brief summary or abstract of the document's content. | `"Explains the MAGI format."` | Optional | | | `author` | `string` | The primary author's name. | `"Jane Doe"` | Optional | | | `author-id` | `string` | Unique identifier for the author (CUID2 or UUID recommended). | `"usr_abcdef12345"` | Optional | Useful for linking author profiles | | `image` | `string` | URL for a primary cover image associated with the document. | `"https://example.com/cover.jpg"` | Optional | | | `images-list` | `list[string]` | URLs for additional images associated with the document. | `["https://.../img1.jpg"]` | Optional | | | `published-date` | `string` | ISO 8601 timestamp when the document was originally published or made public. | `"2024-01-10T08:00:00Z"` | Optional | | | `tags` | `list[string]` | Keywords or categories for classification and retrieval. | `["markdown", "ai", "rag"]` | Optional | | | `created-date` | `string` | ISO 8601 timestamp (date and time with timezone recommended) when the document was originally created. | `"2024-01-15T09:00:00Z"` | Optional | e.g., `YYYY-MM-DDTHH:mm:ssZ` | | `updated-date` | `string` | ISO 8601 timestamp when the document was last significantly updated. | `"2024-06-01T15:30:00Z"` | Optional | | | `expired-date` | `string` | Optional ISO 8601 timestamp when the content should be considered outdated. | `"2025-01-01T00:00:00Z"` | Optional | | | `globs` | `list[string]` | File or URL patterns this metadata applies to (e.g., `["docs/**/*.md", "*.ts"]`). | `["*.mda", "!legacy/*"]` | Optional | Used for external/meta `.mda` files | | `audience` | `list[string]` | Describes the intended audience(s) (e.g., `["developers", "end-users"]`). | `["Developers"]` | Optional | | | `purpose` | `string` | The primary goal or objective of the document (e.g., "tutorial", "reference"). | `"Reference"` | Optional | | | `entities` | `list[string]` | Key named entities (people, places, organizations, concepts) mentioned. | `["MAGI", "RAG", "LLM"]` | Optional | Useful for RAG filtering/extraction | | `relationships` | `list[string]` | High-level summary of relationships defined in footnotes (human-readable). | `["Extends Markdown"]` | Optional | Primarily for human readers | | `source-url` | `string` | The original URL if the content was sourced or derived from the web. | `"https://example.com/doc"` | Optional | | *Note: While all fields are technically optional for basic `.mda` validity, `doc-id` is essential if using the Footnote relationship feature.* Custom fields are allowed but may be ignored by standard processors. ## 2. AI Script Block (`ai-script`) Embeds instructions for AI processing within standard Markdown fenced code blocks using the `ai-script` language identifier. The content **must** be a single, valid JSON object. Field names within the JSON use kebab-case (e.g., `script-id`, `model-name`). **JSON Fields:** | Field | Type | Description | Example | Required/Optional | Notes | | ------------------------- | --------- | --------------------------------------------------------------------------------------------------------------- | ------------------------------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | `script-id` | `string` | A unique identifier for this specific instruction block within the document. | `"summary-request-001"` | Required | Should be unique within the `.mda` file | | `prompt` | `string` | The actual prompt or command text intended for the LLM or AI agent. | `"Summarize this section."` | Required | | | `priority` | `string` | Helps prioritize execution if multiple instructions exist (e.g., "high", "medium", "low"). | `"medium"` | Optional | Default behavior is application-specific | | `auto-run` | `boolean` | Hint indicating if an automated processing agent should execute this instruction without explicit user trigger. | `true` | Optional | Default is usually `false` | | `provider` | `string` | Suggests the target AI provider (e.g., "openai", "anthropic", "google", "local-llm"). | `"openai"` | Optional | | | `model-name` | `string` | Suggests the target model name (e.g., "gpt-4o", "claude-3-opus-20240229"). | `"gpt-4o"` | Optional | | | `system-prompt` | `string` | Optional system-level instructions or context for the AI model. | `"Act as a helpful assistant."` | Optional | Prepended or handled specially by the runtime | | `parameters` | `object` | A JSON object containing provider-specific parameters (e.g., temperature, max tokens). | `{"temperature": 0.7}` | Optional | Passed directly to the model API | | `retry-times` | `integer` | Optional hint for the maximum number of retry attempts on failure. | `3` | Optional | Runtime should interpret this hint. Default behavior is runtime-specific. | | `runtime-env` | `string` | Suggests the ideal runtime context or endpoint for execution (e.g., "server", "browser", "edge", API URL). | `"server"` | Optional | Hint for the processing system | | `output-format` | `string` | Desired format for the output (e.g., "markdown", "text", "json", "image-url"). | `"markdown"` | Optional | Processor should attempt to conform. Implied "json" if `output-schema` is used. | | `output-schema` | `object` | Optional JSON Schema object defining the expected structure of the output. | `{"type": "object", ...}` | Optional | Strongly implies `output-format: "json"`. Used for structured data extraction. | | `stream` | `boolean` | Optional hint to the runtime to stream the response if possible. | `true` | Optional | Default is `false`. Primarily for text output. | | `interactive-type` | `string` | Type of interactive component to render if `auto-run` is false (e.g., "button", "inputbox"). | `"button"` | Optional | Used for client-side triggered execution. If "inputbox", an input field and submit button (using `interactive-label`) are rendered. | | `interactive-label` | `string` | Label text for the interactive component (e.g., button text, typically for the submit button). | `"Run Summary"` | Optional | Used when `interactive-type` is specified. | | `interactive-placeholder` | `string` | Placeholder text for the input field when `interactive-type` is "inputbox". | `"Enter your query..."` | Optional | Used only when `interactive-type` is "inputbox". | **Processing Hint:** A comment like `` can optionally precede the block to explicitly guide processing systems, but detection should rely on the `ai-script` identifier. **Alternative:** Instructions can also be passed externally (e.g., via API metadata alongside the MAGI content string) for separation of concerns, especially in complex multi-agent systems. ## 3. Footnote Relationships Leverages standard Markdown footnote syntax (`[^ref-id]` and `[^ref-id]: ...`) to define typed relationships between the current document and other resources. The footnote definition **must** contain a single JSON object enclosed in backticks (`` ` ``). **JSON Fields within Footnote Definition:** Field names use kebab-case (e.g., `rel-type`, `doc-id`). | Field | Type | Description | Example | Required/Optional | Notes | | ------------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- | ----------------- | ---------------------------------- | | `rel-type` | `string` (Enum recommended) | Nature of the relationship. Recommended values: `citation`, `parent`, `child`, `related`, `contradicts`, `supports`, `extends`. | `"parent"` | Required | | | `doc-id` | `string` | The unique `doc-id` (from Front Matter) of the target/related `.mda` document. Use *either* `doc-id` or `source-url`. | `"UUID-of-target-document"` | Conditional | Required if not using `source-url` | | `source-url` | `string` | The URL of the target/related external resource. Use *either* `doc-id` or `source-url`. | `"https://example.com/related-article"` | Conditional | Required if not using `doc-id` | | `rel-desc` | `string` | A brief, human-readable description of why the documents/resources are related. | `"Derived from primary SEC documentation"` | Required | | | `rel-strength` | `float` (0.0 to 1.0) | Optional confidence score or relevance strength of the relationship. | `0.8` | Optional | | | `bi-directional` | `boolean` | Optional: Indicates if the relationship implies a reciprocal link back (interpretation depends on processor). | `true` | Optional | Default is usually `false` | | `context` | `object` | Optional: Provides additional structured context about the link's location/nature. | `{"section": "Introduction", "relevance": "High"}` | Optional | | | `context.section` | `string` | Specific section/heading in the source document where the link originates. | `"Introduction"` | Optional | Within `context` object | | `context.relevance` | `string` | Qualitative assessment of relevance (e.g., "High", "Medium", "Low"). | `"High"` | Optional | Within `context` object | **Implementation Notes:** * Ensure the `doc-id` used in footnotes corresponds accurately to a `doc-id` defined in the Front Matter of the target `.mda` document for internal links. * Consistent use of `rel-type` values is crucial for building reliable knowledge graphs. * Standard Markdown parsers will render the footnote with the backticks and JSON string as the literal content. MAGI-aware parsers extract and interpret the JSON.