diff --git a/docs/algorithm.yaml b/docs/algorithm.yaml new file mode 100644 index 0000000..5244896 --- /dev/null +++ b/docs/algorithm.yaml @@ -0,0 +1,89 @@ +Pipeline Algorithm: + Basic CRUD Operations: + Create: + 1. The frontend: + - Opens the Prompt Registry pane + - Validates the payload before sending it to the server + - Sends a POST request to the backend + 2. The backend: + - receives the request + - Validates the payload + - Stores the record in the database + - Sends a response to the frontend + 3. The frontend: + - Receives the response from the backend + - Notifies the user of succes or failure + Read: + 1. The frontend: + - Opens the Prompt Registry pane + - Sends a GET request to the backend, requesting data + 2. The backend: + - Receives the request + - Validates the payload + - Fetches the record from the database + - Sends a response to the frontend + 3. The frontend: + - Receives the response from the backend + - Hydrates the Promp Registry + Update: + 1. The frontend: + - Opens the Prompt Registry pane + - Makes local changes to an existing record + - Validates the payload before sending it to the server + - Sends an UPDATE request to the backend + 2. The backend: + - Receives the request + - Validates the payload + - Updates the record in the database + - Sends a response to the frontend + 3. The frontend: + - Receives the response from the backend + - Notifies the user of success or failure + Delete: + 1. The frontend: + - Opens the Prompt Registry pane + - Locates an existing record + - Validates the payload before sending it to the server + - Sends a DELETE request to the backend + 2. The backend: + - Receives the request + - Validates the payload + - Deletes the record from the database + - Sends a response to the frontend + 3. The frontend: + - Receives the response from the backend + - Notifies the user of success or failure + Compiler Job: + 1. Frontend Initialization: + - Opens the compiler configuration pane and establishes settings. + - Opens the terminal and selects the target script. + - Validates the payload data structure. + 2. Job Dispatch: + - Frontend transmits the payload to the server via HTTP POST. + - Server receives and validates the incoming payload. + - Server responds with a unique Job ID and begins asynchronous execution. + - Frontend subscribes to the task by initiating a polling loop (HTTP GET) using the Job ID. + 3. Native Compilation: + - Server passes the validated payload to the C++ compiler via Pybind11. + - Compiler executes the pipeline and saves output artifacts to disk. + - Compiler returns the execution manifest back across the Pybind11 boundary. + 4. State Synchronization: + - Backend receives the manifest and persists it to the database. + - Frontend polling loop detects the job status transition from "building" to "success". + - Frontend issues a final GET request to fetch the manifest and hydrate the interface. + Neural Request: + 1. Frontend Initialization: + - Opens the prompt dashboard. + - Selects a designated PromptPair and target Python script. + - Validates the payload data structure. + 2. Backend Dispatch: + - Frontend transmits the payload to the server via HTTP POST. + - Backend receives and validates the incoming request. + - Backend persists the initial payload state in the database. + 3. LLM Execution & Persistence: + - Backend routes the payload to the designated local LLM server via HTTP POST. + - LLM server processes the prompt and returns the generated inference. + - Backend receives the inference result and updates the database record. + 4. State Synchronization: + - Backend returns the final inference response to the frontend + - Frontend renders the comparative results within the dual-pane Inference Window. diff --git a/docs/testing_plans.yaml b/docs/testing_plans.yaml new file mode 100644 index 0000000..3dc8915 --- /dev/null +++ b/docs/testing_plans.yaml @@ -0,0 +1,63 @@ +Testing Plan: + 1. C++ Pybindings Validation (GTest & Pytest): + Test Cases: + test_safe_assign_binding_integrity: Pass Boolean, Integer, and Enum string types from Python dictionaries into C++ hexa::RunConfig via Pybind11. + TestManifestBridge: Validate C++ hexa::CompilationResult properties correctly reflect into Python ManifestModel schema. + ConfigSafetyTest.HandlesMalformedJSONInjection: Inject deeply nested or malformed JSON payloads into RunConfig::from_json. + Expected Outcomes: + - C++ layer extracts Python variables without segmentation faults. + - Type mismatches or overflows trigger controlled fallbacks or raise caught std::invalid_argument exceptions passed back to Python. Manifest generation strictly enforces mandatory fields. + Verification Methods: + - Pytest assertions on data type mapping (isinstance). + - GTest EXPECT_NO_THROW and EXPECT_EQ ensuring safe fallback values (e.g., SEEDLESS_VALUE). + 2. Class Object Integrity (C++, Python, TypeScript): + Test Cases: + C++ Core: + OptimizerLogicTest for dead code elimination and constant foldingLinearizerTest + - LinearizerTest for nested math AST translationVMTest + - VMTest for memory bound checks (HighRegisterPressure), loop termination, and stack underflow logic. + Python Backend: TestOracle and HexaASTSerializer for validating accurate translation of native Python ast nodes to JSON. + TypeScript Frontend: + - BaseCRUD memento pattern tests (isDirty flag logic). + - BaseLibrary collection hydration. + Expected Outcomes: + - Optimizer reduces AST complexity without altering deterministic output. + - VM halts predictably on stack underflow or type mismatch (ThrowsOnTypeMismatch). + - TS models track local state mutations and revert cleanly. + Verification Methods: + - GTest executing bytecode and validating literal extraction (get_double). + - Pytest validating dictionary structure of serialized AST. + - Vitest verifying Svelte $state reactivity and dirty flags. + 3. Backend Endpoint & Pydantic Structure Validation: + Test Cases: + TestCompilerConfigDynamicOrchestration: Verify FastAPI endpoint schema matches the dynamically generated C++ SchemaBuilder payload. + test_dispatch_pipeline_success: Post CommandPayload to /api/dispatch triggering database entry and background worker queue. + TestCompileJobOrchestration: Validate DB integrity and cascading foreign keys across AST, CompilerConfig, and CompileJob. + Expected Outcomes: + - API endpoints correctly enforce BatchConfig and CommandPayload Pydantic contracts. + - Missing required fields yield 422 Unprocessable Entity. + - Authorized requests insert SQLite records and spawn multiprocessing tasks successfully. + Verification Methods: + - Pytest TestClient executing HTTP requests. + - SQLAlchemy inspect(CompilerConfig) asserting exact column parity with C++ configuration definitions. + 4. Frontend Data Dispatch Accuracy: + Test Cases: + BaseCRUD.Validation: Pass invalid/incomplete forms into TS model before dispatch. + getValidPayload: Verify stripping of UI-only properties (e.g., isEditing) before network transmission. + Expected Outcomes: + - Zod schemas intercept malformed data client-side, throwing ValidationError and halting fetch. + - Generated payloads strictly match the backend's expected JSON format. + Verification Methods: + - Vitest expect(() => getValidPayload(true)).toThrow(). Spying on internal apiFetch calls to assert the shape of the intercepted HTTP body. + 5. End-to-End API Integration & Telemetry Synchronization: + Test Cases: + runIntegrationSuite: Execute chained sequence creating ResearchTier -> LLMServer -> Prompt LLMModel -> PromptConfig. + FullChainTest: Inject Python AST payload, execute compiler pass, and await trace result. + Expected Outcomes: + - System maintains state synchronization across the network boundary. + - C++ execution yields physical .hex and .meta.json files. + - Database accurately links execution Manifest to the original CompileJob. + - WebSocket/Polling loops hydrate the UI RegisterGrid and ASTViewer with zero data mutation. + Verification Methods: + - Vitest polling tests resolving simulated backend responses. + - GTest fs::exists verifying absolute file paths of generated artifacts in the scoped temporary workspace.