doc/AGDB/5_AGDB_command_logic.md

Overall Command Structure and Unified Syntax

Your approach with commands like create-node, get-node, set-domain, and create-relationship provides an intuitive way to interact with nodes and relationships. Here’s how we can refine the logic for each main command:

• Unified Noun-Verb Syntax: Stick to a base format of verb-object for each action, such as get-node.attribute or set-domain.
• Command Parameter Consistency: Each command should support common parameters like -node_id, -domain, and -attributes so that commands remain consistent and predictable.
• Support for AGDB and AGN Differentiation: Use a switch or metadata property to distinguish between AGDB (structured data storage) and AGN (relationship-based network).

Core Commands and Their Implementation

Let's go through the main commands, refining and validating logic based on what you provided:

1. Graph Commands (create-graph, load-graph, build-graph)

   • Purpose: Initialize, load, and build graph structures from files or in-memory storage.
   • Refinements:
     • create-graph: Set up initial metadata and store it in a JSON schema format if needed.
     • load-graph: Import data from JSON or CSV; use networkx for in-memory representation.
     • build-graph: Construct relationships between nodes based on policies in AGN or AGDB.

2. Node Commands (create-node, get-node, set-attribute)

   • Purpose: Add, retrieve, and modify nodes within the graph.
   • Refinements:
     • create-node: Ensure node_id, node_type, and attributes are set based on input and stored in memory or AGDB.
     • get-node: Retrieve node details, with optional filtering by attribute or domain.
     • set-attribute: Allow attribute updates on nodes with a syntax like set-attribute -node_id node_001 -attribute open:1.15.

3. Relationship Commands (create-relationship, get-relationship, set-edge)

   • Purpose: Define, retrieve, and modify relationships between nodes.
   • Refinements:
     • create-relationship: Define the type of relationship (e.g., temporal, causal) and link nodes.
     • get-relationship: Retrieve relationships with filters for direction and relationship type.
     • set-edge: Adjust properties of an existing edge, such as weight or relationship type.

4. Domain and Policy Commands (set-domain, get-domain, set-AGN, get-AGN)

   • Purpose: Set and retrieve domain-based or policy-based contextual layers within AGN or AGDB.
   • Refinements:
     • set-domain: Assign domains to nodes or graphs to contextualize relationships.
     • get-domain: Retrieve domain data to help understand node contexts.
     • set-AGN: Define relational policies like inference rules, weights, and thresholds.
     • get-AGN: Retrieve policies for nodes, relationships, and other features within AGNs.

---

Detailed Command Logic and Functionality

1. create-node

   • Logic:
     • Check for node_type existence in storage.
     • Create a new node under a category or domain if it does not exist.
     • Store in _node_storage with relevant metadata (type, domain, attributes).
   • Additions:
     • Include metadata and domain properties for better organization.
     • Support for optional initial relationships.

2. get-nodeinfo and get-node

   • Logic:
     • Retrieve node details and allow for filtering by attributes, domain, and relationships.
     • Enable conditional querying (e.g., get-node.attribute).
   • Additions:
     • Support for optional in-depth traversal based on relationships.
     • Integration with networkx to leverage its traversal and neighborhood functionalities.

3. list-hierarchy

   • Logic:
     • Support directional traversal (up or down) for both AGNs and AGDBs.
     • Traverse nodes based on direct relationships, optionally limited by depth.
   • Additions:
     • For time series, build temporal hierarchies and support traversal based on temporal nodes.
     • Include node properties in traversal results for more context.

4. load-graph and build-graph

   • Logic:
     • load-graph imports data and prepares node relationships in a JSON structure.
     • build-graph takes the data and applies relationships, using networkx to build memory-optimized graphs.
   • Additions:
     • Different modes: direct load for networkx, CSV parsing for bulk data import, or in-memory only for smaller graphs.
     • If integrating with networkx, leverage the ability to add edges directly with attributes.

5. update-graphindex

   • Logic:
     • Updates the index based on AGN policies or AGDB schema.
     • Example: If a new node is created in an AGDB, update relationships accordingly.
   • Additions:
     • Implement schema validation and indexing checks to ensure alignment with AGN/AGDB standards.

---

Revised JSON Template for AGDB/AGN Integration

Here's a refined JSON template based on your requirements, adding metadata, domains, and predefined relationships.

{
    "metadata": {
        "title": "Time Series AGDB for Trading",
        "source": "AGT Platform",
        "description": "A time series AGDB with pre-defined temporal and synthetic relationships.",
        "created_at": "2024-11-04",
        "timezone": "UTC"
    },
    "domains": {
        "TradingData": {
            "description": "Domain for financial trading data",
            "nodes": ["TimeSeriesNode", "FeatureNode"],
            "relationships": ["temporal_sequence", "influences"]
        }
    },
    "nodes": [
        {
            "node_id": "node_001",
            "type": "TimeSeriesNode",
            "domain": "TradingData",
            "attributes": {
                "timestamp": "2024-11-04T10:45:00Z",
                "open": 1.12,
                "close": 1.15,
                "high": 1.17,
                "low": 1.10,
                "volume": 50000
            },
            "relationships": {
                "next": "node_002",
                "previous": "node_000",
                "related_features": ["open", "close"]
            }
        }
    ],
    "relationships": [
        {
            "source": "node_001",
            "target": "node_002",
            "type": "temporal_sequence",
            "attributes": {
                "weight": 0.8,
                "policy": "temporal_navigation"
            }
        }
    ],
    "policies": {
        "AGN": {
            "trading_inference": {
                "rules": {
                    "time_series_trend": {
                        "relationship": "temporal_sequence",
                        "weight_threshold": 0.5
                    },
                    "volatility_correlation": {
                        "attributes": ["high", "low"],
                        "relationship": "correlates_with",
                        "weight_threshold": 0.3
                    }
                }
            }
        }
    }
}

---

Next Steps for Code Refactoring

1. Refactor agn_service to Use Command Abstraction

   • Implement command-specific handler functions that call the appropriate service logic (e.g., get_node, set_attribute).

2. Create Command Parser and Routing Logic

   • Create a parser to map incoming commands to the relevant functions (e.g., create-node routes to create_node).

3. Enhance load-graph for Flexibility

   • Support flexible loading mechanisms: direct file load, networkx conversion, and CSV import.

4. Unified Query Handler for Consistency

   • Implement a query_handler that interprets commands and retrieves or manipulates data based on the syntax defined.