Merge v4 to main

.gitattributes

@@ -0,0 +1,25 @@
+# Auto-detect text files and normalize them to LF on checkin.
+# Force LF on checkout for all text files to avoid Windows CRLF issues.
+* text=auto eol=lf
+
+# Explicitly force LF for text files, redundant but explicit
+*.toml text eol=lf
+*.txt text eol=lf
+*.md text eol=lf
+*.rst text eol=lf
+*.py text eol=lf
+*.json text eol=lf
+*.yaml text eol=lf
+*.yml text eol=lf
+*.sh text eol=lf
+
+# Explicitly declare binary files to avoid accidental corruption
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.gif binary
+*.ico binary
+*.pdf binary
+*.sqlite binary
+*.db binary
+*.pyc binary

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,86 @@
+---
+name: Bug report
+about: Report a reproducible bug or unexpected behavior.
+title: "[Bug]: Clear and concise description of the bug"
+labels: bug, needs-triage
+assignees: ''
+
+---
+
+## Bug Description
+
+Clearly and concisely describe the bug you've encountered. What is the unexpected behavior? What did you expect to happen instead?
+
+## Steps to Reproduce
+
+Provide a clear, step-by-step procedure to reproduce the bug. This is crucial for us to understand and fix the issue.
+
+1.  Go to '...'
+2.  Click on '....'
+3.  Scroll down to '....'
+4.  See error '....'
+
+## Code or Configuration Example
+
+If the bug involves code or configuration, please provide a minimal, reproducible example that demonstrates the issue. This should be the smallest amount of code/config necessary to trigger the bug.
+
+```python
+# Example of bug-inducing code (if relevant)
+import my_library
+
+# Setup or initialization
+config = {
+    "setting_a": "value",
+    "setting_b": 123
+}
+processor = my_library.Processor(**config)
+
+# Action that triggers the bug
+try:
+    processor.process_data(invalid_data)
+except Exception as e:
+    print(f"Error: {e}")
+```
+
+## Error Message / Stack Trace
+
+If an error message or stack trace was produced, please include it here. Use code blocks for better readability.
+
+```text
+# Example Error Message/Stack Trace
+Traceback (most recent call last):
+  File "<stdin>", line 7, in <module>
+    processor.process_data(invalid_data)
+  File "/path/to/my_library/processor.py", line 42, in process_data
+    raise ValueError("Invalid data provided")
+ValueError: Invalid data provided
+```
+
+## Screenshots / Videos
+
+If applicable, add screenshots to help explain the problem. You can drag and drop images directly into the issue description.
+
+## Expected Behavior
+
+Describe what you expected to happen when following the reproduction steps.
+
+## Actual Behavior
+
+Describe what actually happened, including any unexpected output or results.
+
+## Environment
+
+Please provide details about your environment. This helps us reproduce the issue.
+
+*   **Operating System:**
+*   **Python Version:**
+*   **Project Version:**
+*   **Relevant Dependencies:** 
+
+## Checklist
+
+*   [ ] I have searched existing issues to ensure this bug hasn't already been reported.
+*   [ ] I have provided clear steps to reproduce the bug.
+*   [ ] I have provided a minimal, reproducible code example (if applicable).
+*   [ ] I have included any relevant error messages or stack traces.
+*   [ ] I have described the expected and actual behavior.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,50 @@
+---
+name: Feature request
+about: Suggest an idea for a new feature or enhancement.
+title: "[Feature]: Concise title for your feature request"
+labels: enhancement, needs-triage
+assignees: ''
+
+---
+
+## Feature Request
+
+Clearly and concisely describe the new feature or enhancement you are requesting.
+
+## Problem Statement
+
+What problem does this new feature or enhancement solve? Why is it needed? Describe the current limitations or pain points that this feature would address.
+
+## Proposed Solution (optional)
+
+Describe your proposed solution or how you envision this feature working. Be as specific as possible. Consider:
+
+*   **User Interface/API Changes:** How would a user interact with this new feature?
+*   **Configuration:** Would new configuration options be needed?
+*   **Examples of Usage:** Provide a hypothetical example of how this feature would be used.
+## Benefits
+
+What are the benefits of implementing this feature? How would it improve the project for users?
+
+*   (e.g., "It would simplify X workflow for users.")
+*   (e.g., "It would enable Y functionality that is currently impossible.")
+*   (e.g., "It would improve performance by Z% in certain scenarios.")
+
+## Alternatives Considered
+
+Have you considered any alternative approaches or workarounds for the problem you're trying to solve? If so, why do you think this feature request is a better solution?
+
+## Additional Context
+
+Add any other context, links, or information about the feature request here. This could include:
+
+*   Similar features in other projects.
+*   Relevant research papers or articles.
+*   Any potential challenges or considerations for implementation.
+
+## Checklist
+
+*   [ ] I have searched existing issues to ensure this feature hasn't already been requested.
+*   [ ] I have clearly described the problem this feature solves.
+*   [ ] I have provided a detailed proposed solution (optional).
+*   [ ] I have explained the benefits of this feature.

.github/ISSUE_TEMPLATE/question.md

@@ -0,0 +1,41 @@
+---
+name: Question
+about: Questions about the usage or working of a feature
+title: "[Question]: Your concise question title here"
+labels: needs-triage, question
+assignees: ''
+
+---
+
+## Question
+Clearly and concisely state your question here. What are you trying to understand or achieve?
+
+## Context
+Provide any relevant background information or context that might help us understand your question better. For example:
+
+*   **What are you trying to do?** (e.g., "I'm trying to integrate X with Y," "I'm trying to achieve Z functionality.")
+*   **Why is this question important to you?** (e.g., "This is blocking my progress on feature A," "I'm trying to decide between two approaches.")
+*   **What steps have you already taken to find an answer?** (e.g., "I've checked the documentation for X," "I've searched existing issues for similar topics," "I've tried searching on Stack Overflow.")
+
+## Details & Examples
+
+If applicable, provide specific details, code snippets, or examples that illustrate your question. This is especially helpful for questions related to:
+
+*   **Usage:** How are you currently trying to use the project?
+*   **Configuration:** What relevant configuration are you using?
+*   **Code:** If your question involves code, please provide a minimal, reproducible example.
+
+## Environment
+
+Please provide details about your environment. This helps us reproduce issues or understand potential incompatibilities.
+
+*   **Operating System:**
+*   **Python Version:**
+*   **Project Version:**
+*   **Relevant Dependencies:**
+
+## Checklist
+
+*   [ ] I have checked the [documentation](https://docs.temoaproject.org/en/latest/) for an answer.
+*   [ ] I have searched existing issues to ensure my question hasn't already been asked.
+*   [ ] I have provided as much detail as possible to help answer my question.

.github/workflows/ci.yml

@@ -0,0 +1,85 @@
+name: CI
+
+on:
+  push:
+    branches:
+      [
+        "main",
+        "temoa_alpha",
+        "ci_testing",
+        "1.0.0-dev-operator",
+        "temoa_davey_code",
+        "unstable",
+      ]
+  pull_request:
+    branches:
+      [
+        "main",
+        "temoa_alpha",
+        "ci_testing",
+        "1.0.0-dev-operator",
+        "temoa_davey_code",
+        "unstable",
+      ]
+
+jobs:
+  test:
+    name: setup and test
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["3.12", "3.13", "3.14"]
+
+    steps:
+      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5.0.1
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6.8.0
+        with:
+          version: "0.9.26"
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+
+      - name: Install the project
+        run: uv sync --locked --all-extras --dev
+
+      - name: Install Graphviz (Ubuntu)
+        if: runner.os == 'Linux'
+        run: sudo apt-get install -y graphviz
+
+      - name: Install Graphviz (macOS)
+        if: runner.os == 'macOS'
+        run: brew install graphviz
+
+      - name: Install Graphviz (Windows)
+        if: runner.os == 'Windows'
+        run: choco install graphviz -y
+
+      - name: Run tests
+        env:
+          CI: 1
+        run: uv run pytest tests
+
+  type-check:
+    name: type check
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12"]
+
+    steps:
+      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5.0.1
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6.8.0
+        with:
+          version: "0.9.26"
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+
+      - name: Install the project
+        run: uv sync --locked --all-extras --dev
+
+      - name: Run mypy
+        run: uv run mypy --config-file=pyproject.toml .