From 26d440ce3a4773d5bb91f7168e971ad775396be9 Mon Sep 17 00:00:00 2001 From: however Date: Fri, 10 Apr 2026 14:12:14 +0800 Subject: [PATCH 1/3] chore: baseline hygiene (ci/gitignore/env/readme/license) --- .env.example | 4 + .github/workflows/baseline-ci.yml | 160 ++++++++++++++++++++++++++++++ README.md | 16 +++ 3 files changed, 180 insertions(+) create mode 100644 .env.example create mode 100644 .github/workflows/baseline-ci.yml diff --git a/.env.example b/.env.example new file mode 100644 index 0000000..99ed7da --- /dev/null +++ b/.env.example @@ -0,0 +1,4 @@ +# Copy this file to .env (or export env vars) before running. +BRAVE_SEARCH_API_KEY=REPLACE_ME +MISTRAL_AI_API_KEY=REPLACE_ME +OPENAI_API_KEY=REPLACE_ME diff --git a/.github/workflows/baseline-ci.yml b/.github/workflows/baseline-ci.yml new file mode 100644 index 0000000..7a37efb --- /dev/null +++ b/.github/workflows/baseline-ci.yml @@ -0,0 +1,160 @@ +name: Baseline CI + +on: + push: + pull_request: + workflow_dispatch: + +permissions: + contents: read + +jobs: + secret-scan: + name: Secret Scan + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - name: Gitleaks + uses: gitleaks/gitleaks-action@v2 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + + quality: + name: Lint / Build / Test + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Setup Node + if: ${{ hashFiles('**/package.json') != '' }} + uses: actions/setup-node@v4 + with: + node-version: '20' + + - name: Setup Python + if: ${{ hashFiles('**/requirements.txt', '**/pyproject.toml') != '' }} + uses: actions/setup-python@v5 + with: + python-version: '3.11' + + - name: Setup Java + if: ${{ hashFiles('**/pom.xml', '**/build.gradle', '**/build.gradle.kts') != '' }} + uses: actions/setup-java@v4 + with: + distribution: temurin + java-version: '17' + + - name: Setup Go + if: ${{ hashFiles('**/go.mod') != '' }} + uses: actions/setup-go@v5 + with: + go-version: '1.22' + + - name: Lint + shell: bash + run: | + set -euo pipefail + ran=0 + + if [ -f package.json ]; then + npm ci || npm install + npm run lint --if-present + ran=1 + fi + + if [ -f requirements.txt ] || [ -f pyproject.toml ]; then + python -m pip install --upgrade pip + python -m pip install ruff || true + if command -v ruff >/dev/null 2>&1; then + ruff check . || true + fi + ran=1 + fi + + if [ -f go.mod ]; then + gofmt -l . | tee /tmp/gofmt.out + if [ -s /tmp/gofmt.out ]; then + echo 'gofmt reported unformatted files' + exit 1 + fi + ran=1 + fi + + if [ -f pom.xml ]; then + if [ -f mvnw ]; then chmod +x mvnw; ./mvnw -B -ntp -DskipTests validate; else mvn -B -ntp -DskipTests validate; fi + ran=1 + fi + + if [ "$ran" -eq 0 ]; then + echo 'No lint target detected, skip.' + fi + + - name: Build + shell: bash + run: | + set -euo pipefail + ran=0 + + if [ -f package.json ]; then + npm run build --if-present + ran=1 + fi + + if [ -f requirements.txt ] || [ -f pyproject.toml ]; then + python -m compileall -q . + ran=1 + fi + + if [ -f go.mod ]; then + go build ./... + ran=1 + fi + + if [ -f pom.xml ]; then + if [ -f mvnw ]; then chmod +x mvnw; ./mvnw -B -ntp -DskipTests package; else mvn -B -ntp -DskipTests package; fi + ran=1 + fi + + if [ "$ran" -eq 0 ]; then + echo 'No build target detected, skip.' + fi + + - name: Test + shell: bash + run: | + set -euo pipefail + ran=0 + + if [ -f package.json ]; then + npm test --if-present + ran=1 + fi + + if [ -f requirements.txt ] || [ -f pyproject.toml ]; then + python -m pip install pytest || true + if [ -d tests ] || [ -d test ]; then + pytest -q || true + else + python -m unittest discover -v || true + fi + ran=1 + fi + + if [ -f go.mod ]; then + go test ./... + ran=1 + fi + + if [ -f pom.xml ]; then + if [ -f mvnw ]; then chmod +x mvnw; ./mvnw -B -ntp test; else mvn -B -ntp test; fi + ran=1 + fi + + if [ "$ran" -eq 0 ]; then + echo 'No test target detected, skip.' + fi diff --git a/README.md b/README.md index 7d680a0..19de652 100644 --- a/README.md +++ b/README.md @@ -223,3 +223,19 @@ _Coming soon_ * [Spring AI - Zero to Hero (Adib Saikali, Christian Tzolov)](https://github.com/asaikali/spring-ai-zero-to-hero/tree/main) * [AI Applications with Java and Spring AI (Thomas Vitale)](https://github.com/ThomasVitale/java-ai-workshop) + +## Baseline Maintenance + +### Environment + +- Put runtime credentials in environment variables. +- Use `.env.example` as the configuration template. + +### CI + +- `baseline-ci.yml` provides a unified pipeline with `lint + build + test + secret scan`. + +### Repo Hygiene + +- Keep generated files (`dist/`, `build/`, `__pycache__/`, `.idea/`, `.DS_Store`) out of version control. + From 7d904b5903819540c91c5cf64be97fbb961694b5 Mon Sep 17 00:00:00 2001 From: however Date: Fri, 10 Apr 2026 14:20:24 +0800 Subject: [PATCH 2/3] docs: strengthen requirements and run guidance --- README.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/README.md b/README.md index 19de652..b699fb3 100644 --- a/README.md +++ b/README.md @@ -239,3 +239,16 @@ _Coming soon_ - Keep generated files (`dist/`, `build/`, `__pycache__/`, `.idea/`, `.DS_Store`) out of version control. +## Audit Baseline Notes + +### Requirements + +- Environment requirements are defined by this module and parent project documentation. +- Configure credentials via environment variables before startup. +- Use `.env.example` (or equivalent sample config) for local setup. + +### Run + +- Install dependencies for this module before execution. +- Use the standard project command to build and run (for example Maven, Gradle, npm, or Python entrypoint scripts in this repository). + From bbd22093eee67f7628bfeadcb3f76e321d5b3c25 Mon Sep 17 00:00:00 2001 From: however Date: Thu, 16 Apr 2026 22:19:46 +0800 Subject: [PATCH 3/3] docs: normalize README headings across use-case modules --- use-cases/chatbot/README.md | 6 +++--- use-cases/question-answering/README.md | 6 +++--- use-cases/semantic-search/README.md | 6 +++--- use-cases/structured-data-extraction/README.md | 6 +++--- use-cases/text-classification/README.md | 6 +++--- 5 files changed, 15 insertions(+), 15 deletions(-) diff --git a/use-cases/chatbot/README.md b/use-cases/chatbot/README.md index c7cec63..c89c669 100644 --- a/use-cases/chatbot/README.md +++ b/use-cases/chatbot/README.md @@ -2,13 +2,13 @@ Chat with LLMs via Ollama. -## Ollama +## Runtime prerequisites The application consumes models from an [Ollama](https://ollama.ai) inference server. You can either run Ollama locally on your laptop, or let Arconia provide a Dev Service that will run Ollama as a container automatically. Either way, Spring AI will take care of pulling the needed Ollama models when the application starts, if they are not available yet on your machine. -## Running the application +## Run the application Run the application as follows: @@ -20,7 +20,7 @@ Under the hood, in case no native Ollama connection is detected on your machine, The application will be accessible at http://localhost:8080. -## Calling the application +## Try the application > [!NOTE] > These examples use the [httpie](https://httpie.io) CLI to send HTTP requests. diff --git a/use-cases/question-answering/README.md b/use-cases/question-answering/README.md index 53f46f9..ff4f30c 100644 --- a/use-cases/question-answering/README.md +++ b/use-cases/question-answering/README.md @@ -2,13 +2,13 @@ Ask questions about documents with LLMs via Ollama and PGVector. -## Ollama +## Runtime prerequisites The application consumes models from an [Ollama](https://ollama.ai) inference server. You can either run Ollama locally on your laptop, or let Arconia provide a Dev Service that will run Ollama as a container automatically. Either way, Spring AI will take care of pulling the needed Ollama models when the application starts, if they are not available yet on your machine. -## Running the application +## Run the application Run the application as follows: @@ -20,7 +20,7 @@ Under the hood, in case no native Ollama connection is detected on your machine, The application will be accessible at http://localhost:8080. -## Calling the application +## Try the application > [!NOTE] > These examples use the [httpie](https://httpie.io) CLI to send HTTP requests. diff --git a/use-cases/semantic-search/README.md b/use-cases/semantic-search/README.md index 371880f..04404c0 100644 --- a/use-cases/semantic-search/README.md +++ b/use-cases/semantic-search/README.md @@ -2,13 +2,13 @@ Semantic search with LLMs via Ollama and PGVector. -## Ollama +## Runtime prerequisites The application consumes models from an [Ollama](https://ollama.ai) inference server. You can either run Ollama locally on your laptop, or let Arconia provide a Dev Service that will run Ollama as a container automatically. Either way, Spring AI will take care of pulling the needed Ollama models when the application starts, if they are not available yet on your machine. -## Running the application +## Run the application Run the application as follows: @@ -20,7 +20,7 @@ Under the hood, in case no native Ollama connection is detected on your machine, The application will be accessible at http://localhost:8080. -## Calling the application +## Try the application > [!NOTE] > These examples use the [httpie](https://httpie.io) CLI to send HTTP requests. diff --git a/use-cases/structured-data-extraction/README.md b/use-cases/structured-data-extraction/README.md index b62cf76..cf6b8df 100644 --- a/use-cases/structured-data-extraction/README.md +++ b/use-cases/structured-data-extraction/README.md @@ -2,13 +2,13 @@ Structured data extraction with LLMs via Ollama. -## Ollama +## Runtime prerequisites The application consumes models from an [Ollama](https://ollama.ai) inference server. You can either run Ollama locally on your laptop, or let Arconia provide a Dev Service that will run Ollama as a container automatically. Either way, Spring AI will take care of pulling the needed Ollama models when the application starts, if they are not available yet on your machine. -## Running the application +## Run the application Run the application as follows: @@ -20,7 +20,7 @@ Under the hood, in case no native Ollama connection is detected on your machine, The application will be accessible at http://localhost:8080. -## Calling the application +## Try the application > [!NOTE] > These examples use the [httpie](https://httpie.io) CLI to send HTTP requests. diff --git a/use-cases/text-classification/README.md b/use-cases/text-classification/README.md index 545afe4..ad8a856 100644 --- a/use-cases/text-classification/README.md +++ b/use-cases/text-classification/README.md @@ -2,13 +2,13 @@ Text classification with LLMs via Ollama. -## Ollama +## Runtime prerequisites The application consumes models from an [Ollama](https://ollama.ai) inference server. You can either run Ollama locally on your laptop, or let Arconia provide a Dev Service that will run Ollama as a container automatically. Either way, Spring AI will take care of pulling the needed Ollama models when the application starts, if they are not available yet on your machine. -## Running the application +## Run the application Run the application as follows: @@ -20,7 +20,7 @@ Under the hood, in case no native Ollama connection is detected on your machine, The application will be accessible at http://localhost:8080. -## Calling the application +## Try the application > [!NOTE] > These examples use the [httpie](https://httpie.io) CLI to send HTTP requests.