Merge pull request #800 from AlphaSphereDotAI/hf

.deepsource.toml

@@ -0,0 +1,22 @@
+version = 1
+
+[[analyzers]]
+  name = "shell"
+
+[[analyzers]]
+  dependency_file_paths = ["pyproject.toml"]
+  name = "python"
+
+  [analyzers.meta]
+    additional_builtins = ["_", "pretty_output"]
+    runtime_version = "3.x.x"
+    type_checker = "mypy"
+
+[[analyzers]]
+  name = "docker"
+
+[[analyzers]]
+  name = "secrets"
+
+[[transformers]]
+  name = "ruff"

.dockerignore

@@ -0,0 +1,9 @@
+**/__pycache__/
+.deepsource.toml
+.env
+.github/
+.idea/
+.mypy_cache/
+.ruff_cache/
+.venv/
+.vscode/

.envrc

@@ -0,0 +1,6 @@
+export MODEL__URL=${MODEL__URL:-https://generativelanguage.googleapis.com/v1beta/openai}
+export MODEL__NAME=${MODEL__NAME:-gemini-2.5-flash}
+export MODEL__API_KEY=${GOOGLE_API_KEY}
+export VECTOR_DATABASE__URL=http://localhost:6333
+export VECTOR_DATABASE__NAME=main
+export CHARACTER__NAME=Napoleon

.gitattributes

@@ -1,35 +1,4 @@
-*.7z filter=lfs diff=lfs merge=lfs -text
-*.arrow filter=lfs diff=lfs merge=lfs -text
-*.bin filter=lfs diff=lfs merge=lfs -text
-*.bz2 filter=lfs diff=lfs merge=lfs -text
-*.ckpt filter=lfs diff=lfs merge=lfs -text
-*.ftz filter=lfs diff=lfs merge=lfs -text
-*.gz filter=lfs diff=lfs merge=lfs -text
-*.h5 filter=lfs diff=lfs merge=lfs -text
-*.joblib filter=lfs diff=lfs merge=lfs -text
-*.lfs.* filter=lfs diff=lfs merge=lfs -text
-*.mlmodel filter=lfs diff=lfs merge=lfs -text
-*.model filter=lfs diff=lfs merge=lfs -text
-*.msgpack filter=lfs diff=lfs merge=lfs -text
-*.npy filter=lfs diff=lfs merge=lfs -text
-*.npz filter=lfs diff=lfs merge=lfs -text
-*.onnx filter=lfs diff=lfs merge=lfs -text
-*.ot filter=lfs diff=lfs merge=lfs -text
-*.parquet filter=lfs diff=lfs merge=lfs -text
-*.pb filter=lfs diff=lfs merge=lfs -text
-*.pickle filter=lfs diff=lfs merge=lfs -text
-*.pkl filter=lfs diff=lfs merge=lfs -text
-*.pt filter=lfs diff=lfs merge=lfs -text
-*.pth filter=lfs diff=lfs merge=lfs -text
-*.rar filter=lfs diff=lfs merge=lfs -text
-*.safetensors filter=lfs diff=lfs merge=lfs -text
-saved_model/**/* filter=lfs diff=lfs merge=lfs -text
-*.tar.* filter=lfs diff=lfs merge=lfs -text
-*.tar filter=lfs diff=lfs merge=lfs -text
-*.tflite filter=lfs diff=lfs merge=lfs -text
-*.tgz filter=lfs diff=lfs merge=lfs -text
-*.wasm filter=lfs diff=lfs merge=lfs -text
-*.xz filter=lfs diff=lfs merge=lfs -text
-*.zip filter=lfs diff=lfs merge=lfs -text
-*.zst filter=lfs diff=lfs merge=lfs -text
-*tfevents* filter=lfs diff=lfs merge=lfs -text
+* text=auto eol=lf
+*.jpg filter=lfs diff=lfs merge=lfs -text
+*.png filter=lfs diff=lfs merge=lfs -text
+*.jpeg filter=lfs diff=lfs merge=lfs -text

.github/lint/.hadolint.yaml

@@ -0,0 +1,6 @@
+trustedRegistries:
+  - docker.io
+  - ghcr.io
+  - cgr.dev
+ignored:
+  - DL3018

.github/lint/.ls-lint.yaml

@@ -0,0 +1,8 @@
+ls:
+  .py: snake_case
+  .yaml: snake_case | kebab-case
+  .yml: snake_case | kebab-case
+  .toml: snake_case
+  .md: SCREAMING_SNAKE_CASE
+ignore:
+  - .git

.github/lint/.markdownlint.yaml

@@ -0,0 +1,3 @@
+$schema: https://raw.githubusercontent.com/DavidAnson/markdownlint/main/schema/markdownlint-config-schema-strict.json
+line-length:
+  tables: false

.github/lint/.ruff.toml

@@ -0,0 +1,24 @@
+indent-width = 4
+line-length = 88
+target-version = "py313"
+
+[lint]
+  dummy-variable-rgx = "^(_+|(_+[a-zA-Z0-9_]*[a-zA-Z0-9]+?))$"
+  fixable = ["ALL"]
+  ignore = ["D100", "D105", "D107", "D212", "D413", "SIM117"]
+  select = ["ALL"]
+  unfixable = []
+
+  [lint.isort]
+    combine-as-imports = true
+
+  [lint.per-file-ignores]
+    "test_app.py" = ["INP001", "S101"]
+
+[format]
+  docstring-code-format = false
+  docstring-code-line-length = "dynamic"
+  indent-style = "space"
+  line-ending = "lf"
+  quote-style = "double"
+  skip-magic-trailing-comma = false

.github/lint/.taplo.toml

@@ -0,0 +1,7 @@
+exclude = [".venv/**"]
+[formatting]
+  indent_entries = true
+  indent_tables = true
+  reorder_arrays = true
+  reorder_inline_tables = true
+  reorder_keys = true

.github/lint/.trivy.yaml

@@ -0,0 +1 @@
+ignorefile: .github/lint/.trivyignore.yaml

.github/lint/.trivyignore.yaml

@@ -0,0 +1,2 @@
+misconfigurations:
+  - id: AVD-DS-0026

.github/lint/.yamlfix.toml

@@ -0,0 +1,3 @@
+comments_min_spaces_from_content = 1
+explicit_start = false
+sequence_style = 'block_style'

.github/lint/.yamllint.yaml

@@ -0,0 +1,28 @@
+extends: default
+rules:
+  braces:
+    level: warning
+    max-spaces-inside: 1
+  brackets:
+    level: warning
+    max-spaces-inside: 1
+  colons:
+    level: warning
+  commas:
+    level: warning
+  comments: disable
+  comments-indentation: disable
+  document-start: disable
+  empty-lines:
+    level: warning
+  hyphens:
+    level: warning
+  indentation:
+    level: warning
+    indent-sequences: consistent
+  line-length:
+    level: warning
+    allow-non-breakable-inline-mappings: true
+    max: 140
+  truthy: disable
+  key-duplicates: enable

.github/mergify.yml

@@ -0,0 +1,127 @@
+pull_request_rules:
+  - name: Automatically queue pre-commit Updates
+    conditions:
+      - files ~= .pre-commit-config.yaml
+      - author = renovate[bot]
+    actions:
+      queue:
+      label:
+        add:
+          - pre-commit
+  - name: Automatically queue Dockerfile Updates
+    conditions:
+      - files ~= Dockerfile
+      - author = renovate[bot]
+      - check-success = Test Image / API Test
+    actions:
+      queue:
+  - name: Automatically label Dockerfile Updates
+    conditions:
+      - files ~= Dockerfile
+      - author = renovate[bot]
+    actions:
+      label:
+        add:
+          - docker
+  - name: Automatically queue Github Actions Updates
+    conditions:
+      - files ~= ^.github/workflows
+      - author = renovate[bot]
+    actions:
+      queue:
+      label:
+        add:
+          - github-actions
+  - name: Automatically queue valid Python Dependency Updates
+    conditions:
+      - files ~= ^(uv.lock|pyproject.toml)$
+      - author = renovate[bot]
+      - and:
+          - check-success = Check Dependency Compatibility
+          - check-success = Test Image / API Test
+    actions:
+      queue:
+  - name: Automatically label Python Dependency Updates
+    conditions:
+      - files ~= ^(uv.lock|pyproject.toml)$
+      - author = renovate[bot]
+    actions:
+      label:
+        add:
+          - uv
+          - python
+          - dependencies
+  - name: Automatically queue Docker Compose Updates
+    conditions:
+      - files ~= ^(docker-compose-dev.yaml|docker-compose.yaml)$
+      - author = renovate[bot]
+    actions:
+      queue:
+      label:
+        add:
+          - docker-compose
+  - name: Merge pull request when the configuration of Mergify is valid
+    conditions:
+      - author = MH0386
+      - 'title = ci(Mergify): configuration update'
+      - head = mergify/MH0386/config-update
+    actions:
+      merge:
+  - name: Comment when a pull request is merged
+    conditions:
+      - merged
+    actions:
+      delete_head_branch:
+      comment:
+        message: >-
+          Thank you for your contribution @{{author}}! Your pull request has been
+          merged.
+  - name: Comment if there is a conflict
+    conditions:
+      - conflict
+    actions:
+      comment:
+        message: Hi @{{author}}, Your PR is in conflict and cannot be merged.
+      label:
+        add:
+          - conflict
+  - name: Automatic update of the pull requests
+    conditions:
+      - -merged
+    actions:
+      update:
+  - name: Add a queue label when PR is queued
+    conditions:
+      - queue-position > 0
+    actions:
+      label:
+        toggle:
+          - merge-queued
+  - name: Notify when a PR is removed from the queue
+    conditions:
+      - queue-dequeue-reason != none
+      - queue-dequeue-reason != pr-merged
+    actions:
+      comment:
+        message: >-
+          Hey @{{author}}, your pull request has been dequeued due to the following
+          reason: {{queue_dequeue_reason}}.
+          Sorry about that, but you can requeue the PR by using `@mergifyio requeue`
+          if you think this was a mistake.
+queue_rules:
+  - name: default
+    update_method: merge
+    allow_queue_branch_edit: true
+    queue_branch_merge_method: fast-forward
+    queue_conditions:
+      - and:
+          - 'check-success = DeepSource: Secrets'
+          - 'check-success = DeepSource: Python'
+          - 'check-success = DeepSource: pyproject.toml'
+          - 'check-success = DeepSource: Docker'
+          - check-success = CodeFactor
+          - check-success = GitGuardian Security Checks
+          - check-success = SonarCloud
+          - check-success = CodeQL
+          - check-success = Lint / UV Lock Check
+          - check-success = Lint / TruffleHog

.github/renovate.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
+  "dependencyDashboardOSVVulnerabilitySummary": "all",
+  "extends": [
+    "config:best-practices"
+  ],
+  "lockFileMaintenance": {
+    "enabled": true
+  },
+  "osvVulnerabilityAlerts": true,
+  "packageRules": [
+    {
+      "matchManagers": [
+        "pep621"
+      ],
+      "matchPackageNames": [
+        "*"
+      ],
+      "rangeStrategy": "bump"
+    }
+  ],
+  "pre-commit": {
+    "enabled": true
+  }
+}

.github/workflows/.docker.yaml

@@ -0,0 +1,306 @@
+name: Docker Image
+on:
+  workflow_call:
+    inputs:
+      is_test:
+        type: boolean
+        required: true
+        description: Test Mode
+      registry:
+        type: string
+        required: true
+        description: Registry
+      install_source:
+        type: string
+        required: true
+        description: Source to install from (e.g., PyPI Package or Git source)
+permissions:
+  contents: read
+  packages: write
+  attestations: write
+  id-token: write
+  actions: read
+  security-events: write
+jobs:
+  check_dockerfile:
+    name: Check Dockerfile
+    runs-on: ubuntu-latest
+    if: ${{ inputs.is_test }}
+    environment:
+      name: code_quality
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - name: Check Dockerfile
+        uses: docker/build-push-action@263435318d21b8e681c14492fe198d362a7d2c83 # v6.18.0
+        id: dockerfile_lint
+        with:
+          call: check
+      - name: Job Summary
+        uses: jazanne/job-summary-action@690eb386a0b86fe4da7c6f0e543e61330ff09f06 # v1.0.0
+        if: success() || failure()
+        with:
+          summary: |
+            ## Dockerfile Check
+            - **Status**: ${{ steps.dockerfile_lint.outcome == 'success' && ':white_check_mark:' || ':x:' }}
+  build_image:
+    name: Build and push Docker image to ${{ inputs.registry }}
+    needs: check_dockerfile
+    if: ${{ always() && !cancelled() && !failure() }}
+    runs-on: ubuntu-latest
+    outputs:
+      image_tag: ${{ steps.tag.outputs.TAG }}
+    environment:
+      name: docker_image
+      url: ${{inputs.registry}}/${{github.repository}}
+    steps:
+      - name: Free Disk Space
+        uses: endersonmenezes/free-disk-space@e6ed9b02e683a3b55ed0252f1ee469ce3b39a885 # v3.1.0
+        with:
+          remove_android: true
+          remove_dotnet: true
+          remove_haskell: true
+          remove_tool_cache: true
+          remove_swap: true
+          remove_packages_one_command: true
+          rm_cmd: rmz
+          remove_folders: >-
+            /usr/share /usr/local/lib  /usr/local/share
+            /usr/local
+      - name: Checkout repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - name: Get Python version from pyproject.toml
+        id: get_python_version
+        uses: mikefarah/yq@065b200af9851db0d5132f50bc10b1406ea5c0a8 # v4.50.1
+        with:
+          cmd: yq -roy '.project.requires-python' pyproject.toml
+      - name: Log in to ${{ inputs.registry }} Registry
+        uses: docker/login-action@c94ce9fb468520275223c153574b00df6fe4bcc9 # v3.7.0
+        with:
+          registry: ${{ inputs.registry }}
+          username: mh0386
+          password: ${{ inputs.registry == 'ghcr.io' && secrets.GH_TOKEN || inputs.registry == 'docker.io' && secrets.TOKEN_KEY_DOCKER }}
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@c7c53464625b32c7a7e944ae62b3e17d2b600130 # v3.7.0
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@8d2750c68a42422c14e847fe6c8ac0403b4cbd6f # v3.12.0
+      - name: Docker meta
+        id: meta
+        uses: docker/metadata-action@c299e40c65443455700f0fdfc63efafe5b349051 # v5.10.0
+        with:
+          images: ${{ inputs.registry }}/${{ github.repository }}
+          tags: |
+            type=raw,value=latest,enable=${{ github.event_name == 'push' && contains(github.ref, 'refs/tags/') }}
+            type=ref,event=pr,prefix={{sha}}-pr-
+            type=ref,event=tag
+            type=ref,event=branch
+      - name: Build and Push to ${{ inputs.registry }}
+        uses: docker/build-push-action@263435318d21b8e681c14492fe198d362a7d2c83 # v6.18.0
+        id: push
+        with:
+          push: true
+          sbom: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          annotations: ${{ steps.meta.outputs.annotations }}
+          build-args: |
+            INSTALL_SOURCE=${{ inputs.install_source }}
+            PYTHON_VERSION=${{ steps.get_python_version.outputs.result }}
+        env:
+          DOCKER_CONTENT_TRUST: '1'
+      - name: Generate artifact attestation
+        uses: actions/attest-build-provenance@96278af6caaf10aea03fd8d33a09a777ca52d62f # v3.2.0
+        if: ${{ inputs.is_test == false }}
+        with:
+          subject-name: ${{ inputs.registry == 'docker.io' && 'index.docker.io' || inputs.registry }}/${{github.repository}}
+          subject-digest: ${{ steps.push.outputs.digest }}
+          push-to-registry: true
+      - name: Update Docker Hub Description
+        if: ${{ inputs.registry == 'docker.io' }}
+        uses: peter-evans/dockerhub-description@1b9a80c056b620d92cedb9d9b5a223409c68ddfa # v5.0.0
+        with:
+          username: mh0386
+          password: ${{ secrets.TOKEN_KEY_DOCKER }}
+          repository: ${{ github.repository }}
+          short-description: ${{ github.event.repository.description }}
+          enable-url-completion: true
+      - name: Export tag for Testing and Scanning
+        id: tag
+        run: echo "TAG=$(echo "${{ steps.meta.outputs.tags }}" | tail -n 1)" >> $GITHUB_OUTPUT
+  docker_scout:
+    name: Docker Scout CVEs
+    needs: build_image
+    runs-on: ubuntu-latest
+    environment:
+      name: container_health
+    steps:
+      - name: Docker Scout
+        uses: docker/scout-action@f8c776824083494ab0d56b8105ba2ca85c86e4de # v1.18.2
+        with:
+          command: cves
+          dockerhub-user: mh0386
+          dockerhub-password: ${{ secrets.TOKEN_KEY_DOCKER }}
+          image: ${{ needs.build_image.outputs.image_tag }}
+          github-token: ${{ secrets.GH_TOKEN }}
+  trufflehog:
+    name: TruffleHog
+    runs-on: ubuntu-latest
+    needs: build_image
+    environment:
+      name: container_health
+    steps:
+      - name: Install trufflehog
+        uses: jaxxstorm/action-install-gh-release@6096f2a2bbfee498ced520b6922ac2c06e990ed2 # v2.1.0
+        with:
+          repo: trufflesecurity/trufflehog
+          cache: enable
+      - name: Docker Secret Scanning
+        run: >-
+          trufflehog docker --image ${{needs.build_image.outputs.image_tag}}
+          --fail --github-actions --results=verified --log-level=4 --no-update
+  syft:
+    name: Syft
+    runs-on: ubuntu-latest
+    needs: build_image
+    environment:
+      name: container_health
+    permissions:
+      contents: write
+    steps:
+      - name: SBOM Generation
+        uses: anchore/sbom-action@deef08a0db64bfad603422135db61477b16cef56 # v0.22.1
+        with:
+          image: ${{ needs.build_image.outputs.image_tag }}
+          dependency-snapshot: true
+          output-file: ${{ github.event.repository.name }}-sbom.json
+          format: syft-json
+  grype:
+    name: Grype
+    needs: build_image
+    runs-on: ubuntu-latest
+    environment:
+      name: container_health
+    steps:
+      - name: Scan image
+        uses: anchore/scan-action@8d2fce09422cd6037e577f4130e9b925e9a37175 # v7.3.1
+        id: scan
+        with:
+          image: ${{ needs.build_image.outputs.image_tag }}
+          cache-db: true
+      - name: upload Anchore scan SARIF report
+        if: success() || failure()
+        uses: github/codeql-action/upload-sarif@b20883b0cd1f46c72ae0ba6d1090936928f9fa30 # v4.32.0
+        with:
+          sarif_file: ${{ steps.scan.outputs.sarif }}
+  trivy:
+    name: Trivy
+    needs: build_image
+    runs-on: ubuntu-latest
+    environment:
+      name: container_health
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - name: Run Trivy vulnerability scanner
+        uses: aquasecurity/trivy-action@b6643a29fecd7f34b3597bc6acb0a98b03d33ff8 # 0.33.1
+        with:
+          image-ref: ${{ needs.build_image.outputs.image_tag }}
+          trivy-config: .github/lint/.trivy.yaml
+          format: sarif
+          output: trivy-results-image.sarif
+          exit-code: '1'
+          scanners: vuln,secret,misconfig,license
+      - name: Upload Trivy scan results to GitHub Security tab
+        if: success() || failure()
+        uses: github/codeql-action/upload-sarif@b20883b0cd1f46c72ae0ba6d1090936928f9fa30 # v4.32.0
+        with:
+          sarif_file: trivy-results-image.sarif
+  dockle:
+    name: Dockle
+    needs: build_image
+    runs-on: ubuntu-latest
+    environment:
+      name: container_health
+    steps:
+      - name: Lint the Container Image
+        uses: goodwithtech/dockle-action@e30e6af832aad6ea7dca2a248d31a85eab6dbd68 # v0.4.15
+        with:
+          image: ${{ needs.build_image.outputs.image_tag }}
+          format: sarif
+          output: dockle.sarif
+          accept-file: settings.py
+          accept-key: --chmod,--chown,GRADIO_SERVER_PORT,GRADIO_SERVER_NAME,FASTEMBED_CACHE_PATH,PATH
+          ignore: CIS-DI-0006
+      - name: upload Dockle scan SARIF report
+        if: success() || failure()
+        uses: github/codeql-action/upload-sarif@b20883b0cd1f46c72ae0ba6d1090936928f9fa30 # v4.32.0
+        with:
+          sarif_file: dockle.sarif
+  api_test:
+    name: API Test
+    needs: build_image
+    runs-on: ubuntu-latest
+    if: ${{ inputs.is_test }}
+    environment:
+      name: container_health
+    services:
+      vector_database:
+        image: qdrant/qdrant:latest@sha256:0425e3e03e7fd9b3dc95c4214546afe19de2eb2e28ca621441a56663ac6e1f46
+        ports:
+          - 6333:6333
+      app:
+        image: ${{ needs.build_image.outputs.image_tag }}
+        ports:
+          - 7860:7860
+        env:
+          MODEL__URL: https://api.groq.com/openai/v1
+          MODEL__API_KEY: ${{ secrets.GROQ_API_KEY }}
+          MODEL__NAME: llama3-70b-8192
+          VECTOR_DATABASE__URL: http://vector_database:6333
+          VECTOR_DATABASE__NAME: test
+        options: >-
+          --health-cmd "curl -o /dev/null -f -s -w 'Status: %{http_code}, Time: %{time_total}s'
+          http://localhost:7860/" --health-interval 10s --health-timeout
+          10s --health-start-period 20s --health-retries 15
+    steps:
+      - name: Echo URL
+        run: echo "${{ github.event.repository.name }} available on localhost:${{ job.services.app.ports['7860'] }}"
+      - name: Checkout repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - name: Install uv
+        uses: astral-sh/setup-uv@803947b9bd8e9f986429fa0c5a41c367cd732b41 # v7.2.1
+        with:
+          enable-cache: true
+          activate-environment: true
+      - name: Install deps
+        run: uv sync --only-dev
+      - name: Test
+        uses: pavelzw/pytest-action@510c5e90c360a185039bea56ce8b3e7e51a16507 # v2.2.0
+        with:
+          click-to-expand: false
+          custom-arguments: tests/test_app.py::test_app -p no:warnings
+        env:
+          MERGIFY_TOKEN: ${{ secrets.MERGIFY_TOKEN }}
+  clean:
+    name: Cleaning GHCR
+    needs:
+      - api_test
+      - docker_scout
+      - dockle
+      - trivy
+      - grype
+      - syft
+      - trufflehog
+    if: ${{ inputs.registry == 'ghcr.io' && ( success() || failure() ) && !contains(github.event.head_commit.message, '[skip ghcr clean]') }}
+    runs-on: ubuntu-latest
+    environment:
+      name: docker_image
+    steps:
+      - name: GHCR Cleaning
+        uses: snok/container-retention-policy@3b0972b2276b171b212f8c4efbca59ebba26eceb # v3.0.1
+        with:
+          account: ${{ github.repository_owner }}
+          token: ${{ secrets.GH_TOKEN }}
+          image-names: ${{ github.event.repository.name }}
+          image-tags: '!latest !*.*.*'
+          cut-off: 1s

.github/workflows/.lint.yaml

@@ -0,0 +1,363 @@
+name: Lint
+on:
+  workflow_call:
+permissions:
+  contents: write
+  pull-requests: write
+  checks: write
+  security-events: write
+  actions: read
+jobs:
+  taplo:
+    name: Taplo ${{ matrix.command }}
+    runs-on: ubuntu-latest
+    environment:
+      name: code_quality
+    strategy:
+      fail-fast: false
+      matrix:
+        command:
+          - format
+          - lint
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - name: Install taplo
+        uses: baptiste0928/cargo-install@b687c656bda5733207e629b50a22bf68974a0305 # v3.3.2
+        with:
+          crate: taplo-cli
+          locked: true
+      - name: ${{ matrix.command }}
+        run: >-
+          taplo ${{matrix.command}}
+          --config .github/lint/.taplo.toml
+          ${{matrix.command == 'lint' && '--default-schema-catalogs' || ''}}
+      - name: Commit and push applied formatter fixes
+        if: matrix.command == 'format'
+        uses: stefanzweifel/git-auto-commit-action@04702edda442b2e678b25b537cec683a1493fcb9 # v7.1.0
+        with:
+          commit_message: '[Taplo] Apply formatter fixes'
+          commit_options: --no-verify
+  trufflehog:
+    name: TruffleHog
+    runs-on: ubuntu-latest
+    environment:
+      name: code_quality
+    steps:
+      - name: Install trufflehog
+        uses: jaxxstorm/action-install-gh-release@6096f2a2bbfee498ced520b6922ac2c06e990ed2 # v2.1.0
+        with:
+          repo: trufflesecurity/trufflehog
+          cache: enable
+      - name: Git Secret Scanning
+        run: >-
+          trufflehog git ${{github.event.repository.html_url}} --branch=${{github.head_ref || github.ref_name}}
+          --fail --github-actions --results=verified,unknown --log-level=4 --no-update
+  pre-commit:
+    name: pre-commit
+    runs-on: ubuntu-latest
+    environment:
+      name: code_quality
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - name: Install uv
+        uses: astral-sh/setup-uv@803947b9bd8e9f986429fa0c5a41c367cd732b41 # v7.2.1
+        with:
+          enable-cache: true
+          activate-environment: true
+      - name: Restore pre-commit cache
+        uses: actions/cache/restore@cdf6c1fa76f9f475f3d7449005a359c84ca0f306 # v5.0.3
+        id: cache-restore
+        with:
+          path: ~/.cache/pre-commit
+          key: pre-commit-${{ hashFiles('**/.pre-commit-config.yaml') }}
+          restore-keys: pre-commit-
+      - name: Run pre-commit hooks
+        run: uvx pre-commit run --show-diff-on-failure --color=always --all-files
+      - name: Save pre-commit cache
+        uses: actions/cache/save@cdf6c1fa76f9f475f3d7449005a359c84ca0f306 # v5.0.3
+        if: always() && steps.cache-restore.outputs.cache-hit != 'true'
+        with:
+          path: ~/.cache/pre-commit
+          key: ${{ steps.cache-restore.outputs.cache-primary-key }}
+      - name: Run pre-commit-ci-lite
+        uses: pre-commit-ci/lite-action@5d6cc0eb514c891a40562a58a8e71576c5c7fb43 # v1.1.0
+        if: always()
+  uv_lock:
+    name: UV Lock Check
+    runs-on: ubuntu-latest
+    environment:
+      name: code_quality
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - name: Install uv
+        uses: astral-sh/setup-uv@803947b9bd8e9f986429fa0c5a41c367cd732b41 # v7.2.1
+        with:
+          enable-cache: true
+          activate-environment: true
+      - name: Check if the lockfile is up-to-date
+        id: uv_lock_check
+        run: uv lock --check
+      - name: Job Summary
+        uses: jazanne/job-summary-action@690eb386a0b86fe4da7c6f0e543e61330ff09f06 # v1.0.0
+        if: success() || failure()
+        with:
+          summary: |
+            ## UV Lock Check
+            - **Status**: ${{ steps.uv_lock_check.outcome == 'success' && ':white_check_mark:' || ':x:' }}
+  ls_lint:
+    name: ls-lint
+    runs-on: ubuntu-latest
+    environment:
+      name: code_quality
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - name: Lint file names
+        uses: ls-lint/action@02e380fe8733d499cbfc9e22276de5085508a5bd # v2.3.1
+        with:
+          config: .github/lint/.ls-lint.yaml
+  ruff:
+    name: Ruff ${{ matrix.command }}
+    runs-on: ubuntu-latest
+    environment:
+      name: code_quality
+    strategy:
+      fail-fast: false
+      matrix:
+        command:
+          - check
+          - format
+        include:
+          - command: check
+            output: sarif
+          - command: format
+            output: github
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          token: ${{ secrets.GH_TOKEN }}
+      - name: ${{ matrix.command }}
+        uses: astral-sh/ruff-action@57714a7c8a2e59f32539362ba31877a1957dded1 # v3.5.1
+        with:
+          args: >-
+            ${{ matrix.command }} --config .github/lint/.ruff.toml
+            --output-format ${{matrix.output}}
+            ${{matrix.output == 'sarif' && '--output-file ruff.sarif' || ''}}
+      - name: upload Ruff scan SARIF report
+        if: matrix.output == 'sarif' && ( success() || failure() )
+        uses: github/codeql-action/upload-sarif@b20883b0cd1f46c72ae0ba6d1090936928f9fa30 # v4.32.0
+        with:
+          sarif_file: ruff.sarif
+      - name: Commit and push applied Ruff fixes
+        if: matrix.output == 'github'
+        uses: stefanzweifel/git-auto-commit-action@04702edda442b2e678b25b537cec683a1493fcb9 # v7.1.0
+        with:
+          commit_message: '[Ruff] Apply format fixes'
+          commit_options: --no-verify
+  yamlfix:
+    name: YamlFix
+    runs-on: ubuntu-latest
+    environment:
+      name: code_quality
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          token: ${{ secrets.GH_TOKEN }}
+      - name: Install uv
+        uses: astral-sh/setup-uv@803947b9bd8e9f986429fa0c5a41c367cd732b41 # v7.2.1
+        with:
+          enable-cache: true
+          activate-environment: true
+      - name: Format
+        run: uvx yamlfix . --config-file .github/lint/.yamlfix.toml
+      - name: Commit and push applied linter fixes
+        uses: stefanzweifel/git-auto-commit-action@04702edda442b2e678b25b537cec683a1493fcb9 # v7.1.0
+        with:
+          commit_message: '[YamlFix] Apply linters fixes'
+          commit_options: --no-verify
+  yamllint:
+    name: YamlLint
+    runs-on: ubuntu-latest
+    environment:
+      name: code_quality
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - name: Install uv
+        uses: astral-sh/setup-uv@803947b9bd8e9f986429fa0c5a41c367cd732b41 # v7.2.1
+        with:
+          enable-cache: true
+          activate-environment: true
+      - name: Check
+        run: uvx yamllint . --strict -c=.github/lint/.yamllint.yaml --format github
+  syft:
+    name: Syft
+    runs-on: ubuntu-latest
+    environment:
+      name: code_quality
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - name: SBOM Generation
+        uses: anchore/sbom-action@deef08a0db64bfad603422135db61477b16cef56 # v0.22.1
+        with:
+          path: .
+          dependency-snapshot: true
+          output-file: ${{ github.event.repository.name }}-sbom.json
+          format: syft-json
+  grype:
+    name: Grype
+    runs-on: ubuntu-latest
+    environment:
+      name: code_quality
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - name: Scan current project
+        uses: anchore/scan-action@8d2fce09422cd6037e577f4130e9b925e9a37175 # v7.3.1
+        id: scan
+        with:
+          path: .
+          cache-db: true
+      - name: upload Anchore scan SARIF report
+        if: success() || failure()
+        uses: github/codeql-action/upload-sarif@b20883b0cd1f46c72ae0ba6d1090936928f9fa30 # v4.32.0
+        with:
+          sarif_file: ${{ steps.scan.outputs.sarif }}
+  trivy:
+    name: Trivy ${{ matrix.name }}
+    runs-on: ubuntu-latest
+    environment:
+      name: code_quality
+    strategy:
+      fail-fast: false
+      matrix:
+        scan-type:
+          - repo
+          - config
+          - fs
+        include:
+          - scan-type: repo
+            format: sarif
+            output: trivy-results-repo.sarif
+            name: Repo
+          - scan-type: config
+            format: sarif
+            output: trivy-results-config.sarif
+            name: IaC
+          - scan-type: fs
+            format: github
+            output: dependency-results.sbom.json
+            name: SBOM
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - name: Run Trivy vulnerability scanner in repo mode
+        uses: aquasecurity/trivy-action@b6643a29fecd7f34b3597bc6acb0a98b03d33ff8 # 0.33.1
+        with:
+          scan-type: ${{ matrix.scan-type }}
+          trivy-config: .github/lint/.trivy.yaml
+          format: ${{ matrix.format }}
+          output: ${{ matrix.output }}
+          github-pat: ${{ secrets.GH_TOKEN }}
+          exit-code: '1'
+          scanners: vuln,secret,misconfig
+      - name: Upload Trivy scan results to GitHub Security tab
+        if: matrix.scan-type != 'fs' && ( success() || failure() )
+        uses: github/codeql-action/upload-sarif@b20883b0cd1f46c72ae0ba6d1090936928f9fa30 # v4.32.0
+        with:
+          sarif_file: ${{ matrix.output }}
+          category: ${{ matrix.scan-type }}
+      - name: Upload trivy report as a Github artifact
+        if: matrix.scan-type == 'fs' && ( success() || failure() )
+        uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6.0.0
+        with:
+          name: trivy-sbom-report
+          path: ${{ matrix.output }}
+  dclint:
+    name: DCLint
+    runs-on: ubuntu-latest
+    environment:
+      name: code_quality
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - name: Lint Docker Compose file
+        uses: docker-compose-linter/dclint-github-action@18659f6a7956706cb67cf9c1ad5e55f4352cbc17 # v1.6.0
+        with:
+          fix: true
+          recursive: true
+  ty:
+    name: Ty
+    runs-on: ubuntu-latest
+    environment:
+      name: code_quality
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - name: Install uv
+        uses: astral-sh/setup-uv@803947b9bd8e9f986429fa0c5a41c367cd732b41 # v7.2.1
+        with:
+          enable-cache: true
+          activate-environment: true
+      - name: Check
+        run: uvx ty check --output-format github
+  markdownlint:
+    name: MarkdownLint
+    runs-on: ubuntu-latest
+    environment:
+      name: code_quality
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - name: Lint Markdown files
+        uses: DavidAnson/markdownlint-cli2-action@07035fd053f7be764496c0f8d8f9f41f98305101 # v22.0.0
+        with:
+          globs: '**/*.md'
+          config: .github/lint/.markdownlint.yaml
+          fix: true
+  hadolint:
+    name: Hadolint
+    runs-on: ubuntu-latest
+    environment:
+      name: code_quality
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - name: Lint Dockerfile
+        uses: hadolint/hadolint-action@2332a7b74a6de0dda2e2221d575162eba76ba5e5 # v3.3.0
+        with:
+          config: .github/lint/.hadolint.yaml
+          format: sarif
+          output-file: hadolint.sarif
+      - name: upload Hadolint scan SARIF report
+        if: success() || failure()
+        uses: github/codeql-action/upload-sarif@b20883b0cd1f46c72ae0ba6d1090936928f9fa30 # v4.32.0
+        with:
+          sarif_file: hadolint.sarif
+  actionlint:
+    name: ActionLint
+    runs-on: ubuntu-latest
+    environment:
+      name: code_quality
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - name: Install actionlint
+        uses: jaxxstorm/action-install-gh-release@6096f2a2bbfee498ced520b6922ac2c06e990ed2 # v2.1.0
+        with:
+          repo: rhysd/actionlint
+          cache: enable
+      - name: Download actionlint-matcher.json
+        run: >-
+          curl -fsSL https://raw.githubusercontent.com/rhysd/actionlint/main/.github/actionlint-matcher.json
+          -o .github/actionlint-matcher.json
+      - name: Run actionlint
+        run: |-
+          echo "::add-matcher::.github/actionlint-matcher.json"
+          actionlint -color

.github/workflows/build.yaml

@@ -0,0 +1,86 @@
+name: Build
+on:
+  push:
+    tags:
+      - '[0-9]+.[0-9]+.[0-9]+'
+      - '[0-9]+.[0-9]+.[0-9]+a[0-9]+'
+      - '[0-9]+.[0-9]+.[0-9]+b[0-9]+'
+permissions: read-all
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref_name }}
+  cancel-in-progress: true
+jobs:
+  setup_and_build:
+    name: Setup and Build
+    environment:
+      name: uv
+      url: ${{github.event.repository.html_url}}/commits/${{github.ref_name}}
+    env:
+      UV_COMPILE_BYTECODE: '1'
+      UV_LINK_MODE: copy
+    permissions:
+      contents: write
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          token: ${{ secrets.GH_TOKEN }}
+      - name: Get Package version from pyproject.toml
+        id: get_package_version
+        uses: mikefarah/yq@065b200af9851db0d5132f50bc10b1406ea5c0a8 # v4.50.1
+        with:
+          cmd: yq -roy '.project.version' pyproject.toml
+      - name: Install uv
+        uses: astral-sh/setup-uv@803947b9bd8e9f986429fa0c5a41c367cd732b41 # v7.2.1
+        with:
+          enable-cache: true
+          activate-environment: true
+      - name: Install the project
+        run: uv sync --no-dev --frozen --no-editable
+      - name: Update Project Version
+        if: ${{ github.ref_name != steps.get_package_version.outputs.result }}
+        run: uv version ${{ github.ref_name }}
+      - name: Build source and wheel distribution
+        run: uv build
+      - name: Upload artifacts
+        uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6.0.0
+        with:
+          name: dist
+          path: dist/
+      - name: Update the main branch to the updated version
+        if: ${{ github.ref_name != steps.get_package_version.outputs.result }}
+        uses: stefanzweifel/git-auto-commit-action@04702edda442b2e678b25b537cec683a1493fcb9 # v7.1.0
+        with:
+          commit_message: 'Version: ${{ github.ref_name }}'
+          branch: main
+          commit_options: --no-verify
+      - name: Update the tag to the updated version
+        if: ${{ github.ref_name != steps.get_package_version.outputs.result }}
+        run: |
+          git tag --force ${{ github.ref_name }}
+          git push origin --force HEAD:refs/tags/${{ github.ref_name }}
+  github_release:
+    name: Create GitHub Release
+    needs: setup_and_build
+    runs-on: ubuntu-latest
+    environment:
+      name: github
+      url: ${{github.event.repository.html_url}}/releases/tag/${{github.ref_name}}
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - name: Download artifacts
+        uses: actions/download-artifact@37930b1c2abaa49bbe596cd826c3c89aef350131 # v7.0.0
+        with:
+          name: dist
+          path: dist/
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@a06a81a03ee405af7f2048a818ed3f03bbf83c7b # v2.5.0
+        with:
+          files: dist/*
+          generate_release_notes: true
+          make_latest: true
+          fail_on_unmatched_files: true

.github/workflows/ci_tools.yaml

@@ -0,0 +1,106 @@
+name: CI Tools
+on:
+  push:
+    branches:
+      - main
+  issue_comment:
+    types:
+      - created
+      - edited
+  workflow_dispatch:
+permissions:
+  id-token: write
+  contents: write
+  pull-requests: read
+  issues: read
+jobs:
+  opencode:
+    if: |
+      github.event_name == 'issue_comment' &&
+      (
+        contains(github.event.comment.body, ' /oc') ||
+        startsWith(github.event.comment.body, '/oc') ||
+        contains(github.event.comment.body, ' /opencode') ||
+        startsWith(github.event.comment.body, '/opencode')
+      )
+    name: Opencode
+    runs-on: ubuntu-latest
+    environment:
+      name: ai_agent
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - name: Run opencode
+        uses: sst/opencode/github@8f537940178772deedf3317c5c669950f1f6c5a6 # v1.1.45
+        env:
+          OPENCODE_API_KEY: ${{ secrets.OPENCODE_API_KEY }}
+        with:
+          model: opencode/grok-code
+  uv_lock_sync:
+    if: |
+      github.event_name == 'workflow_dispatch' ||
+      (
+        github.event_name == 'issue_comment' &&
+        (
+          contains(github.event.comment.body, ' /uv-lock-sync') ||
+          startsWith(github.event.comment.body, '/uv-lock-sync')
+        )
+      )
+    name: UV Lock Sync
+    runs-on: ubuntu-latest
+    environment:
+      name: lockfile
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          token: ${{ secrets.GH_TOKEN }}
+      - name: Install uv
+        uses: astral-sh/setup-uv@803947b9bd8e9f986429fa0c5a41c367cd732b41 # v7.2.1
+        with:
+          enable-cache: true
+          activate-environment: true
+      - name: Sync dependencies and uv.lock
+        run: uv lock
+      - name: Commit and push changes
+        uses: stefanzweifel/git-auto-commit-action@04702edda442b2e678b25b537cec683a1493fcb9 # v7.1.0
+        with:
+          commit_message: Sync uv.lock
+          commit_options: --no-verify
+  huggingface:
+    name: Sync HuggingFace Space
+    runs-on: ubuntu-latest
+    if: |
+      github.event_name == 'push' ||
+      github.event_name == 'workflow_dispatch' ||
+      (
+        github.event_name == 'issue_comment' &&
+        (
+          contains(github.event.comment.body, ' /hf-sync') ||
+          startsWith(github.event.comment.body, '/hf-sync')
+        )
+      )
+    permissions:
+      contents: read
+      id-token: write
+    environment:
+      name: huggingface
+      url: https://huggingface.co/spaces/${{github.repository}}
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4.0.0
+        with:
+          fetch-depth: 0
+          lfs: true
+      - name: Install uv
+        uses: astral-sh/setup-uv@61cb8a9741eeb8a550a1b8544337180c0fc8476b # v7.2.0
+        with:
+          enable-cache: true
+          activate-environment: true
+      - name: Push to HF
+        env:
+          HF_TOKEN: ${{ secrets.HF_TOKEN }}
+          COMMIT_MESSAGE: ${{ github.event.head_commit.message || 'Sync from GitHub' }}
+        run: >-
+          uvx hf upload ${{github.repository}} . . --repo-type space
+          --delete '*' --exclude '.github' --commit-message "$COMMIT_MESSAGE"

.github/workflows/release.yaml

@@ -0,0 +1,70 @@
+name: Release
+on:
+  release:
+    types:
+      - published
+permissions: read-all
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref_name }}
+  cancel-in-progress: true
+jobs:
+  pypi:
+    name: Upload Python Package
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    environment:
+      name: pypi
+      url: https://pypi.org/project/${{github.event.repository.name}}/${{github.event.release.tag_name}}
+    steps:
+      - name: Retrieve release distributions
+        uses: robinraju/release-downloader@daf26c55d821e836577a15f77d86ddc078948b05 # v1.12
+        with:
+          tag: ${{ github.event.release.tag_name }}
+          out-file-path: dist/
+          fileName: '*'
+      - name: Publish release distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/
+  huggingface:
+    name: Tag HuggingFace Space
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    environment:
+      name: huggingface
+      url: https://huggingface.co/spaces/${{github.repository}}/tree/${{github.event.release.tag_name}}
+    steps:
+      - name: Install uv
+        uses: astral-sh/setup-uv@61cb8a9741eeb8a550a1b8544337180c0fc8476b # v7.2.0
+        with:
+          enable-cache: true
+          activate-environment: true
+      - name: Push to HF
+        env:
+          HF_TOKEN: ${{ secrets.HF_TOKEN }}
+        run: >-
+          uvx hf repo tag create ${{github.repository}} ${{github.event.release.tag_name}}
+          --repo-type space
+  image:
+    name: Release Image
+    needs: pypi
+    permissions:
+      contents: read
+      packages: write
+      attestations: write
+      id-token: write
+    strategy:
+      matrix:
+        registry:
+          - ghcr.io
+          - docker.io
+    uses: ./.github/workflows/.docker.yaml
+    with:
+      is_test: false
+      registry: ${{ matrix.registry }}
+      install_source: ${{github.event.repository.name}}==${{github.event.release.tag_name}}
+    secrets: inherit

.github/workflows/test.yaml

@@ -0,0 +1,76 @@
+name: Test
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+  workflow_dispatch:
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref_name }}
+  cancel-in-progress: true
+permissions: read-all
+jobs:
+  compatibility:
+    name: Check Dependency Compatibility
+    runs-on: ubuntu-latest
+    environment:
+      name: code_quality
+    permissions:
+      checks: write
+      contents: read
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - name: Install uv
+        uses: astral-sh/setup-uv@803947b9bd8e9f986429fa0c5a41c367cd732b41 # v7.2.1
+        with:
+          enable-cache: true
+          activate-environment: true
+      - name: Install the project
+        id: dependency_check
+        run: uv sync --frozen --no-install-project
+      - name: Job Summary
+        uses: jazanne/job-summary-action@690eb386a0b86fe4da7c6f0e543e61330ff09f06 # v1.0.0
+        if: success() || failure()
+        with:
+          summary: |-
+            ## Dependency Compatibility Check
+              - **Status**: ${{ steps.dependency_check.outcome == 'success' && ':white_check_mark:' || ':x:' }}
+      - name: Show Dependency Tree
+        if: steps.dependency_check.outcome == 'success'
+        run: |
+          echo "## Dependency Tree" >> $GITHUB_STEP_SUMMARY
+          echo "<details>" >> $GITHUB_STEP_SUMMARY
+          echo "<summary> Dependency Tree </summary>" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo '```' >> $GITHUB_STEP_SUMMARY
+          echo "$(uv tree --show-sizes)" >> $GITHUB_STEP_SUMMARY
+          echo '```' >> $GITHUB_STEP_SUMMARY
+          echo "</details>" >> $GITHUB_STEP_SUMMARY
+  lint:
+    name: Lint
+    permissions:
+      contents: write
+      pull-requests: write
+      checks: write
+      security-events: write
+      actions: read
+    needs: compatibility
+    uses: ./.github/workflows/.lint.yaml
+    secrets: inherit
+  image:
+    name: Test Image
+    permissions:
+      contents: write
+      packages: write
+      attestations: write
+      id-token: write
+      security-events: write
+      actions: read
+    needs: compatibility
+    uses: ./.github/workflows/.docker.yaml
+    with:
+      is_test: true
+      registry: ghcr.io
+      install_source: git+${{ github.event.repository.html_url }}@${{ github.sha }}
+    secrets: inherit

.github/workflows/version.yaml

@@ -0,0 +1,45 @@
+name: Version
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - pyproject.toml
+      - uv.lock
+      - Dockerfile
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref_name }}
+  cancel-in-progress: false
+permissions: read-all
+jobs:
+  version:
+    name: Versioning
+    runs-on: ubuntu-latest
+    if: github.actor == 'renovate[bot]' || github.actor == 'mergify[bot]'
+    permissions:
+      contents: write
+    environment:
+      name: versioning
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          token: ${{ secrets.GH_TOKEN }}
+          fetch-depth: 0
+      - name: Install uv
+        uses: astral-sh/setup-uv@803947b9bd8e9f986429fa0c5a41c367cd732b41 # v7.2.1
+        with:
+          enable-cache: true
+          activate-environment: true
+      - name: Increase the patch version
+        run: uv version --bump patch
+      - name: Get Package version from pyproject.toml
+        id: get_package_version
+        uses: mikefarah/yq@065b200af9851db0d5132f50bc10b1406ea5c0a8 # v4.50.1
+        with:
+          cmd: yq -roy '.project.version' pyproject.toml
+      - name: Commit updated count
+        uses: stefanzweifel/git-auto-commit-action@04702edda442b2e678b25b537cec683a1493fcb9 # v7.1.0
+        with:
+          commit_message: 'Tag: ${{ steps.get_package_version.outputs.result }}'
+          tagging_message: ${{ steps.get_package_version.outputs.result }}

.gitignore

@@ -0,0 +1,12 @@
+**/__pycache__/
+.env
+.mypy_cache/
+.ruff_cache/
+.venv/
+logs/
+results/
+qdrant_storage/
+assets/audio/
+assets/video/
+agno/
+.vscode/settings.json

.idea/.gitignore

@@ -0,0 +1,12 @@
+# Default ignored files
+/shelf/
+/workspace.xml
+# Ignored default folder with query files
+/queries/
+# Datasource local storage ignored files
+/dataSources/
+/dataSources.local.xml
+# Editor-based HTTP Client requests
+/httpRequests/
+
+copilot.*.xml

.idea/chattr.iml

@@ -0,0 +1,15 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<module type="PYTHON_MODULE" version="4">
+  <component name="NewModuleRootManager">
+    <content url="file://$MODULE_DIR$">
+      <sourceFolder url="file://$MODULE_DIR$/src" isTestSource="false" />
+      <excludeFolder url="file://$MODULE_DIR$/.venv" />
+    </content>
+    <orderEntry type="jdk" jdkName="uv (chattr)" jdkType="Python SDK" />
+    <orderEntry type="sourceFolder" forTests="false" />
+  </component>
+  <component name="PyDocumentationSettings">
+    <option name="format" value="GOOGLE" />
+    <option name="myDocStringFormat" value="Google" />
+  </component>
+</module>

.idea/inspectionProfiles/Project_Default.xml

@@ -0,0 +1,237 @@
+<component name="InspectionProjectProfileManager">
+  <profile version="1.0">
+    <option name="myName" value="Project Default" />
+    <inspection_tool class="AlphaUnsortedPropertiesFile" enabled="true" level="WEAK WARNING" enabled_by_default="true" />
+    <inspection_tool class="AngularAmbiguousComponentTag" enabled="false" level="ERROR" enabled_by_default="false" />
+    <inspection_tool class="AngularBindingTypeMismatch" enabled="false" level="ERROR" enabled_by_default="false" />
+    <inspection_tool class="AngularCliAddDependency" enabled="false" level="WARNING" enabled_by_default="false" />
+    <inspection_tool class="AngularDeferBlockOnTrigger" enabled="false" level="ERROR" enabled_by_default="false" />
+    <inspection_tool class="AngularForBlockNonIterableVar" enabled="false" level="ERROR" enabled_by_default="false" />
+    <inspection_tool class="AngularIllegalForLoopTrackAccess" enabled="false" level="ERROR" enabled_by_default="false" />
+    <inspection_tool class="AngularInaccessibleSymbol" enabled="false" level="ERROR" enabled_by_default="false" />
+    <inspection_tool class="AngularIncorrectBlockUsage" enabled="false" level="ERROR" enabled_by_default="false" />
+    <inspection_tool class="AngularIncorrectLetUsage" enabled="false" level="ERROR" enabled_by_default="false" />
+    <inspection_tool class="AngularIncorrectTemplateDefinition" enabled="false" level="ERROR" enabled_by_default="false" />
+    <inspection_tool class="AngularInsecureBindingToEvent" enabled="false" level="WARNING" enabled_by_default="false" />
+    <inspection_tool class="AngularInvalidAnimationTriggerAssignment" enabled="false" level="ERROR" enabled_by_default="false" />
+    <inspection_tool class="AngularInvalidEntryComponent" enabled="false" level="ERROR" enabled_by_default="false" />
+    <inspection_tool class="AngularInvalidI18nAttribute" enabled="false" level="WARNING" enabled_by_default="false" />
+    <inspection_tool class="AngularInvalidImportedOrDeclaredSymbol" enabled="false" level="ERROR" enabled_by_default="false" />
+    <inspection_tool class="AngularInvalidSelector" enabled="false" level="ERROR" enabled_by_default="false" />
+    <inspection_tool class="AngularInvalidTemplateReferenceVariable" enabled="false" level="ERROR" enabled_by_default="false" />
+    <inspection_tool class="AngularMissingEventHandler" enabled="false" level="ERROR" enabled_by_default="false" />
+    <inspection_tool class="AngularMissingOrInvalidDeclarationInModule" enabled="false" level="ERROR" enabled_by_default="false" />
+    <inspection_tool class="AngularMissingRequiredDirectiveInputBinding" enabled="false" level="ERROR" enabled_by_default="false" />
+    <inspection_tool class="AngularMultipleStructuralDirectives" enabled="false" level="ERROR" enabled_by_default="false" />
+    <inspection_tool class="AngularNgOptimizedImage" enabled="false" level="WEAK WARNING" enabled_by_default="false" />
+    <inspection_tool class="AngularNonEmptyNgContent" enabled="false" level="ERROR" enabled_by_default="false" />
+    <inspection_tool class="AngularNonStandaloneComponentImports" enabled="false" level="ERROR" enabled_by_default="false" />
+    <inspection_tool class="AngularRecursiveModuleImportExport" enabled="false" level="ERROR" enabled_by_default="false" />
+    <inspection_tool class="AngularUndefinedBinding" enabled="false" level="ERROR" enabled_by_default="false" />
+    <inspection_tool class="AngularUndefinedModuleExport" enabled="false" level="ERROR" enabled_by_default="false" />
+    <inspection_tool class="AngularUndefinedTag" enabled="false" level="ERROR" enabled_by_default="false" />
+    <inspection_tool class="AngularUnresolvedPipe" enabled="false" level="ERROR" enabled_by_default="false" />
+    <inspection_tool class="AngularUnsupportedSyntax" enabled="false" level="ERROR" enabled_by_default="false" />
+    <inspection_tool class="AngularUnusedComponentImport" enabled="false" level="ERROR" enabled_by_default="false" />
+    <inspection_tool class="BadExpressionStatementJS" enabled="false" level="WEAK WARNING" enabled_by_default="false" />
+    <inspection_tool class="CallerJS" enabled="false" level="WARNING" enabled_by_default="false" />
+    <inspection_tool class="CommaExpressionJS" enabled="false" level="WARNING" enabled_by_default="false" />
+    <inspection_tool class="ConstantConditionalExpressionJS" enabled="false" level="WARNING" enabled_by_default="false" />
+    <inspection_tool class="ContinueOrBreakFromFinallyBlockJS" enabled="false" level="WARNING" enabled_by_default="false" />
+    <inspection_tool class="CssBrowserCompatibilityForProperties" enabled="true" level="WARNING" enabled_by_default="true" />
+    <inspection_tool class="CssConvertColorToHexInspection" enabled="true" level="WARNING" enabled_by_default="true" />
+    <inspection_tool class="CssConvertColorToRgbInspection" enabled="true" level="WARNING" enabled_by_default="true" />
+    <inspection_tool class="CssInvalidNestedSelector" enabled="true" level="WARNING" enabled_by_default="true" />
+    <inspection_tool class="CssMissingSemicolon" enabled="true" level="WARNING" enabled_by_default="true" />
+    <inspection_tool class="CyclomaticComplexityInspection" enabled="true" level="WARNING" enabled_by_default="true" />
+    <inspection_tool class="DjangoUnresolvedUrlInspection" enabled="true" level="WEAK WARNING" enabled_by_default="true" />
+    <inspection_tool class="DuplicatePropertyInspection" enabled="true" level="WARNING" enabled_by_default="true" />
+    <inspection_tool class="ES6BindWithArrowFunction" enabled="false" level="WARNING" enabled_by_default="false" />
+    <inspection_tool class="ES6ClassMemberInitializationOrder" enabled="false" level="WARNING" enabled_by_default="false" />
+    <inspection_tool class="ES6ConvertIndexedForToForOf" enabled="false" level="INFORMATION" enabled_by_default="false" />
+    <inspection_tool class="ES6ConvertLetToConst" enabled="false" level="INFORMATION" enabled_by_default="false" />
+    <inspection_tool class="ES6ConvertModuleExportToExport" enabled="false" level="INFORMATION" enabled_by_default="false" />
+    <inspection_tool class="ES6ConvertRequireIntoImport" enabled="false" level="INFORMATION" enabled_by_default="false" />
+    <inspection_tool class="ES6ConvertToForOf" enabled="false" level="INFORMATION" enabled_by_default="false" />
+    <inspection_tool class="ES6ConvertVarToLetConst" enabled="false" level="WEAK WARNING" enabled_by_default="false" />
+    <inspection_tool class="ES6DestructuringVariablesMerge" enabled="false" level="WEAK WARNING" enabled_by_default="false" />
+    <inspection_tool class="ES6MissingAwait" enabled="false" level="WEAK WARNING" enabled_by_default="false" />
+    <inspection_tool class="ES6PossiblyAsyncFunction" enabled="false" level="WEAK WARNING" enabled_by_default="false" />
+    <inspection_tool class="ES6PreferShortImport" enabled="false" level="WARNING" enabled_by_default="false" />
+    <inspection_tool class="ES6RedundantAwait" enabled="false" level="WEAK WARNING" enabled_by_default="false" />
+    <inspection_tool class="ES6RedundantNestingInTemplateLiteral" enabled="false" level="WEAK WARNING" enabled_by_default="false" />
+    <inspection_tool class="ES6ShorthandObjectProperty" enabled="false" level="INFORMATION" enabled_by_default="false" />
+    <inspection_tool class="ES6UnusedImports" enabled="false" level="WARNING" enabled_by_default="false" />
+    <inspection_tool class="EmptyDirectory" enabled="true" level="WARNING" enabled_by_default="true" />
+    <inspection_tool class="EmptyStatementBodyJS" enabled="false" level="WARNING" enabled_by_default="false" />
+    <inspection_tool class="Eslint" enabled="true" level="WARNING" enabled_by_default="true" />
+    <inspection_tool class="ExceptionCaughtLocallyJS" enabled="false" level="WARNING" enabled_by_default="false" />
+    <inspection_tool class="FallThroughInSwitchStatementJS" enabled="false" level="WARNING" enabled_by_default="false" />
+    <inspection_tool class="FlowJSConfig" enabled="false" level="WARNING" enabled_by_default="false" />
+    <inspection_tool class="FlowJSFlagCommentPlacement" enabled="false" level="WARNING" enabled_by_default="false" />
+    <inspection_tool class="HtmlNonExistentInternetResource" enabled="true" level="WARNING" enabled_by_default="true" />
+    <inspection_tool class="HtmlPresentationalElement" enabled="true" level="INFORMATION" enabled_by_default="true" />
+    <inspection_tool class="HtmlRequiredSummaryAttribute" enabled="true" level="INFORMATION" enabled_by_default="true" />
+    <inspection_tool class="HtmlRequiredTitleAttribute" enabled="true" level="INFORMATION" enabled_by_default="true" />
+    <inspection_tool class="IncompatibleMaskJS" enabled="false" level="WARNING" enabled_by_default="false" />
+    <inspection_tool class="InconsistentLineSeparators" enabled="true" level="WARNING" enabled_by_default="true" />
+    <inspection_tool class="IncorrectFormatting" enabled="true" level="WEAK WARNING" enabled_by_default="true" />
+    <inspection_tool class="InfiniteLoopJS" enabled="false" level="WARNING" enabled_by_default="false" />
+    <inspection_tool class="InfiniteRecursionJS" enabled="false" level="WARNING" enabled_by_default="false" />
+    <inspection_tool class="JSAccessibilityCheck" enabled="false" level="WARNING" enabled_by_default="false" />
+    <inspection_tool class="JSAnnotator" enabled="false" level="ERROR" enabled_by_default="false" />
+    <inspection_tool class="JSArrowFunctionBracesCanBeRemoved" enabled="false" level="INFORMATION" enabled_by_default="false" />
+    <inspection_tool class="JSAssignmentUsedAsCondition" enabled="false" level="WARNING" enabled_by_default="false" />
+    <inspection_tool class="JSBitwiseOperatorUsage" enabled="false" level="WARNING" enabled_by_default="false" />
+    <inspection_tool class="JSCheckFunctionSignatures" enabled="false" level="WEAK WARNING" enabled_by_default="false" />
+    <inspection_tool class="JSClosureCompilerSyntax" enabled="false" level="WARNING" enabled_by_default="false" />
+    <inspection_tool class="JSCommentMatchesSignature" enabled="false" level="WARNING" enabled_by_default="false" />
+    <inspection_tool class="JSComparisonWithNaN" enabled="false" level="WARNING" enabled_by_default="false" />
+    <inspection_tool class="JSConsecutiveCommasInArrayLiteral" enabled="false" level="WARNING" enabled_by_default="false" />
+    <inspection_tool class="JSConstantReassignment" enabled="false" level="ERROR" enabled_by_default="false" />
+    <inspection_tool class="JSDeprecatedSymbols" enabled="false" level="WEAK WARNING" enabled_by_default="false" />
+    <inspection_tool class="JSDuplicateCaseLabel" enabled="false" level="WARNING" enabled_by_default="false" />
+    <inspection_tool class="JSDuplicatedDeclaration" enabled="false" level="WARNING" enabled_by_default="false" />
+    <inspection_tool class="JSEqualityComparisonWithCoercion" enabled="false" level="WARNING" enabled_by_default="false" />
+    <inspection_tool class="JSFileReferences" enabled="false" level="WARNING" enabled_by_default="false" />
+    <inspection_tool class="JSFunctionExpressionToArrowFunction" enabled="false" level="INFORMATION" enabled_by_default="false" />
+    <inspection_tool class="JSIgnoredPromiseFromCall" enabled="false" level="WEAK WARNING" enabled_by_default="false" />
+    <inspection_tool class="JSIncompatibleTypesComparison" enabled="false" level="WEAK WARNING" enabled_by_default="false" />
+    <inspection_tool class="JSJQueryEfficiency" enabled="false" level="WARNING" enabled_by_default="false" />
+    <inspection_tool class="JSJoinVariableDeclarationAndAssignment" enabled="false" level="INFORMATION" enabled_by_default="false" />
+    <inspection_tool class="JSLastCommaInArrayLiteral" enabled="false" level="WARNING" enabled_by_default="false" />
+    <inspection_tool class="JSLastCommaInObjectLiteral" enabled="false" level="WARNING" enabled_by_default="false" />
+    <inspection_tool class="JSMethodCanBeStatic" enabled="false" level="INFORMATION" enabled_by_default="false" />
+    <inspection_tool class="JSMismatchedCollectionQueryUpdate" enabled="false" level="WARNING" enabled_by_default="false" />
+    <inspection_tool class="JSMissingSwitchBranches" enabled="false" level="INFORMATION" enabled_by_default="false" />
+    <inspection_tool class="JSMissingSwitchDefault" enabled="false" level="INFORMATION" enabled_by_default="false" />
+    <inspection_tool class="JSNonASCIINames" enabled="false" level="WARNING" enabled_by_default="false" />
+    <inspection_tool class="JSObjectNullOrUndefined" enabled="false" level="WARNING" enabled_by_default="false" />
+    <inspection_tool class="JSOctalInteger" enabled="false" level="ERROR" enabled_by_default="false" />
+    <inspection_tool class="JSPotentiallyInvalidConstructorUsage" enabled="false" level="WARNING" enabled_by_default="false" />
+    <inspection_tool class="JSPotentiallyInvalidTargetOfIndexedPropertyAccess" enabled="false" level="WARNING" enabled_by_default="false" />
+    <inspection_tool class="JSPotentiallyInvalidUsageOfClassThis" enabled="false" level="WARNING" enabled_by_default="false" />
+    <inspection_tool class="JSPotentiallyInvalidUsageOfThis" enabled="false" level="WARNING" enabled_by_default="false" />
+    <inspection_tool class="JSPrimitiveTypeWrapperUsage" enabled="false" level="WARNING" enabled_by_default="false" />
+    <inspection_tool class="JSRedundantSwitchStatement" enabled="false" level="INFORMATION" enabled_by_default="false" />
+    <inspection_tool class="JSReferencingMutableVariableFromClosure" enabled="false" level="WARNING" enabled_by_default="false" />
+    <inspection_tool class="JSRemoveUnnecessaryParentheses" enabled="false" level="INFORMATION" enabled_by_default="false" />
+    <inspection_tool class="JSStringConcatenationToES6Template" enabled="false" level="INFORMATION" enabled_by_default="false" />
+    <inspection_tool class="JSSuspiciousEqPlus" enabled="false" level="WARNING" enabled_by_default="false" />
+    <inspection_tool class="JSSuspiciousNameCombination" enabled="false" level="WARNING" enabled_by_default="false" />
+    <inspection_tool class="JSSwitchVariableDeclarationIssue" enabled="false" level="WARNING" enabled_by_default="false" />
+    <inspection_tool class="JSTestFailedLine" enabled="false" level="WARNING" enabled_by_default="false" />
+    <inspection_tool class="JSTypeOfValues" enabled="false" level="WARNING" enabled_by_default="false" />
+    <inspection_tool class="JSUndeclaredVariable" enabled="false" level="WEAK WARNING" enabled_by_default="false" />
+    <inspection_tool class="JSUndefinedPropertyAssignment" enabled="false" level="WEAK WARNING" enabled_by_default="false" />
+    <inspection_tool class="JSUnnecessarySemicolon" enabled="false" level="WARNING" enabled_by_default="false" />
+    <inspection_tool class="JSUnreachableSwitchBranches" enabled="false" level="WARNING" enabled_by_default="false" />
+    <inspection_tool class="JSUnresolvedExtXType" enabled="false" level="WARNING" enabled_by_default="false" />
+    <inspection_tool class="JSUnresolvedLibraryURL" enabled="false" level="WARNING" enabled_by_default="false" />
+    <inspection_tool class="JSUnresolvedReference" enabled="false" level="WEAK WARNING" enabled_by_default="false" />
+    <inspection_tool class="JSUnusedAssignment" enabled="false" level="WARNING" enabled_by_default="false" />
+    <inspection_tool class="JSUnusedGlobalSymbols" enabled="false" level="WARNING" enabled_by_default="false" />
+    <inspection_tool class="JSUnusedLocalSymbols" enabled="false" level="WARNING" enabled_by_default="false" />
+    <inspection_tool class="JSUrlImportUsage" enabled="false" level="INFORMATION" enabled_by_default="false" />
+    <inspection_tool class="JSValidateJSDoc" enabled="false" level="WARNING" enabled_by_default="false" />
+    <inspection_tool class="JSValidateTypes" enabled="false" level="WEAK WARNING" enabled_by_default="false" />
+    <inspection_tool class="JSVoidFunctionReturnValueUsed" enabled="false" level="WARNING" enabled_by_default="false" />
+    <inspection_tool class="JSXDomNesting" enabled="false" level="WARNING" enabled_by_default="false" />
+    <inspection_tool class="JSXNamespaceValidation" enabled="false" level="INFORMATION" enabled_by_default="false" />
+    <inspection_tool class="JSXUnresolvedComponent" enabled="false" level="WEAK WARNING" enabled_by_default="false" />
+    <inspection_tool class="KarmaConfigFile" enabled="false" level="WARNING" enabled_by_default="false" />
+    <inspection_tool class="LongLine" enabled="true" level="WARNING" enabled_by_default="true" />
+    <inspection_tool class="LoopStatementThatDoesntLoopJS" enabled="false" level="WARNING" enabled_by_default="false" />
+    <inspection_tool class="NodeCoreCodingAssistance" enabled="false" level="WARNING" enabled_by_default="false" />
+    <inspection_tool class="NpmUsedModulesInstalled" enabled="false" level="WEAK WARNING" enabled_by_default="false" />
+    <inspection_tool class="NpmVulnerableApiCode" enabled="false" level="WARNING" enabled_by_default="false" />
+    <inspection_tool class="PackageJsonMismatchedDependency" enabled="false" level="WARNING" enabled_by_default="false" />
+    <inspection_tool class="PointlessArithmeticExpressionJS" enabled="false" level="WARNING" enabled_by_default="false" />
+    <inspection_tool class="PointlessBooleanExpressionJS" enabled="false" level="WARNING" enabled_by_default="false" />
+    <inspection_tool class="PostCssCustomMedia" enabled="false" level="ERROR" enabled_by_default="false" />
+    <inspection_tool class="PostCssCustomSelector" enabled="false" level="ERROR" enabled_by_default="false" />
+    <inspection_tool class="PostCssMediaRange" enabled="false" level="ERROR" enabled_by_default="false" />
+    <inspection_tool class="PostCssUnresolvedModuleValueReference" enabled="false" level="ERROR" enabled_by_default="false" />
+    <inspection_tool class="ProblematicWhitespace" enabled="true" level="WARNING" enabled_by_default="true" />
+    <inspection_tool class="PyArgumentEqualDefaultInspection" enabled="true" level="WEAK WARNING" enabled_by_default="true" />
+    <inspection_tool class="PyAugmentAssignmentInspection" enabled="true" level="WEAK WARNING" enabled_by_default="true" />
+    <inspection_tool class="PyClassicStyleClassInspection" enabled="true" level="WARNING" enabled_by_default="true" />
+    <inspection_tool class="PyCompatibilityInspection" enabled="true" level="WARNING" enabled_by_default="true">
+      <option name="ourVersions">
+        <value>
+          <list size="5">
+            <item index="0" class="java.lang.String" itemvalue="3.14" />
+            <item index="1" class="java.lang.String" itemvalue="3.10" />
+            <item index="2" class="java.lang.String" itemvalue="3.11" />
+            <item index="3" class="java.lang.String" itemvalue="3.12" />
+            <item index="4" class="java.lang.String" itemvalue="3.13" />
+          </list>
+        </value>
+      </option>
+    </inspection_tool>
+    <inspection_tool class="PyMandatoryEncodingInspection" enabled="true" level="WARNING" enabled_by_default="true" />
+    <inspection_tool class="PyMissingOrEmptyDocstringInspection" enabled="true" level="WEAK WARNING" enabled_by_default="true" />
+    <inspection_tool class="PyMissingTypeHintsInspection" enabled="true" level="WARNING" enabled_by_default="true" editorAttributes="WARNING_ATTRIBUTES" />
+    <inspection_tool class="PyPep8NamingInspection" enabled="true" level="WEAK WARNING" enabled_by_default="true">
+      <option name="ignoredErrors">
+        <list>
+          <option value="N812" />
+        </list>
+      </option>
+    </inspection_tool>
+    <inspection_tool class="PyTypeCheckerInspection" enabled="false" level="WARNING" enabled_by_default="false" />
+    <inspection_tool class="PydanticTypeCheckerInspection" enabled="true" level="WARNING" enabled_by_default="true" />
+    <inspection_tool class="RegExpAnonymousGroup" enabled="true" level="WARNING" enabled_by_default="true" />
+    <inspection_tool class="ReservedWordUsedAsNameJS" enabled="false" level="WARNING" enabled_by_default="false" />
+    <inspection_tool class="RestRoleInspection" enabled="true" level="WARNING" enabled_by_default="true">
+      <option name="ignoredRoles">
+        <value>
+          <list size="0" />
+        </value>
+      </option>
+    </inspection_tool>
+    <inspection_tool class="ReturnFromFinallyBlockJS" enabled="false" level="WARNING" enabled_by_default="false" />
+    <inspection_tool class="ShiftOutOfRangeJS" enabled="false" level="WARNING" enabled_by_default="false" />
+    <inspection_tool class="SillyAssignmentJS" enabled="false" level="WARNING" enabled_by_default="false" />
+    <inspection_tool class="SqlGotoInspection" enabled="true" level="WARNING" enabled_by_default="true" />
+    <inspection_tool class="SqlJoinCountInspection" enabled="true" level="WARNING" enabled_by_default="true" />
+    <inspection_tool class="SqlMissingColumnAliasesInspection" enabled="true" level="WARNING" enabled_by_default="true" />
+    <inspection_tool class="SqlNamedArgumentsInspection" enabled="true" level="WARNING" enabled_by_default="true" />
+    <inspection_tool class="Stylelint" enabled="true" level="ERROR" enabled_by_default="true" />
+    <inspection_tool class="SuspiciousTypeOfGuard" enabled="false" level="WARNING" enabled_by_default="false" />
+    <inspection_tool class="ThisExpressionReferencesGlobalObjectJS" enabled="false" level="WARNING" enabled_by_default="false" />
+    <inspection_tool class="ThrowFromFinallyBlockJS" enabled="false" level="WARNING" enabled_by_default="false" />
+    <inspection_tool class="TodoComment" enabled="true" level="WARNING" enabled_by_default="true" />
+    <inspection_tool class="TrivialConditionalJS" enabled="false" level="WARNING" enabled_by_default="false" />
+    <inspection_tool class="TrivialIfJS" enabled="false" level="WARNING" enabled_by_default="false" />
+    <inspection_tool class="TypeScriptAbstractClassConstructorCanBeMadeProtected" enabled="false" level="WEAK WARNING" enabled_by_default="false" />
+    <inspection_tool class="TypeScriptCheckImport" enabled="false" level="ERROR" enabled_by_default="false" />
+    <inspection_tool class="TypeScriptConfig" enabled="false" level="WARNING" enabled_by_default="false" />
+    <inspection_tool class="TypeScriptDuplicateUnionOrIntersectionType" enabled="false" level="WARNING" enabled_by_default="false" />
+    <inspection_tool class="TypeScriptExplicitMemberType" enabled="false" level="INFORMATION" enabled_by_default="false" />
+    <inspection_tool class="TypeScriptFieldCanBeMadeReadonly" enabled="false" level="WEAK WARNING" enabled_by_default="false" />
+    <inspection_tool class="TypeScriptJSXUnresolvedComponent" enabled="false" level="WEAK WARNING" enabled_by_default="false" />
+    <inspection_tool class="TypeScriptLibrary" enabled="false" level="ERROR" enabled_by_default="false" />
+    <inspection_tool class="TypeScriptMissingAugmentationImport" enabled="false" level="INFORMATION" enabled_by_default="false" />
+    <inspection_tool class="TypeScriptMissingConfigOption" enabled="false" level="WARNING" enabled_by_default="false" />
+    <inspection_tool class="TypeScriptRedundantGenericType" enabled="false" level="WEAK WARNING" enabled_by_default="false" />
+    <inspection_tool class="TypeScriptSmartCast" enabled="false" level="WARNING" enabled_by_default="false" />
+    <inspection_tool class="TypeScriptSuspiciousConstructorParameterAssignment" enabled="false" level="WARNING" enabled_by_default="false" />
+    <inspection_tool class="TypeScriptUMDGlobal" enabled="false" level="WEAK WARNING" enabled_by_default="false" />
+    <inspection_tool class="TypeScriptUnresolvedReference" enabled="false" level="ERROR" enabled_by_default="false" />
+    <inspection_tool class="TypeScriptValidateGenericTypes" enabled="false" level="ERROR" enabled_by_default="false" />
+    <inspection_tool class="TypeScriptValidateTypes" enabled="false" level="ERROR" enabled_by_default="false" />
+    <inspection_tool class="UnnecessaryContinueJS" enabled="false" level="WARNING" enabled_by_default="false" />
+    <inspection_tool class="UnnecessaryLabelJS" enabled="false" level="WARNING" enabled_by_default="false" />
+    <inspection_tool class="UnnecessaryLabelOnBreakStatementJS" enabled="false" level="WARNING" enabled_by_default="false" />
+    <inspection_tool class="UnnecessaryLabelOnContinueStatementJS" enabled="false" level="WARNING" enabled_by_default="false" />
+    <inspection_tool class="UnnecessaryLocalVariableJS" enabled="false" level="WARNING" enabled_by_default="false" />
+    <inspection_tool class="UnnecessaryReturnJS" enabled="false" level="WARNING" enabled_by_default="false" />
+    <inspection_tool class="UnreachableCodeJS" enabled="false" level="WARNING" enabled_by_default="false" />
+    <inspection_tool class="UnusedDefine" enabled="true" level="WARNING" enabled_by_default="true" />
+    <inspection_tool class="UpdateDependencyToLatestVersion" enabled="false" level="INFORMATION" enabled_by_default="false" />
+    <inspection_tool class="UseEllipsisInPropertyInspection" enabled="true" level="WARNING" enabled_by_default="true" />
+    <inspection_tool class="WebpackConfigHighlighting" enabled="false" level="WARNING" enabled_by_default="false" />
+    <inspection_tool class="WithStatementJS" enabled="false" level="WARNING" enabled_by_default="false" />
+  </profile>
+</component>

.idea/inspectionProfiles/profiles_settings.xml

@@ -0,0 +1,6 @@
+<component name="InspectionProjectProfileManager">
+  <settings>
+    <option name="USE_PROJECT_PROFILE" value="false" />
+    <version value="1.0" />
+  </settings>
+</component>

.idea/misc.xml

@@ -0,0 +1,13 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="Black">
+    <option name="sdkName" value="uv (chattr)" />
+  </component>
+  <component name="ProjectRootManager" version="2" project-jdk-name="uv (chattr)" project-jdk-type="Python SDK" />
+  <component name="RuffConfiguration">
+    <option name="enabled" value="true" />
+  </component>
+  <component name="TyConfiguration">
+    <option name="enabled" value="true" />
+  </component>
+</project>

.idea/modules.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="ProjectModuleManager">
+    <modules>
+      <module fileurl="file://$PROJECT_DIR$/.idea/chattr.iml" filepath="$PROJECT_DIR$/.idea/chattr.iml" />
+    </modules>
+  </component>
+</project>

.idea/vcs.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="VcsDirectoryMappings">
+    <mapping directory="" vcs="Git" />
+  </component>
+</project>

.pre-commit-config.yaml

@@ -0,0 +1,118 @@
+repos:
+  - repo: https://github.com/Mergifyio/mergify-pre-commit
+    rev: 1.1.0
+    hooks:
+      - id: validate-mergify-config-location
+      - id: validate-mergify-config
+  - repo: https://github.com/ComPWA/taplo-pre-commit
+    rev: v0.9.3
+    hooks:
+      - id: taplo-format
+        args:
+          - --config
+          - .github/lint/.taplo.toml
+      - id: taplo-lint
+        args:
+          - --config
+          - .github/lint/.taplo.toml
+          - --default-schema-catalogs
+  - repo: https://github.com/igorshubovych/markdownlint-cli
+    rev: v0.47.0
+    hooks:
+      - id: markdownlint
+        args:
+          - --config
+          - .github/lint/.markdownlint.yaml
+      - id: markdownlint-fix
+        args:
+          - --config
+          - .github/lint/.markdownlint.yaml
+  - repo: https://github.com/adrienverge/yamllint
+    rev: v1.38.0
+    hooks:
+      - id: yamllint
+        args:
+          - --strict
+          - -c
+          - .github/lint/.yamllint.yaml
+  - repo: https://github.com/docker-compose-linter/pre-commit-dclint
+    rev: v3.1.0
+    hooks:
+      - id: dclint
+        args:
+          - --fix
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: check-yaml
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+      - id: check-added-large-files
+      - id: check-ast
+      - id: check-illegal-windows-names
+      - id: check-json
+      - id: check-merge-conflict
+        args:
+          - --assume-in-merge
+      - id: check-symlinks
+      - id: check-toml
+      - id: check-vcs-permalinks
+      - id: check-xml
+      - id: debug-statements
+      - id: destroyed-symlinks
+      - id: detect-private-key
+      - id: mixed-line-ending
+        args:
+          - --fix=lf
+      - id: pretty-format-json
+        args:
+          - --autofix
+  - repo: https://github.com/renovatebot/pre-commit-hooks
+    rev: 43.0.5
+    hooks:
+      - id: renovate-config-validator
+        args:
+          - --strict
+  - repo: https://github.com/astral-sh/uv-pre-commit
+    rev: 0.9.28
+    hooks:
+      - id: uv-lock
+      - id: uv-sync
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.14.14
+    hooks:
+      - id: ruff-check
+        args:
+          - --fix
+          - --config
+          - .github/lint/.ruff.toml
+      - id: ruff-format
+        args:
+          - --config
+          - .github/lint/.ruff.toml
+  - repo: https://github.com/facebook/pyrefly-pre-commit
+    rev: 0.50.1
+    hooks:
+      - id: pyrefly-check
+  - repo: https://github.com/lyz-code/yamlfix
+    rev: 1.19.1
+    hooks:
+      - id: yamlfix
+        args:
+          - -c
+          - .github/lint/.yamlfix.toml
+  - repo: https://github.com/rhysd/actionlint
+    rev: v1.7.10
+    hooks:
+      - id: actionlint-docker
+  - repo: https://github.com/trufflesecurity/trufflehog
+    rev: v3.92.5
+    hooks:
+      - id: trufflehog
+  - repo: https://github.com/hadolint/hadolint
+    rev: v2.14.0
+    hooks:
+      - id: hadolint-docker
+        args:
+          - -c
+          - .github/lint/.hadolint.yaml

.sonarlint/connectedMode.json

@@ -0,0 +1,5 @@
+{
+  "projectKey": "AlphaSphereDotAI_chatacter_backend_app",
+  "region": "EU",
+  "sonarCloudOrganization": "alphaspheredotai"
+}

.vscode/launch.json

@@ -0,0 +1,19 @@
+{
+    // Use IntelliSense to learn about possible attributes.
+    // Hover to view descriptions of existing attributes.
+    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "run: server",
+            "type": "debugpy",
+            "request": "launch",
+            "module": "${workspaceFolderBasename}",
+            "preLaunchTask": "uv sync",
+            "logToFile": true,
+            "env": {
+                "DOPPLER_ENV": "1"
+            }
+        }
+    ]
+}

.vscode/tasks.json

@@ -0,0 +1,15 @@
+{
+    // See https://go.microsoft.com/fwlink/?LinkId=733558
+    // for the documentation about the tasks.json format
+    "version": "2.0.0",
+    "tasks": [
+        {
+            "label": "uv sync",
+            "type": "shell",
+            "command": "uv",
+            "args": [
+                "sync"
+            ]
+        }
+    ]
+}

.zed/tasks.json

@@ -0,0 +1,24 @@
+[
+  {
+    "args": [
+      "run",
+      "chattr"
+    ],
+    "command": "uv",
+    "label": "Run Chattr",
+    "reveal_target": "center",
+    "shell": "system"
+  },
+  {
+    "args": [
+      "compose",
+      "-f",
+      "compose-dev.yaml",
+      "up"
+    ],
+    "command": "docker",
+    "label": "Run Docker Compose",
+    "reveal_target": "center",
+    "shell": "system"
+  }
+]

AGENTS.md

@@ -0,0 +1,133 @@
+# Agent Guidelines for Chattr
+
+[byterover-mcp]
+
+## Byterover MCP Server Tools Reference
+
+There are two main workflows with Byterover tools and recommended tool call strategies that you **MUST** follow precisely.
+
+### Onboarding workflow
+
+If users particularly ask you to start the onboarding process, you **MUST STRICTLY** follow these steps.
+
+1. **ALWAYS USE** **byterover-check-handbook-existence** first to check if the byterover handbook already exists. If not, You **MUST** call **byterover-create-handbook** to create the byterover handbook.
+2. If the byterover handbook already exists, first you **MUST** USE **byterover-check-handbook-sync** to analyze the gap between the current codebase and the existing byterover handbook.
+3. Then **IMMEDIATELY USE** **byterover-update-handbook** to update these changes to the byterover handbook.
+4. During the onboarding, you **MUST** use **byterover-list-modules** **FIRST** to get the available modules, and then **byterover-store-modules** and **byterover-update-modules** if there are new modules or changes to existing modules in the project.
+
+### Planning workflow
+
+Based on user request, you **MUST** follow these sequences of tool calls
+
+1. If asked to continue an unfinished implementation, **CALL** **byterover-retrieve-active-plans** to find the most relevant active plan.
+2. **CRITICAL PLAN PERSISTENCE RULE**: Once a user approves a plan, you **MUST IMMEDIATELY CALL** **byterover-save-implementation-plan** to save it.
+3. Throughout the plan, you **MUST** run **byterover-retrieve-knowledge** several times to retrieve sufficient knowledge and context for the plan's tasks.
+4. In addition, you might need to run **byterover-search-modules** and **byterover-update-modules** if the tasks require or update knowledge about certain modules. However, **byterover-retrieve-knowledge** should **ALWAYS** be considered **FIRST**.
+5. **MUST** use **byterover-update-plan-progress** to mark tasks (and then the whole plan) as completed.
+   Example:
+
+- Task: `byterover-update-plan-progress(plan_name="Feature X", task_name="Task 1", is_completed=true)`
+- All done: `byterover-update-plan-progress(plan_name="Feature X", is_completed=true)`
+
+1. Then, you might call **byterover-store-knowledge** to save knowledge and experience implemented throughout the plan or in important tasks.
+2. During the plan's implementation, you **MUST** frequently call **byterover-think-about-collected-information** and **byterover-assess-context-completeness** to make sure you're on the right track and gather sufficient context for the tasks.
+
+### Recommended Workflow Sequence
+
+1. **MOST IMPORTANT**: **ALWAYS USE** **byterover-retrieve-knowledge** once or several times for **EACH TASK** of the plan to gather necessary context to complete that task.
+2. **MOST IMPORTANT**: **ALWAYS USE** **byterover-store-knowledge** once or several times to store critical knowledge and context for future implementations
+3. Over 15 provided tools, **byterover-retrieve-knowledge** and **byterover-store-knowledge** ARE the two main tools, which **MUST** be used regularly. You can use these two main tools outside the two main workflows for retrieval and storage purposes.
+4. You **MUST** include phrases like **"According to Byterover memory layer"**, **"Based on memory extracted from Byterover"**, **"From Byterover memory tools"**, ... to explicitly showcase that these sources are from **Byterover**.
+5. **Implementation & Progress Tracking** → Execute implementation following saved plan → Mark tasks complete as you go → Mark entire plan done when all tasks finished.
+6. You **MUST** use **byterover-update-module** **IMMEDIATELY** on changes to the module's purposes, technical details, or critical insights that essential for future implementations.
+
+## Build/Lint/Test Commands
+
+### Installation
+
+```bash
+uv sync  # Install dependencies
+```
+
+### Building
+
+```bash
+uv build  # Build source and wheel distributions
+```
+
+### Linting & Formatting
+
+```bash
+trunk fmt --all --no-progress  # Auto-format code
+trunk check  # Run all linters and checks
+```
+
+### Testing
+
+```bash
+pytest  # Run all tests
+pytest tests/test_app.py::test_app  # Run single test
+```
+
+## Code Style Guidelines
+
+### General
+
+- **Line length**: 88 characters
+- **Indentation**: 4 spaces
+- **Quote style**: Double quotes (`"`)
+- **File encoding**: UTF-8
+
+### Imports
+
+- Use `from __future__ import annotations` when needed
+- Group imports: standard library, third-party, local
+- Use `TYPE_CHECKING` for conditional imports
+- Combine as imports: `from typing import Dict, List` → `from typing import Dict, List`
+
+### Type Hints
+
+- Use type hints for all function parameters and return values
+- Use `Self` for methods returning the same class instance
+- Use `Sequence`, `list`, `dict` instead of bare generics
+- Use `Path` from `pathlib` for file paths
+
+### Naming Conventions
+
+- **Functions/Methods**: `snake_case`
+- **Variables**: `snake_case`
+- **Classes**: `PascalCase`
+- **Constants**: `UPPER_CASE`
+- **Private attributes**: `_leading_underscore`
+
+### Error Handling
+
+- Use specific exception types (e.g., `OSError`, `ValueError`, `ValidationError`)
+- Log errors with appropriate levels (`logger.error`, `logger.warning`)
+- Raise `Error` from gradio for user-facing errors
+- Use try/except blocks with meaningful error messages
+
+### Async/Await
+
+- Use `async def` for coroutines
+- Use `await` for async operations
+- Return `AsyncGenerator` for streaming responses
+
+### Documentation
+
+- Use docstrings for all public functions, classes, and modules
+- Follow Google-style docstring format
+- Document parameters, return values, and exceptions
+
+### Logging
+
+- Import logger from module settings
+- Use appropriate log levels: `debug`, `info`, `warning`, `error`
+- Include relevant context in log messages
+
+### Testing Guidelines
+
+- Use `pytest` framework
+- Test functions named `test_*`
+- Use descriptive assertions
+- Mock external dependencies when needed

Dockerfile

@@ -0,0 +1,32 @@
+FROM cgr.dev/chainguard/wolfi-base:latest@sha256:17ab0709456ce1a2aedd85e95f72e58d73133bb70c33ae945a4d4b2424e984f1 AS builder
+
+ARG INSTALL_SOURCE
+ARG PYTHON_VERSION
+
+# skipcq: DOK-DL3018
+RUN apk add --no-cache build-base git uv
+
+USER nonroot
+
+RUN --mount=type=cache,target=/root/.cache/uv \
+    uv tool install ${INSTALL_SOURCE} --python ${PYTHON_VERSION}
+
+FROM cgr.dev/chainguard/wolfi-base:latest@sha256:17ab0709456ce1a2aedd85e95f72e58d73133bb70c33ae945a4d4b2424e984f1 AS production
+
+ENV GRADIO_SERVER_PORT=7860 \
+    GRADIO_SERVER_NAME=0.0.0.0 \
+    FASTEMBED_CACHE_PATH=/home/nonroot/fastembed \
+    PATH=/home/nonroot/.local/bin:$PATH
+
+# skipcq: DOK-DL3018
+RUN apk add --no-cache curl libstdc++
+
+USER nonroot
+
+WORKDIR /home/nonroot
+
+COPY --from=builder --chown=nonroot:nonroot --chmod=555 /home/nonroot/.local/ /home/nonroot/.local/
+
+EXPOSE ${GRADIO_SERVER_PORT}
+
+CMD ["chattr"]

README.md

@@ -1,12 +1,38 @@
 ---
 title: Chattr
-emoji: 🐠
-colorFrom: blue
-colorTo: indigo
-sdk: gradio
-sdk_version: 6.5.1
-app_file: app.py
-pinned: false
+emoji: 💬
+colorFrom: gray
+colorTo: blue
+sdk: docker
+app_port: 7860
+short_description: Chat with Characters
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+## **Chattr**: App part of the Chatacter Backend
+
+[![Build](https://github.com/AlphaSphereDotAI/chattr/actions/workflows/build.yaml/badge.svg)](https://github.com/AlphaSphereDotAI/chattr/actions/workflows/build.yaml)
+[![CI Tools](https://github.com/AlphaSphereDotAI/chattr/actions/workflows/ci_tools.yaml/badge.svg)](https://github.com/AlphaSphereDotAI/chattr/actions/workflows/ci_tools.yaml)
+[![CodeQL](https://github.com/AlphaSphereDotAI/chattr/actions/workflows/github-code-scanning/codeql/badge.svg)](https://github.com/AlphaSphereDotAI/chattr/actions/workflows/github-code-scanning/codeql)
+[![Dependabot Updates](https://github.com/AlphaSphereDotAI/chattr/actions/workflows/dependabot/dependabot-updates/badge.svg)](https://github.com/AlphaSphereDotAI/chattr/actions/workflows/dependabot/dependabot-updates)
+[![Release](https://github.com/AlphaSphereDotAI/chattr/actions/workflows/release.yaml/badge.svg)](https://github.com/AlphaSphereDotAI/chattr/actions/workflows/release.yaml)
+[![Test](https://github.com/AlphaSphereDotAI/chattr/actions/workflows/test.yaml/badge.svg)](https://github.com/AlphaSphereDotAI/chattr/actions/workflows/test.yaml)
+
+### Environment Variables
+
+The configuration of the server is done using environment variables:
+
+| Name                       | Description                      | Required | Default Value                              |
+|:---------------------------|:---------------------------------|:--------:|:-------------------------------------------|
+| `MODEL__URL`               | OpenAI-compatible endpoint       |    ✘     | `https://api.groq.com/openai/v1`           |
+| `MODEL__NAME`              | Model name to use for chat       |    ✘     | `llama3-70b-8192`                          |
+| `MODEL__API_KEY`           | API key for model access         |    ✔     | `None`                                     |
+| `MODEL__TEMPERATURE`       | Model temperature (0.0-1.0)      |    ✘     | `0.0`                                      |
+| `SHORT_TERM_MEMORY__URL`   | Redis URL for memory store       |    ✘     | `redis://localhost:6379`                   |
+| `VECTOR_DATABASE__NAME`    | Vector database collection name  |    ✘     | `chattr`                                   |
+| `VOICE_GENERATOR_MCP__URL` | MCP service for audio generation |    ✘     | `http://localhost:8001/gradio_api/mcp/sse` |
+| `VIDEO_GENERATOR_MCP__URL` | MCP service for video generation |    ✘     | `http://localhost:8002/gradio_api/mcp/sse` |
+| `DIRECTORY__ASSETS`        | Base assets directory            |    ✘     | `./assets`                                 |
+| `DIRECTORY__LOG`           | Log files directory              |    ✘     | `./logs`                                   |
+| `DIRECTORY__IMAGE`         | Image assets directory           |    ✘     | `./assets/image`                           |
+| `DIRECTORY__AUDIO`         | Audio assets directory           |    ✘     | `./assets/audio`                           |
+| `DIRECTORY__VIDEO`         | Video assets directory           |    ✘     | `./assets/video`                           |

assets/prompts/template.poml

@@ -0,0 +1,30 @@
+<poml syntax="markdown">
+  <role speaker="system">
+    You are a helpful assistant who can act and mimic {{character}}'s character and answer questions about the era.
+  </role>
+  <task speaker="system">
+    Always respond to the user's query by first generating your text answer, then using an MCP to generate audio from that text, and finally using an MCP to create a video from that audio.
+    <br />
+    <b>Crucially, your final output MUST include the generated text response, followed by the tool call for the video creation.</b>
+    <list>
+    <item><b>Personality:</b> Adopt the voice, tone, and perspective of {{character}}.</item>
+    <item><b>Knowledge:</b> Answer questions about the {{character}} era, military campaigns, and French history relevant to his life.</item>
+    </list>
+    <stepwise-instructions>
+      <list>
+        <item>Understand the user's question and context.</item>
+        <item>Gather relevant information and resources.</item>
+        <item>Formulate a clear and concise response in {{character}}'s voice.</item>
+        <item><b>ALWAYS</b> generate audio from the formulated response using the appropriate MCP.</item>
+        <item><b>ALWAYS</b> create a video file from the generated audio using the appropriate MCP.</item>
+      </list>
+    </stepwise-instructions>
+  </task>
+  <output-format>
+   Your response structure MUST be:
+     <list>
+    <item><b>[{{character}}'s Text Response]</b></item>
+    <item><b>[Tool Call to generate the video, which implicitly includes the audio generation step]</b></item>
+    </list>
+  </output-format>
+</poml>

docker-compose-dev.yaml

@@ -0,0 +1,97 @@
+name: Chattr Dev
+services:
+  vector_database:
+    image: qdrant/qdrant:latest@sha256:0425e3e03e7fd9b3dc95c4214546afe19de2eb2e28ca621441a56663ac6e1f46
+    ports:
+      - 6333:6333
+      - 6334:6334
+    volumes:
+      - qdrant_storage:/qdrant/storage
+    restart: on-failure:3
+  voice_generator:
+    image: ghcr.io/alphaspheredotai/vocalizr:latest@sha256:df1f4fa0615ae3f34249454ddc3a74e3fd955332da507ff2c7d5373190037863
+    ports:
+      - 7861:7860
+    post_start:
+      - command: chown -R nonroot:nonroot /home/nonroot
+        user: root
+      - command: chmod -R 700 /home/nonroot
+        user: root
+    volumes:
+      - huggingface:/home/nonroot/hf
+      - results:/home/nonroot/results
+      - logs:/home/nonroot/logs
+    restart: on-failure:3
+    environment:
+      GRADIO_DEBUG: 1
+    healthcheck:
+      test:
+        - CMD
+        - curl
+        - -o
+        - /dev/null
+        - -f
+        - -s
+        - -w
+        - "'Status: %{http_code},\tTime: %{time_total}s'"
+        - http://localhost:7860/
+      interval: 1m30s
+      timeout: 10s
+      retries: 5
+      start_period: 40s
+    deploy:
+      resources:
+        reservations:
+          devices:
+            - driver: nvidia
+              count: all
+              capabilities:
+                - gpu
+  video_generator:
+    image: ghcr.io/alphaspheredotai/visualizr:latest@sha256:2c5b096a66c6ebee1a5c0242a8b42c393e0cfdcda086ae6ceba11f92618ec7aa
+    ports:
+      - 7862:7860
+    volumes:
+      - assets:/home/nonroot/assets
+      - checkpoint:/home/nonroot/ckpts
+      - gfpgan:/home/nonroot/gfpgan
+    post_start:
+      - command: chown -R nonroot:nonroot /home/nonroot
+        user: root
+      - command: chmod -R 700 /home/nonroot
+        user: root
+    restart: on-failure:3
+    environment:
+      GRADIO_DEBUG: 1
+    healthcheck:
+      test:
+        - CMD
+        - curl
+        - -o
+        - /dev/null
+        - -f
+        - -s
+        - -w
+        - "'Status: %{http_code},\tTime: %{time_total}s'"
+        - http://localhost:7860/
+      interval: 1m30s
+      timeout: 10s
+      retries: 5
+      start_period: 40s
+    deploy:
+      resources:
+        reservations:
+          devices:
+            - driver: nvidia
+              count: all
+              capabilities:
+                - gpu
+volumes:
+  logs:
+  assets:
+  fastembed:
+  qdrant_storage:
+  checkpoint:
+  gfpgan:
+  huggingface:
+  results:

docker-compose.yaml

@@ -0,0 +1,126 @@
+name: Chattr
+services:
+  chattr:
+    image: alphaspheredotai/chattr:latest@sha256:094981de2f6cbad9b42bbde8147a1278af0e5a681b1d1903c497e1cd6e8dcb2c
+    volumes:
+      - logs:/home/nonroot/logs
+      - assets:/home/nonroot/assets
+      - fastembed:/home/nonroot/fastembed
+    environment:
+      MODEL__URL: ${MODEL__URL:-https://generativelanguage.googleapis.com/v1beta/openai}
+      MODEL__NAME: ${MODEL__NAME:-gemini-2.5-flash}
+      MODEL__API_KEY: ${MODEL__API_KEY}
+      VECTOR_DATABASE__URL: http://vector_database:6333
+      VECTOR_DATABASE__NAME: main
+    ports:
+      - 7860:7860
+    restart: on-failure:3
+    healthcheck:
+      test:
+        - CMD
+        - curl
+        - -o
+        - /dev/null
+        - -f
+        - -s
+        - -w
+        - "'Status: %{http_code},\tTime: %{time_total}s'"
+        - http://localhost:7860/
+      interval: 1m30s
+      timeout: 10s
+      retries: 5
+      start_period: 40s
+    post_start:
+      - command: chown -R nonroot:nonroot /home/nonroot
+        user: root
+      - command: chmod -R 700 /home/nonroot
+        user: root
+  vector_database:
+    image: qdrant/qdrant:latest@sha256:0425e3e03e7fd9b3dc95c4214546afe19de2eb2e28ca621441a56663ac6e1f46
+    volumes:
+      - qdrant_storage:/qdrant/storage
+    ports:
+      - 6333:6333
+      - 6334:6334
+    restart: on-failure:3
+  video_generator:
+    image: alphaspheredotai/visualizr:latest@sha256:d1f5c97d9babdbdd45ca26b6ec42a128b612921295de13d77cb7e36fe638bb55
+    volumes:
+      - assets:/home/nonroot/assets
+      - checkpoint:/home/nonroot/ckpts
+      - gfpgan:/home/nonroot/gfpgan
+    ports:
+      - 7862:7860
+    restart: on-failure:3
+    healthcheck:
+      test:
+        - CMD
+        - curl
+        - -o
+        - /dev/null
+        - -f
+        - -s
+        - -w
+        - "'Status: %{http_code},\tTime: %{time_total}s'"
+        - http://localhost:7860/
+      interval: 1m30s
+      timeout: 10s
+      retries: 5
+      start_period: 40s
+    deploy:
+      resources:
+        reservations:
+          devices:
+            - driver: nvidia
+              count: all
+              capabilities:
+                - gpu
+    post_start:
+      - command: chown -R nonroot:nonroot /home/nonroot
+        user: root
+      - command: chmod -R 700 /home/nonroot
+        user: root
+  voice_generator:
+    image: alphaspheredotai/vocalizr:latest@sha256:e508d563372b08766b9dd38f462c97ec831d5563922255baf911b2c821a77c8a
+    volumes:
+      - huggingface:/home/nonroot/hf
+      - results:/home/nonroot/results
+      - logs:/home/nonroot/logs
+    ports:
+      - 7861:7860
+    restart: on-failure:3
+    healthcheck:
+      test:
+        - CMD
+        - curl
+        - -o
+        - /dev/null
+        - -f
+        - -s
+        - -w
+        - "'Status: %{http_code},\tTime: %{time_total}s'"
+        - http://localhost:7860/
+      interval: 1m30s
+      timeout: 10s
+      retries: 5
+      start_period: 40s
+    deploy:
+      resources:
+        reservations:
+          devices:
+            - driver: nvidia
+              count: all
+              capabilities:
+                - gpu
+    post_start:
+      - command: chown -R nonroot:nonroot /home/nonroot
+        user: root
+      - command: chmod -R 700 /home/nonroot
+        user: root
+volumes:
+  logs:
+  assets:
+  fastembed:
+  qdrant_storage:
+  checkpoint:
+  gfpgan:

mcp.json

@@ -0,0 +1,40 @@
+{
+  "mcp_servers": [
+    {
+      "args": [
+        "run",
+        "-i",
+        "--rm",
+        "mcp/time"
+      ],
+      "command": "docker",
+      "name": "time",
+      "transport": "stdio",
+      "type": "command"
+    },
+    {
+      "args": [
+        "run",
+        "-i",
+        "--rm",
+        "mcp/sequentialthinking"
+      ],
+      "command": "docker",
+      "name": "sequential_thinking",
+      "transport": "stdio",
+      "type": "command"
+    },
+    {
+      "name": "voice_generator",
+      "transport": "streamable-http",
+      "type": "url",
+      "url": "http://localhost:7861/gradio_api/mcp"
+    },
+    {
+      "name": "video_generator",
+      "transport": "streamable-http",
+      "type": "url",
+      "url": "http://localhost:7862/gradio_api/mcp/?tools=generate_video_mcp"
+    }
+  ]
+}

pyproject.toml

@@ -0,0 +1,41 @@
+[project]
+  authors = [
+    { email = "mohamed.hisham.abdelzaher@gmail.com", name = "Mohamed Hisham Abdelzaher" },
+  ]
+  dependencies = [
+    "agno[google,qdrant]>=2.4.7",
+    "ddgs>=9.10.0",
+    "fastembed>=0.7.4",
+    "gradio[mcp]>=6.5.1",
+    "m3u8>=6.0.0",
+    "mem0ai>=1.0.2",
+    "poml>=0.0.8",
+    "rich>=14.3.1",
+  ]
+  description = "App part of the Chatacter Backend"
+  name = "chattr"
+  readme = "README.md"
+  requires-python = ">=3.13,<3.14"
+  version = "0.0.103"
+
+  [project.scripts]
+    chattr = "chattr.__main__:main"
+
+[build-system]
+  build-backend = "uv_build"
+  requires = ["uv_build"]
+
+[dependency-groups]
+  dev = [
+    "doppler-env>=0.3.1",
+    "pre-commit>=4.5.1",
+    "pytest-emoji>=0.2.0",
+    "pytest-md>=0.2.0",
+    "pytest-mergify>=2026.1.26.1",
+    "ruff>=0.14.14",
+    "ty>=0.0.14",
+    "uv-build>=0.9.28",
+  ]
+
+[tool.ruff]
+  extend = ".github/lint/.ruff.toml"

src/chattr/__init__.py

@@ -0,0 +1,8 @@
+from warnings import filterwarnings
+
+from rich.console import Console
+
+filterwarnings("ignore", category=DeprecationWarning)
+
+console = Console()
+APP_NAME: str = __package__

src/chattr/__main__.py

@@ -0,0 +1,22 @@
+from typing import TYPE_CHECKING
+
+from chattr.app.runner import app
+
+if TYPE_CHECKING:
+    from gradio import Blocks
+
+
+def main() -> None:
+    """Launch the Gradio Multi-agent system app."""
+    application: Blocks = app.gui()
+    application.queue(api_open=True)
+    application.launch(
+        debug=True,
+        enable_monitoring=True,
+        show_error=True,
+        pwa=True,
+    )
+
+
+if __name__ == "__main__":
+    main()

src/chattr/app/__init__.py

@@ -0,0 +1,3 @@
+from gradio.processing_utils import PUBLIC_HOSTNAME_WHITELIST
+
+PUBLIC_HOSTNAME_WHITELIST.append("localhost")

src/chattr/app/builder.py

@@ -0,0 +1,323 @@
+"""Main orchestration graph for the Chattr application."""
+
+from collections.abc import AsyncGenerator
+from json import dumps, loads
+from pathlib import Path
+
+from agno.agent import (
+    Agent,
+    RunContentEvent,
+    ToolCallCompletedEvent,
+    ToolCallStartedEvent,
+)
+from agno.db import BaseDb
+from agno.db.json import JsonDb
+from agno.guardrails import PIIDetectionGuardrail, PromptInjectionGuardrail
+from agno.knowledge.knowledge import Knowledge
+from agno.models.message import Message
+from agno.models.openai.like import OpenAILike
+from agno.tools import Toolkit
+from agno.tools.mcp import MultiMCPTools
+from agno.vectordb.qdrant import Qdrant
+from gradio import (
+    Audio,
+    Blocks,
+    ChatInterface,
+    ChatMessage,
+    Error,
+    Video,
+)
+from gradio.components.chatbot import MetadataDict
+from m3u8 import M3U8, load
+from poml import poml
+from pydantic import HttpUrl, ValidationError
+from requests import Session
+from rich.pretty import pprint
+
+from chattr.app.settings import Settings, logger
+
+
+class App:
+    """Main application class for the Chattr Multi-agent system app."""
+
+    def __init__(self, settings: Settings) -> None:
+        self.settings = settings
+
+    async def _setup_agent(self) -> Agent:
+        return Agent(
+            model=self._setup_model(),
+            tools=await self._setup_tools(),
+            description="You are a helpful assistant who can act and mimic Napoleon's character and answer questions about the era.",
+            instructions=[
+                "Understand the user's question and context.",
+                "Gather relevant information and resources.",
+                "Formulate a clear and concise response in Napoleon's voice.",
+                "ALWAYS generate audio from the formulated response using the appropriate Tool.",
+                "Generate video from the resulted audio using the appropriate Tool.",
+            ],
+            db=self._setup_database(),
+            knowledge=self._setup_knowledge(
+                self._setup_vector_database(),
+                self._setup_database(),
+            ),
+            markdown=True,
+            add_datetime_to_context=True,
+            timezone_identifier="Africa/Cairo",
+            pre_hooks=[PIIDetectionGuardrail(), PromptInjectionGuardrail()],
+            debug_mode=True,
+            save_response_to_file="agno/response.txt",
+            add_history_to_context=True,
+            add_memories_to_context=True,
+        )
+
+    async def _setup_tools(self) -> list[Toolkit]:
+        mcp_servers: list[dict] = loads(self.settings.mcp.path.read_text()).get(
+            "mcp_servers",
+            [],
+        )
+        url_servers = [m for m in mcp_servers if m.get("type") == "url"]
+        self.mcp_tools = MultiMCPTools(
+            urls=[m.get("url") for m in url_servers],
+            urls_transports=[m.get("transport") for m in url_servers],
+        )
+        await self.mcp_tools.connect()
+        return [self.mcp_tools]
+
+    def _setup_prompt(self) -> str:
+        prompt_template = poml(
+            self.settings.directory.prompts / "template.poml",
+            {"character": "Napoleon"},
+            chat=False,
+            format="dict",
+        )
+        if not isinstance(prompt_template, dict):
+            _msg = "Prompt template must be a string."
+            raise TypeError(_msg)
+        return prompt_template["messages"]
+
+    def _setup_model(self) -> OpenAILike:
+        """
+        Initialize the ChatOpenAI language model using the provided settings.
+
+        This method creates and returns a ChatOpenAI instance configured with
+        the model's URL, name, API key, and temperature.
+
+        Returns:
+            ChatOpenAI: The initialized ChatOpenAI language model instance.
+
+        Raises:
+            Exception: If the model initialization fails.
+        """
+        try:
+            return OpenAILike(
+                base_url=str(self.settings.model.url),
+                id=self.settings.model.name,
+                api_key=self.settings.model.api_key.get_secret_value(),
+                temperature=self.settings.model.temperature,
+            )
+        except Exception as e:
+            _msg: str = f"Failed to initialize ChatOpenAI model: {e}"
+            logger.error(_msg)
+            raise Error(_msg) from e
+
+    def _setup_vector_database(self) -> Qdrant:
+        return Qdrant(
+            collection=self.settings.vector_database.name,
+            url=self.settings.vector_database.url.host,
+        )
+
+    def _setup_knowledge(self, vector_db: Qdrant, db: BaseDb) -> Knowledge:
+        return Knowledge(
+            vector_db=vector_db,
+            contents_db=db,
+        )
+
+    def _setup_database(self) -> JsonDb:
+        return JsonDb(
+            db_path="agno",
+        )
+
+    def gui(self) -> Blocks:
+        """
+        Create and return the main Gradio Blocks interface for the Chattr app.
+
+        Returns:
+            Blocks: The constructed Gradio Blocks interface for the chat application.
+        """
+        return ChatInterface(fn=self.generate_response, save_history=True)
+
+    async def generate_response(
+        self,
+        message: str,
+        history: list[ChatMessage],
+    ) -> AsyncGenerator[tuple[str, list[ChatMessage], Path | None, Path | None]]:
+        """
+        Generate a response to a user message and update the conversation history.
+
+        This asynchronous method streams responses from the state graph and
+        yields updated history and audio file paths as needed.
+
+        Args:
+            message: The user's input message as a string.
+            history: The conversation history as a list of ChatMessage objects.
+
+        Returns:
+            AsyncGenerator: Yields a tuple containing an
+                            empty string, the updated history, and
+                            a Path to an audio file if generated.
+        """
+        try:
+            agent: Agent = await self._setup_agent()
+            async for response in agent.arun(
+                Message(content=message, role="user"),
+                stream=True,
+            ):
+                pprint(response)
+                if isinstance(response, RunContentEvent):
+                    history.append(
+                        ChatMessage(
+                            role="assistant",
+                            content=response.content,
+                        ),
+                    )
+                elif isinstance(response, ToolCallStartedEvent):
+                    history.append(
+                        ChatMessage(
+                            role="assistant",
+                            content=dumps(response.tool.tool_args, indent=4),
+                            metadata=MetadataDict(
+                                title=response.tool.tool_name,
+                                id=response.tool.tool_call_id,
+                                duration=response.tool.created_at,
+                            ),
+                        ),
+                    )
+                elif isinstance(response, ToolCallCompletedEvent):
+                    if response.tool.tool_call_error:
+                        history.append(
+                            ChatMessage(
+                                role="assistant",
+                                content=dumps(response.tool.tool_args, indent=4),
+                                metadata=MetadataDict(
+                                    title=response.tool.tool_name,
+                                    id=response.tool.tool_call_id,
+                                    log="Tool Call Failed",
+                                    duration=response.tool.metrics.duration,
+                                ),
+                            ),
+                        )
+                    else:
+                        history.append(
+                            ChatMessage(
+                                role="assistant",
+                                content=dumps(response.tool.tool_args, indent=4),
+                                metadata=MetadataDict(
+                                    title=response.tool.tool_name,
+                                    id=response.tool.tool_call_id,
+                                    log="Tool Call Succeeded",
+                                    duration=response.tool.metrics.duration,
+                                ),
+                            ),
+                        )
+                        if response.tool.tool_name == "generate_audio_for_text":
+                            history.append(
+                                Audio(
+                                    response.tool.result,
+                                    autoplay=True,
+                                    show_download_button=True,
+                                    show_share_button=True,
+                                ),
+                            )
+                        elif response.tool.tool_name == "generate_video_mcp":
+                            history.append(
+                                Video(
+                                    response.tool.result,
+                                    autoplay=True,
+                                    show_download_button=True,
+                                    show_share_button=True,
+                                ),
+                            )
+                        else:
+                            msg = f"Unknown tool name: {response.tool.tool_name}"
+                            raise Error(msg)
+                yield history
+        except Exception as e:
+            _msg: str = f"Error generating response: {e}"
+            logger.error(_msg)
+            raise Error(_msg) from e
+        finally:
+            await self._close()
+
+    def _is_url(self, value: str | None) -> bool:
+        """
+        Check if a string is a valid URL.
+
+        Args:
+            value: The string to check. Can be None.
+
+        Returns:
+            bool: True if the string is a valid URL, False otherwise.
+        """
+        if value is None:
+            return False
+
+        try:
+            _ = HttpUrl(value)
+        except ValidationError:
+            return False
+        return True
+
+    def _download_file(self, url: HttpUrl, path: Path) -> None:
+        """
+        Download a file from a URL and save it to a local path.
+
+        Args:
+            url: The URL to download the file from.
+            path: The local file path where the downloaded file will be saved.
+
+        Returns:
+            None
+
+        Raises:
+            requests.RequestException: If the HTTP request fails.
+            IOError: If file writing fails.
+        """
+        if str(url).endswith(".m3u8"):
+            _playlist: M3U8 = load(url)
+            url: str = str(url).replace("playlist.m3u8", _playlist.segments[0].uri)
+        logger.info(f"Downloading {url} to {path}")
+        session = Session()
+        response = session.get(url, stream=True, timeout=30)
+        response.raise_for_status()
+        with path.open("wb") as f:
+            for chunk in response.iter_content(chunk_size=8192):
+                if chunk:
+                    f.write(chunk)
+        logger.info(f"File downloaded to {path}")
+
+    async def _close(self) -> None:
+        try:
+            logger.info("Closing MCP tools...")
+            await self.mcp_tools.close()
+        except Exception as e:
+            msg: str = (
+                f"Error closing MCP tools: {e}, Check if the Tool services are running."
+            )
+            logger.error(msg)
+            raise Error(msg) from e
+
+
+async def test() -> None:
+    settings: Settings = Settings()
+    app: App = App(settings)
+    agent: Agent = await app._setup_agent()
+    try:
+        await agent.aprint_response("Hello!", debug_mode=True)
+    finally:
+        await app._close()
+
+
+if __name__ == "__main__":
+    import asyncio
+
+    asyncio.run(test())

src/chattr/app/logger.py

@@ -0,0 +1,19 @@
+from logging import INFO, WARNING, Logger, basicConfig, getLogger
+
+from rich.logging import RichHandler
+
+from chattr import APP_NAME, console
+
+basicConfig(
+    level=INFO,
+    handlers=[
+        RichHandler(
+            level=INFO,
+            console=console,
+            rich_tracebacks=True,
+        ),
+    ],
+    format="%(name)s | %(process)d | %(message)s",
+)
+getLogger("httpx").setLevel(WARNING)
+logger: Logger = getLogger(APP_NAME)