# Implementation Plan: Enhanced .to_ascii and New .from_ascii for Symbol Graph Serialization

## 1. Introduction
This document outlines the plan to enhance the existing `.to_ascii` method within the `Symbol` class for more comprehensive graph export, and to implement a new `.from_ascii` class method for reconstructing `Symbol` graphs from their ASCII representation. The focus is on providing flexible traversal options for export and robust parsing for import, adhering to the "happy path" for initial implementation.

## 2. Current State Analysis of `.to_ascii`
The current `Symbol.to_ascii()` method delegates to `GraphTraversal.to_ascii()`, which performs a depth-first traversal of the `children` hierarchy only. It does not account for general `relations` or offer configurable traversal strategies (e.g., breadth-first, different family traversal orders).

## 3. Proposed Enhancements to `.to_ascii`

### 3.1. New Parameters for `GraphTraversal.to_ascii`
To provide flexibility, the `GraphTraversal.to_ascii` method will be extended with the following parameters, each with sensible default values:

*   `traverse_mode: Literal["dfs", "bfs"] = "dfs"`: Determines the general graph traversal order (Depth-First Search or Breadth-First Search).
*   `family_mode: Literal["children_first", "parents_first"] = "children_first"`: Specifies the traversal order within the parent-child hierarchy.
*   `graph_mode: Literal["dfs", "bfs"] = "dfs"`: Specifies the traversal order for general relations.

### 3.2. Enhanced Content Export
The ASCII output will be augmented to include:
*   **Family Hierarchy:** Continue to represent the parent-child relationships with indentation.
*   **General Relations:** Clearly indicate relationships defined via `sym.relate(other, how='...')`. This might involve a separate section for relations or inline notation, depending on readability.
*   **Nested Elements:** The traversal logic will ensure that all connected symbols are included, preventing infinite loops by tracking visited nodes. The export will stop traversing a path when it encounters an already exported symbol.

### 3.3. Implementation Details
*   Modify `GraphTraversal.__init__` to accept the new `traverse_mode`, `family_mode`, and `graph_mode` parameters.
*   Refactor `GraphTraversal.traverse` (or create new internal methods) to implement DFS and BFS logic, considering both family and general graph relations.
*   Update `GraphTraversal.to_ascii` to utilize the chosen traversal modes and to format the output to include relation information.
*   Update `Symbol.to_ascii` to accept and pass these new parameters to `GraphTraversal.to_ascii`.

## 4. New Implementation: `.from_ascii`

### 4.1. Class Method Signature
A new class method `Symbol.from_ascii(ascii_string: str) -> 'Symbol'` will be implemented. This method will reconstruct a `Symbol` graph from its ASCII string representation.

### 4.2. Parsing Logic
The parsing process will involve:
*   **Line-by-Line Processing:** Iterate through the ASCII string line by line.
*   **Symbol Identification:** Extract symbol names and determine their hierarchical level (indentation).
*   **Relationship Reconstruction:** Based on the parsed structure, re-establish parent-child relationships and general relations using `Symbol.append()` and `Symbol.relate()`.
*   **Visited Tracking:** Maintain a mapping of symbol names to `Symbol` instances to handle references and avoid creating duplicate symbols.

### 4.3. Happy Path Focus
The initial implementation will focus solely on the "happy path," assuming a well-formed ASCII input generated by the enhanced `.to_ascii` method. Error handling for malformed input will be considered in future iterations.

## 5. Testing Strategy

### 5.1. Unit Tests for `.to_ascii`
*   Create test cases to verify the output of `.to_ascii` for various graph structures (simple trees, graphs with relations, cycles).
*   Test different combinations of `traverse_mode`, `family_mode`, and `graph_mode`.
*   Ensure correct indentation and representation of relations.

### 5.2. Unit Tests for `.from_ascii`
*   Create test cases to verify that `.from_ascii` correctly reconstructs `Symbol` graphs from valid ASCII strings.
*   Test with ASCII strings representing different graph complexities.

### 5.3. Roundtrip Tests
*   Implement tests that perform a roundtrip: `symbol_graph -> to_ascii() -> from_ascii() -> reconstructed_symbol_graph`.
*   Verify that the `reconstructed_symbol_graph` is structurally and relationally equivalent to the original `symbol_graph`.

## 6. Deliverables
*   Modified `symb/core/symb.py` with enhanced `GraphTraversal.to_ascii` and new `Symbol.from_ascii`.
*   Updated test files (e.g., `tests/core/test_symbol.py`) with new test cases.
*   This `docs/plan.md` document.
*   `docs/todo.md` for tracking progress.
