feat(ai): add CASTS and Light Memory components

.github/workflows/ci-py311.yml

@@ -1,29 +1,131 @@
-  name: CASTS Python Tests
-
-  on:
-    pull_request:
-      paths:
-        - "geaflow-ai/plugins/casts/**"
-    push:
-      branches: ["master"]
-      paths:
-        - "geaflow-ai/plugins/casts/**"
-    workflow_dispatch:
-
-  jobs:
-    tests:
-      runs-on: ubuntu-latest
-      defaults:
-        run:
-          working-directory: geaflow-ai/plugins/casts
-      steps:
-        - uses: actions/checkout@v4
-        - uses: actions/setup-python@v5
-          with:
-            python-version: "3.11"
-        - name: Install uv
-          run: pip install uv
-        - name: Sync deps
-          run: uv sync
-        - name: Run tests
-          run: uv run pytest
+################################################################################
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+################################################################################
+
+name: Python CI (uv + 3.11)
+
+on:
+  pull_request:
+    paths:
+      - "geaflow-ai/plugins/casts/**"
+      - "geaflow-ai/plugins/lightmem/**"
+      - ".github/workflows/ci-py311.yml"
+  push:
+    branches: ["master"]
+    paths:
+      - "geaflow-ai/plugins/casts/**"
+      - "geaflow-ai/plugins/lightmem/**"
+      - ".github/workflows/ci-py311.yml"
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event_name }}-${{ github.event.number || github.run_id }}
+  cancel-in-progress: true
+
+jobs:
+  tests:
+    name: ${{ matrix.plugin }} (py${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11"]
+        plugin: ["casts", "lightmem"]
+
+    defaults:
+      run:
+        shell: bash
+        working-directory: geaflow-ai/plugins/${{ matrix.plugin }}
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Setup uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "0.9.17"
+          enable-cache: true
+
+      - name: Sync deps
+        run: |
+          python -m venv .venv
+          uv sync --extra dev --no-editable
+
+      - name: Lint (ruff)
+        run: |
+          uv run --no-editable ruff check .
+
+      - name: Format check (ruff)
+        run: |
+          uv run --no-editable ruff format --check .
+
+      - name: Type check (mypy)
+        run: |
+          if [[ "${{ matrix.plugin }}" == "casts" ]]; then
+            uv run --no-editable mypy -p api -p core -p services -p harness
+          else
+            uv run --no-editable mypy -p lightmem -p api
+          fi
+
+      - name: Run tests
+        run: |
+          uv run --no-editable pytest -q
+
+  smoke:
+    name: smoke-${{ matrix.plugin }} (py${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    needs: tests
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11"]
+        plugin: ["casts", "lightmem"]
+
+    defaults:
+      run:
+        shell: bash
+        working-directory: geaflow-ai/plugins/${{ matrix.plugin }}
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Setup uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "0.9.17"
+          enable-cache: true
+
+      - name: Prepare venv
+        run: |
+          python -m venv .venv
+
+      - name: Smoke test
+        run: |
+          bash ./scripts/smoke.sh

geaflow-ai/plugins/casts/.gitignore

@@ -18,5 +18,5 @@ uv.lock
 .DS_Store
 
 # Data files
-data/real_graph_data/
+harness/data/real_graph_data/
 casts_traversal_path_req_*.png

geaflow-ai/plugins/casts/AGENTS.md

@@ -0,0 +1,71 @@
+# CASTS Agent Instructions (geaflow-ai/plugins/casts)
+
+This file defines CASTS plugin-local instructions for coding agents.
+
+## Must-Read (Before You Change Code)
+
+- Review and follow: `geaflow-ai/plugins/CODE_STYLES.md`
+  - Treat it as the baseline contract for changes under `geaflow-ai/plugins/casts/`.
+  - If you need to break a rule, document the reason in the PR/commit message.
+
+## Repository Layout (What Goes Where)
+
+- `core/`: deterministic cache + decision logic (no network calls required).
+- `services/`: integration code (LLM / embedding / external I/O).
+- `harness/`: offline simulation harness (data + executor + evaluator).
+- `api/`: production-facing decision service (FastAPI).
+  - Endpoint: `POST /casts/decision`
+  - Safety: must degrade conservatively to `decision="stop"` on invalid input or upstream failures.
+- `scripts/`: local developer scripts (e.g., smoke tests).
+- `tests/`: pytest suite.
+
+## Local Dev (Python 3.11 + uv)
+
+We use a per-plugin venv in `.venv/` (gitignored) and a **no-activate** workflow.
+
+One-time setup:
+
+```bash
+cd geaflow-ai/plugins/casts
+[ -d .venv ] || python3.11 -m venv .venv
+uv sync --extra dev
+```
+
+Run tests:
+
+```bash
+cd geaflow-ai/plugins/casts
+uv run pytest -q
+```
+
+Run lint + type checks:
+
+```bash
+cd geaflow-ai/plugins/casts
+uv run ruff format --check .
+uv run ruff check .
+uv run mypy -p api -p core -p services -p harness
+```
+
+## Run The Service (FastAPI)
+
+```bash
+cd geaflow-ai/plugins/casts
+uv sync --extra dev
+uv run uvicorn api.app:app --host 127.0.0.1 --port 5001
+```
+
+One-click smoke:
+
+```bash
+cd geaflow-ai/plugins/casts
+./scripts/smoke.sh
+```
+
+## Safety Defaults
+
+- Never enable evaluating LLM-provided predicates in production:
+  - `LLM_ORACLE_ENABLE_PREDICATE_EVAL` must remain `False` by default.
+- `scope` is a hard boundary:
+  - requests with empty scope must be rejected (or conservatively downgraded).
+  - CASTS service additionally requires `scope.run_id` for cache isolation; if missing, it downgrades to `stop`.