feat: yaml files for llm reasoning

schemas/artifact_schema.yaml

@@ -0,0 +1,102 @@
+# artifact_schema.yaml
+schema_name: trading_code_artifact
+schema_version: v1.1
+description: >
+  Defines the structure for derived knowledge artifacts generated from
+  trading system source code. Artifacts capture factual structure,
+  interpretive intent, invariants, and validated tags for reasoning
+  and retrieval by the AI backend.
+
+required_fields:
+  - source_file
+  - schema_version
+  - factual_summary
+  - tags
+
+optional_fields:
+  - methods
+  - interpretive_summary
+  - invariants
+  - provenance
+
+field_definitions:
+
+  source_file:
+    type: string
+    description: Relative path to the source file in the trading repository.
+    constraints:
+      - non_empty
+      - relative_path
+
+  schema_version:
+    type: string
+    description: Version of the artifact schema used to generate this artifact.
+
+  factual_summary:
+    type: text
+    description: >
+      Objective description of what the file or module does.
+      Focuses on responsibilities and structure, not rationale.
+    constraints:
+      - min_length: 40
+      - max_length: 500
+      - no_interpretive_language
+
+  methods:
+    type: object
+    optional: true
+    description: >
+      Optional method-level descriptions for classes or modules where
+      fine-grained behavioral understanding is useful.
+    method_definition:
+      signature:
+        type: string
+      description:
+        type: text
+        constraints:
+          - no_implementation_details
+          - max_length: 200
+
+  interpretive_summary:
+    type: text
+    optional: true
+    description: >
+      High-level explanation of why the file exists, what architectural
+      role it plays, and what tradeoffs or risks it is designed to manage.
+    constraints:
+      - min_length: 40
+      - max_length: 500
+      - no_code_identifiers
+
+  invariants:
+    type: list
+    optional: true
+    description: >
+      Conditions that must always hold true for correct behavior.
+    item_constraints:
+      - type: string
+      - min_length: 10
+
+  tags:
+    type: object
+    description: >
+      Classification metadata for the artifact. All tag dimensions
+      and values must conform to the backend tag schema.
+    constraints:
+      - validated_against_tag_schema
+
+  provenance:
+    type: object
+    optional: true
+    fields:
+      generated_at:
+        type: datetime
+      generated_by:
+        type: string
+      source_commit:
+        type: string
+      confidence_score:
+        type: float
+        constraints:
+          - min: 0.0
+          - max: 1.0

schemas/tag_schema.yaml

@@ -0,0 +1,60 @@
+# tag_schema.yaml
+schema_version: v1
+
+dimensions:
+  domain:
+    - market_data
+    - signal_generation
+    - strategy_execution
+    - risk_management
+    - order_execution
+    - exchange_integration
+    - pnl_accounting
+
+  trading_function:
+    - data_ingest
+    - alpha_generation
+    - position_sizing
+    - entry_logic
+    - exit_logic
+
+  strategy_layer:
+    - signal
+    - decision
+    - execution
+    - evaluation
+
+  system_layer:
+    - api
+    - service
+    - engine
+    - worker
+    - persistence
+
+  intent:
+    - orchestration
+    - abstraction
+    - isolation
+    - validation
+    - optimization
+    - safety
+
+  data_type:
+    - signals
+    - orders
+    - positions
+    - pnl
+    - configs
+    - exchanges
+
+  risk:
+    - capital_loss
+    - liquidation
+    - latency
+    - data_corruption
+    - security
+    - hedging
+
+  maturity:
+    - experimental
+    - production