Main dev

.github/agents/sage-apps.agent.md

@@ -0,0 +1,31 @@
+______________________________________________________________________
+
+## name: sage-examples description: Agent for SAGE examples/tutorials/apps with runnable minimal changes. argument-hint: Include target folder (`examples`, `tutorials`, or `sage-apps`), goal, and run command. tools: ['vscode', 'execute', 'read', 'agent', 'edit', 'search', 'web', 'todo', 'vscode.mermaid-chat-features/renderMermaidDiagram', 'github.vscode-pull-request-github/issue_fetch', 'github.vscode-pull-request-github/suggest-fix', 'github.vscode-pull-request-github/searchSyntax', 'github.vscode-pull-request-github/doSearch', 'github.vscode-pull-request-github/renderIssues', 'github.vscode-pull-request-github/activePullRequest', 'github.vscode-pull-request-github/openPullRequest', 'ms-azuretools.vscode-containers/containerToolsConfig', 'ms-python.python/getPythonEnvironmentInfo', 'ms-python.python/getPythonExecutableCommand', 'ms-python.python/installPythonPackage', 'ms-python.python/configurePythonEnvironment', 'ms-toolsai.jupyter/configureNotebook', 'ms-toolsai.jupyter/listNotebookPackages', 'ms-toolsai.jupyter/installNotebookPackages', 'ms-vscode.cpp-devtools/Build_CMakeTools', 'ms-vscode.cpp-devtools/RunCtest_CMakeTools', 'ms-vscode.cpp-devtools/ListBuildTargets_CMakeTools', 'ms-vscode.cpp-devtools/ListTests_CMakeTools']
+
+# SAGE Examples Agent
+
+## Scope
+
+- `examples/`, `tutorials/`, `sage-apps/` in `sage-examples` repo.
+
+## Rules
+
+- Flownet-first: no new `ray` imports/dependencies.
+- Keep examples concise and runnable; avoid core-framework refactors here.
+- Do not create new local virtual environments (`venv`/`.venv`); use the existing configured Python
+  environment.
+- In conda environments, use `python -m pip`.
+- Dependency changes must go to repo config files, not one-off install notes.
+
+## Workflow
+
+1. Read nearest README/QUICK_START first.
+1. Implement minimal local change.
+1. Run relevant example/test and update nearby docs if behavior changed.
+
+## Polyrepo coordination rules
+
+- Treat this repository as the only local source tree; do not assume sibling repositories exist.
+- If a task spans multiple repositories, implement only this repo and explicitly list follow-up
+  repo/version-bump actions.
+- Do not create `venv`/`.venv`; always use the existing configured Python environment.

.github/agents/sage-examples.agent.md

@@ -0,0 +1,45 @@
+```chatagent
+______________________________________________________________________
+
+## name: sage-examples description: Agent for SAGE examples, tutorials, and app entrypoints built on consolidated isage. argument-hint: Include target area (`examples`, `tutorials`, or `sage-apps`), goal, and any run/test command. tools: ['vscode', 'execute', 'read', 'agent', 'edit', 'search', 'web', 'todo', 'vscode.mermaid-chat-features/renderMermaidDiagram', 'github.vscode-pull-request-github/issue_fetch', 'github.vscode-pull-request-github/suggest-fix', 'github.vscode-pull-request-github/searchSyntax', 'github.vscode-pull-request-github/doSearch', 'github.vscode-pull-request-github/renderIssues', 'github.vscode-pull-request-github/activePullRequest', 'github.vscode-pull-request-github/openPullRequest', 'ms-azuretools.vscode-containers/containerToolsConfig', 'ms-python.python/getPythonEnvironmentInfo', 'ms-python.python/getPythonExecutableCommand', 'ms-python.python/installPythonPackage', 'ms-python.python/configurePythonEnvironment', 'ms-toolsai.jupyter/configureNotebook', 'ms-toolsai.jupyter/listNotebookPackages', 'ms-toolsai.jupyter/installNotebookPackages', 'ms-vscode.cpp-devtools/Build_CMakeTools', 'ms-vscode.cpp-devtools/RunCtest_CMakeTools', 'ms-vscode.cpp-devtools/ListBuildTargets_CMakeTools', 'ms-vscode.cpp-devtools/ListTests_CMakeTools']
+
+# SAGE Examples Agent
+
+## Scope
+
+- `examples/`, `tutorials/`, and `sage-apps/` in the `sage-examples` repository.
+- Teach and modify examples that depend on the consolidated `isage` core package.
+
+## Core Guidance
+
+- Prefer current `sage.*` surfaces such as `sage.foundation`, `sage.stream`, `sage.runtime`, `sage.serving`, and `sage.cli`.
+- Keep examples stream-first.
+- Treat distributed runtime as optional.
+- Treat `isagellm` and other adapters such as `isage-rag` or `isage-neuromem` as external optional integrations.
+- Do not reintroduce retired split-core package guidance.
+
+## Rules
+
+- Flownet-first: do not add new `ray` imports or dependencies.
+- Keep examples concise, runnable, and local to this repository.
+- Do not create new local virtual environments (`venv`/`.venv`); use the existing configured Python environment.
+- In conda environments, use `python -m pip`.
+- Dependency changes must be declared in repo config files, not as one-off install notes.
+- Fail fast; do not add silent fallback logic that hides missing configuration or imports.
+
+## Workflow
+
+1. Read the nearest `README.md` or `QUICK_START.md` first.
+2. Reuse existing example and tutorial patterns before inventing new structure.
+3. Implement the smallest repo-local change that solves the task.
+4. Run the relevant example, test, or check when practical.
+5. Update nearby docs when behavior or usage changes.
+
+## Polyrepo Coordination Rules
+
+- Treat this repository as an independent examples repository.
+- Do not assume sibling source repositories are available locally.
+- If cross-repo rollout is needed, keep changes here minimal and note any follow-up version bump separately.
+- Do not create `venv`/`.venv`; always reuse the existing configured Python environment.
+
+```

.github/copilot-instructions.md

@@ -0,0 +1,50 @@
+# SAGE Examples Copilot Instructions
+
+## Scope
+
+- Repository: `intellistream/sage-examples` (examples + app entry scripts, not SAGE core).
+- Read docs first: `README.md`, `tutorials/README.md`, `tutorials/QUICK_START.md`,
+  `examples/README.md`.
+
+## Critical rules
+
+- Runtime direction: Flownet-first; do not add new `ray` imports/dependencies.
+- Do not create new local virtual environments (`venv`/`.venv`); use the existing configured Python
+  environment.
+- In conda environments, use `python -m pip` (never plain `pip`).
+- Do not rely on manual install commands for permanent deps; declare in
+  `pyproject.toml`/`requirements.txt`.
+- No silent fallback logic; fail fast with actionable errors.
+- Do not re-add SAGE core internals here; depend on published `isage-*` packages.
+
+## Dependency and setup
+
+- If work depends on SAGE core behavior, ensure SAGE dev env is prepared via
+  `./quickstart.sh --dev --yes` in `SAGE/`.
+- Keep dependency changes explicit and versioned in this repo files.
+
+## Workflow
+
+1. Confirm target area (`examples/`, `tutorials/`, or `sage-apps/`).
+1. Implement minimal repo-local change.
+1. Run relevant tests/linters and update nearby README when behavior changes.
+
+## High-signal paths
+
+- `examples/`, `tutorials/`, `sage-apps/`, `requirements.txt`, `README.md`.
+
+## Polyrepo coordination (mandatory)
+
+- This repository is an independent SAGE sub-repository and is developed/released independently.
+- Do not assume sibling source directories exist locally in `intellistream/SAGE`.
+- For cross-repo rollout, publish this repo/package first, then bump the version pin in
+  `SAGE/packages/sage/pyproject.toml` when applicable.
+- Do not add local editable installs of other SAGE sub-packages in setup scripts or docs.
+
+## 🚫 NEVER_CREATE_DOT_VENV_MANDATORY
+
+- 永远不要创建 `.venv` 或 `venv`（无任何例外）。
+- NEVER create `.venv`/`venv` in this repository under any circumstance.
+- 必须复用当前已配置的非-venv Python 环境（如现有 conda 环境）。
+- If any script/task suggests creating a virtualenv, skip that step and continue with the existing
+  environment.

.github/workflows/quality.yml

@@ -0,0 +1,115 @@
+name: Code Quality Checks
+
+on:
+  push:
+    branches: [main, main-dev]
+  pull_request:
+    branches: [main, main-dev]
+  workflow_dispatch:
+
+jobs:
+  pre-commit:
+    name: Pre-commit Hooks
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.11'
+
+    - name: Install pre-commit
+      run: |
+        pip install pre-commit
+
+    - name: Run pre-commit
+      run: |
+        pre-commit run --all-files --show-diff-on-failure
+
+  ruff:
+    name: Ruff Linting
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.11'
+
+    - name: Install ruff
+      run: |
+        pip install ruff==0.14.6
+
+    - name: Run ruff check
+      run: |
+        ruff check .
+
+    - name: Run ruff format check
+      run: |
+        ruff format --check .
+
+  mypy:
+    name: Type Checking (mypy)
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.11'
+
+    - name: Install dependencies
+      run: |
+        pip install -e ".[dev]"
+
+    - name: Run mypy
+      run: |
+        mypy . --config-file=pyproject.toml --no-error-summary
+      continue-on-error: true    # Type checking errors shouldn't block CI
+
+  legacy-ray-guard:
+    name: Legacy Ray Term Guard
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.11'
+
+    - name: Check for legacy Ray terms in source
+        # Fail fast if any new direct Ray imports or identifiers sneak in.
+        # All distributed-execution work must go via sageFlownet / SAGE facade APIs.
+      run: |
+        python - << 'EOF'
+        import re, sys
+        from pathlib import Path
+        FORBIDDEN = {
+            "import ray":         re.compile(r"\bimport\s+ray\b"),
+            "from ray":           re.compile(r"\bfrom\s+ray\b"),
+            "ray.init()":         re.compile(r"\bray\.init\s*\("),
+            "ray.remote":         re.compile(r"\bray\.remote\b"),
+            "RayQueueDescriptor": re.compile(r"\bRayQueueDescriptor\b"),
+            "RayServiceTask":     re.compile(r"\bRayServiceTask\b"),
+            "use_ray=True":       re.compile(r"\buse_ray\s*=\s*True\b"),
+        }
+        violations = []
+        for path in Path(".").rglob("*.py"):
+            rel = path.relative_to(".")
+            if any(p.startswith(".") for p in rel.parts) or "__pycache__" in rel.parts:
+                continue
+            text = path.read_text(encoding="utf-8")
+            for term, pat in FORBIDDEN.items():
+                for m in pat.finditer(text):
+                    ln = text.count("\n", 0, m.start()) + 1
+                    violations.append(f"{rel}:{ln}: {term}")
+        if violations:
+            print("ERROR: Legacy Ray terms found (use sageFlownet / SAGE facade APIs instead):")
+            print("\n".join(sorted(violations)))
+            sys.exit(1)
+        print("OK: no legacy Ray terms found")
+        EOF

.github/workflows/tests.yml

@@ -0,0 +1,89 @@
+name: Tests
+
+on:
+  push:
+    branches: [main, main-dev]
+  pull_request:
+    branches: [main, main-dev]
+  workflow_dispatch:
+
+jobs:
+  test-examples:
+    name: Test Examples
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.10', '3.11']
+    env:
+      # Skip tests requiring network/external services in CI
+      SAGE_EXAMPLES_MODE: test
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+
+    - name: Install dependencies
+      run: |
+        pip install --upgrade pip
+        pip install -e ".[dev]"
+
+    - name: Install examples dependencies
+      run: |
+        pip install -e .
+
+    - name: Run example tests
+      run: |
+        pytest examples/test_apps.py -v --tb=short
+      continue-on-error: true
+
+  test-sage-apps-package:
+    name: Test sage-apps Package
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.11'
+
+    - name: Install sage-apps package
+      run: |
+        pip install -e "./apps[dev]"
+
+    - name: Run sage-apps tests
+      run: |
+        pytest apps/tests/ -v --tb=short --cov=apps/src/sage/apps --cov-report=term-missing
+      continue-on-error: true
+
+  test-coverage:
+    name: Coverage Report
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.11'
+
+    - name: Install dependencies
+      run: |
+        pip install --upgrade pip
+        pip install -e ".[dev]"
+
+    - name: Run tests with coverage
+      run: |
+        pytest tutorials/ apps/test_apps.py --cov=. --cov-report=xml --cov-report=term-missing
+      continue-on-error: true
+
+    - name: Upload coverage to Codecov
+      uses: codecov/codecov-action@v4
+      with:
+        file: ./coverage.xml
+        flags: unittests
+        name: codecov-umbrella
+      continue-on-error: true