Merge pull request #10 from RadCod3/feat/langchain-stdio-support

Feat/langchain stdio support

Author: RadCod3

.github/workflows/python-interpreter.yml

@@ -73,12 +73,13 @@ jobs:
           OWNER_LOWER=$(echo "$OWNER" | tr '[:upper:]' '[:lower:]')
           echo "image_name=ghcr.io/$OWNER_LOWER/afm-langchain-interpreter" >> $GITHUB_OUTPUT
 
-      - name: Build and push Docker image
+      - name: Build and push full image
         uses: docker/build-push-action@v5
         with:
           context: python-interpreter
           push: true
           platforms: linux/amd64,linux/arm64
+          build-args: VARIANT=full
           tags: |
             ${{ steps.meta.outputs.image_name }}:latest
             ${{ steps.meta.outputs.image_name }}:${{ github.sha }}
@@ -90,3 +91,22 @@ jobs:
           annotations: |
             index:org.opencontainers.image.source=https://github.com/${{ github.repository }}
             index:org.opencontainers.image.licenses=Apache-2.0
+
+      - name: Build and push slim image
+        uses: docker/build-push-action@v5
+        with:
+          context: python-interpreter
+          push: true
+          platforms: linux/amd64,linux/arm64
+          build-args: VARIANT=slim
+          tags: |
+            ${{ steps.meta.outputs.image_name }}:slim
+            ${{ steps.meta.outputs.image_name }}:${{ github.sha }}-slim
+          labels: |
+            org.opencontainers.image.source=https://github.com/${{ github.repository }}
+            org.opencontainers.image.revision=${{ github.sha }}
+            org.opencontainers.image.title=AFM LangChain Interpreter (Slim)
+            org.opencontainers.image.licenses=Apache-2.0
+          annotations: |
+            index:org.opencontainers.image.source=https://github.com/${{ github.repository }}
+            index:org.opencontainers.image.licenses=Apache-2.0

.github/workflows/release-ballerina.yml

@@ -130,6 +130,7 @@ jobs:
     with:
       tag: ${{ needs.validate.outputs.tag }}
       implementation: ballerina-interpreter
+      package: ballerina-interpreter
       version: ${{ needs.validate.outputs.release_version }}
       branch: ${{ inputs.branch }}
       is_rerelease: false

.github/workflows/release-docker.yml

@@ -57,20 +57,23 @@ jobs:
           # GHCR requires lowercase repository names
           OWNER_LOWER=$(echo "$OWNER" | tr '[:upper:]' '[:lower:]')
           FULL_IMAGE="ghcr.io/$OWNER_LOWER/$IMAGE_NAME"
-          TAGS="$FULL_IMAGE:v$VERSION"
-          if [ "$UPDATE_LATEST" = "true" ]; then
-            TAGS="$TAGS,$FULL_IMAGE:latest"
-          fi
-          echo "TAGS=$TAGS" >> $GITHUB_OUTPUT
+          TAGS_FULL="$FULL_IMAGE:v$VERSION"
+          [ "$UPDATE_LATEST" = "true" ] && TAGS_FULL="$TAGS_FULL,$FULL_IMAGE:latest"
+          echo "TAGS_FULL=$TAGS_FULL" >> $GITHUB_OUTPUT
+
+          TAGS_SLIM="$FULL_IMAGE:v$VERSION-slim"
+          [ "$UPDATE_LATEST" = "true" ] && TAGS_SLIM="$TAGS_SLIM,$FULL_IMAGE:slim"
+          echo "TAGS_SLIM=$TAGS_SLIM" >> $GITHUB_OUTPUT
           echo "FULL_IMAGE=$FULL_IMAGE" >> $GITHUB_OUTPUT
 
-      - name: Build and push Docker image
+      - name: Build and push full image
         uses: docker/build-push-action@v5
         with:
           context: ${{ inputs.context }}
           push: true
           platforms: linux/amd64,linux/arm64
-          tags: ${{ steps.docker-tags.outputs.TAGS }}
+          build-args: VARIANT=full
+          tags: ${{ steps.docker-tags.outputs.TAGS_FULL }}
           labels: |
             org.opencontainers.image.source=https://github.com/${{ github.repository }}
             org.opencontainers.image.version=${{ inputs.version }}
@@ -81,6 +84,24 @@ jobs:
             index:org.opencontainers.image.source=https://github.com/${{ github.repository }}
             index:org.opencontainers.image.licenses=Apache-2.0
 
+      - name: Build and push slim image
+        uses: docker/build-push-action@v5
+        with:
+          context: ${{ inputs.context }}
+          push: true
+          platforms: linux/amd64,linux/arm64
+          build-args: VARIANT=slim
+          tags: ${{ steps.docker-tags.outputs.TAGS_SLIM }}
+          labels: |
+            org.opencontainers.image.source=https://github.com/${{ github.repository }}
+            org.opencontainers.image.version=${{ inputs.version }}
+            org.opencontainers.image.revision=${{ github.sha }}
+            org.opencontainers.image.title=${{ inputs.image_title }} (Slim)
+            org.opencontainers.image.licenses=Apache-2.0
+          annotations: |
+            index:org.opencontainers.image.source=https://github.com/${{ github.repository }}
+            index:org.opencontainers.image.licenses=Apache-2.0
+
       - name: Scan Docker image for vulnerabilities
         uses: aquasecurity/trivy-action@0.34.0
         with:

.github/workflows/release-finalize.yml

@@ -19,6 +19,10 @@ on:
         description: 'Branch to release from'
         required: true
         type: string
+      package:
+        description: 'Package name (e.g., afm-core, afm-langchain, ballerina-interpreter)'
+        required: true
+        type: string
       is_rerelease:
         description: 'Whether this is a re-release'
         required: false
@@ -41,24 +45,26 @@ jobs:
         env:
           TAG: ${{ inputs.tag }}
           IMPLEMENTATION: ${{ inputs.implementation }}
+          PACKAGE: ${{ inputs.package }}
           VERSION: ${{ inputs.version }}
         run: |
           git config user.name "github-actions[bot]"
           git config user.email "github-actions[bot]@users.noreply.github.com"
-          git checkout -b "release-${TAG%-v*}-$VERSION"
+          git checkout -b "release-$PACKAGE-$VERSION"
           git tag "$TAG"
-          git push origin "release-${TAG%-v*}-$VERSION"
+          git push origin "release-$PACKAGE-$VERSION"
           git push origin "$TAG"
 
       - name: Generate release notes
         env:
           TAG: ${{ inputs.tag }}
           IMPLEMENTATION: ${{ inputs.implementation }}
+          PACKAGE: ${{ inputs.package }}
           VERSION: ${{ inputs.version }}
           IS_RERELEASE: ${{ inputs.is_rerelease }}
         run: |
           # Find previous tag for this implementation (exclude current version)
-          PREV_TAG=$(git tag -l "${TAG%-v*}-v*" --sort=-v:refname | grep -v "^$TAG$" | head -1)
+          PREV_TAG=$(git tag -l "$PACKAGE-v*" --sort=-v:refname | grep -v "^$TAG$" | head -1)
 
           # Generate notes from commits that touched this implementation
           if [ -n "$PREV_TAG" ]; then
@@ -108,9 +114,10 @@ jobs:
         env:
           GH_TOKEN: ${{ github.token }}
           TAG: ${{ inputs.tag }}
+          PACKAGE: ${{ inputs.package }}
           VERSION: ${{ inputs.version }}
         run: |
-          TITLE="${TAG%-v*} v$VERSION"
+          TITLE="$PACKAGE v$VERSION"
           gh release create "$TAG" \
             --title "$TITLE" \
             --notes-file release_notes.md

.github/workflows/release-python.yml

@@ -80,7 +80,7 @@ jobs:
           TAG: ${{ steps.version.outputs.TAG }}
         run: |
           if git rev-parse "$TAG" >/dev/null 2>&1; then
-            echo "::error::Tag $TAG already exists. Use re-release workflow to overwrite."
+            echo "::error::Tag $TAG already exists. Delete the existing tag and release branch before re-running, or bump the version in pyproject.toml."
             exit 1
           fi
 
@@ -92,7 +92,7 @@ jobs:
         run: |
           RELEASE_BRANCH="release-$PACKAGE-$VERSION"
           if git ls-remote --exit-code --heads origin "$RELEASE_BRANCH" >/dev/null 2>&1; then
-            echo "::error::Release branch $RELEASE_BRANCH already exists. Use re-release workflow to overwrite."
+            echo "::error::Release branch $RELEASE_BRANCH already exists. Delete the existing tag and release branch before re-running, or bump the version in pyproject.toml."
             exit 1
           fi
 
@@ -150,18 +150,26 @@ jobs:
             uv build --package afm-langchain
           fi
 
-      - name: Publish to PyPI
+      - name: Publish afm-core to PyPI
+        if: inputs.package == 'afm-core'
         working-directory: python-interpreter
         env:
-          PACKAGE: ${{ inputs.package }}
-          UV_PUBLISH_TOKEN: ${{ secrets.PYPI_API_TOKEN }}
-        run: |
-          if [ "$PACKAGE" = "afm-core" ]; then
-            uv publish dist/afm_core-*
-            uv publish dist/afm_cli-*
-          elif [ "$PACKAGE" = "afm-langchain" ]; then
-            uv publish dist/afm_langchain-*
-          fi
+          UV_PUBLISH_TOKEN: ${{ secrets.AFM_CORE_PYPI_API_TOKEN }}
+        run: uv publish dist/afm_core-*
+
+      - name: Publish afm-cli to PyPI
+        if: inputs.package == 'afm-core'
+        working-directory: python-interpreter
+        env:
+          UV_PUBLISH_TOKEN: ${{ secrets.AFM_CLI_PYPI_API_TOKEN }}
+        run: uv publish dist/afm_cli-*
+
+      - name: Publish afm-langchain to PyPI
+        if: inputs.package == 'afm-langchain'
+        working-directory: python-interpreter
+        env:
+          UV_PUBLISH_TOKEN: ${{ secrets.AFM_LANGCHAIN_PYPI_API_TOKEN }}
+        run: uv publish dist/afm_langchain-*
 
   docker:
     needs: [validate, test]
@@ -189,6 +197,7 @@ jobs:
     with:
       tag: ${{ needs.validate.outputs.tag }}
       implementation: python-interpreter
+      package: ${{ inputs.package }}
       version: ${{ needs.validate.outputs.release_version }}
       branch: ${{ inputs.branch }}
       is_rerelease: false
@@ -230,6 +239,10 @@ jobs:
             uv version --bump patch --package afm-cli --frozen
             # Sync the afm-core exact pin in afm-cli's dependencies
             NEW_CORE_VERSION=$(uv version --short --package afm-core)
+            if [[ ! "$NEW_CORE_VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+              echo "::error::Failed to get valid afm-core version, got: '$NEW_CORE_VERSION'"
+              exit 1
+            fi
             sed -i "s/\"afm-core==.*\"/\"afm-core==$NEW_CORE_VERSION\"/" packages/afm-cli/pyproject.toml
           elif [ "$PACKAGE" = "afm-langchain" ]; then
             uv version --bump patch --package afm-langchain --frozen

README.md

@@ -7,15 +7,15 @@ Reference implementations for [Agent-Flavored Markdown (AFM)](https://wso2.githu
 | Implementation | Language/Framework | Status |
 |----------------|-------------------|--------|
 | [ballerina-interpreter](./ballerina-interpreter) | Ballerina | Active |
-| [python-interpreter](./python-interpreter) | Python/LangChain | Active |
+| [langchain-interpreter](./python-interpreter) | Python/LangChain | Active |
 
 ## Repository Structure
 
 ```
 reference-implementations-afm/
-├── ballerina-interpreter/   # Ballerina-based AFM interpreter
-├── python-interpreter/   # LangChain-based AFM interpreter
-└── .github/workflows/       # CI/CD (path-filtered per implementation)
+├── ballerina-interpreter/    # Ballerina-based AFM interpreter
+├── python-interpreter/       # LangChain-based AFM interpreter
+└── .github/workflows/        # CI/CD (path-filtered per implementation)
 ```
 
 ## Getting Started
@@ -24,13 +24,33 @@ Each implementation has its own README with setup and usage instructions. See th
 
 ## Contributing
 
-Contributions are welcome! When adding a new implementation:
+Contributions are welcome!
 
-1. Create a new directory: `{language/framework}-{type}/` (e.g., `python-interpreter/`)
+### Adding a New Implementation (New Language or Framework)
+
+To add an interpreter in a new language or framework:
+
+1. Create a new directory: `{language/framework}-{type}/` (e.g., `go-interpreter/`)
 2. Add a path-filtered workflow in `.github/workflows/`
 3. Include a README with setup and usage instructions
 4. Follow the [AFM Specification](https://wso2.github.io/agent-flavored-markdown/specification/) for compatibility
 
+### Adding a New Python Execution Backend (Plugin)
+
+The Python interpreter uses a plugin-based architecture. New execution backends (e.g., for LlamaIndex, CrewAI or other agent frameworks) should be contributed as packages inside [`python-interpreter/packages/`](./python-interpreter/packages/).
+
+To add a new Python backend:
+
+1. Create a new package under `python-interpreter/packages/` and add it to the `uv` workspace
+2. Implement the `AgentRunner` protocol from [`afm-core`](./python-interpreter/packages/afm-core/)
+3. Register your backend via the `afm.runner` entry point in your `pyproject.toml`:
+   ```toml
+   [project.entry-points."afm.runner"]
+   your-backend = "your_package.module:YourRunnerClass"
+   ```
+4. Use [`afm-langchain`](./python-interpreter/packages/afm-langchain/) as a reference implementation
+5. Include a README and tests for your package
+
 ## License
 
 Apache License 2.0

python-interpreter/Dockerfile

@@ -28,7 +28,22 @@ RUN --mount=type=cache,target=/root/.cache/uv \
     uv sync --frozen --no-editable --package afm-core --package afm-langchain
 
 # Stage 2: Final image
+# VARIANT=full installs Node.js, npm (npx), git, and uv/uvx for MCP server support.
+# VARIANT=slim ships only Python + .venv.
 FROM python:3.13-alpine
+ARG VARIANT=full
+
+RUN if [ "$VARIANT" = "full" ]; then \
+        apk add --no-cache nodejs npm git && \
+        echo "Full variant: nodejs, npm, git installed"; \
+    fi
+
+# Install uv and uvx for Python-based MCP server support (full variant only)
+COPY --from=ghcr.io/astral-sh/uv:0.10.0 /uv /uvx /uv-bins/
+RUN if [ "$VARIANT" = "full" ]; then \
+        mv /uv-bins/uv /uv-bins/uvx /bin/; \
+    fi && \
+    rm -rf /uv-bins
 
 # Set working directory
 WORKDIR /app
@@ -39,6 +54,10 @@ COPY --from=builder /app/.venv /app/.venv
 # Set environment variables
 ENV PATH="/app/.venv/bin:$PATH"
 ENV PYTHONUNBUFFERED=1
+# Signal to the AFM update checker that it's running inside a container.
+# This suppresses package-manager upgrade commands in update notifications
+# since users should update by rebuilding or pulling the container image.
+ENV AFM_RUNTIME=docker
 
 # Expose default port for web interfaces
 EXPOSE 8000

python-interpreter/packages/afm-cli/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "afm-cli"
-version = "0.2.10"
+version = "0.3.0"
 description = "AFM CLI metapackage: installs afm-core and afm-langchain"
 readme = "README.md"
 classifiers = [
@@ -11,8 +11,8 @@ license = "Apache-2.0"
 requires-python = ">=3.11"
 urls = { Repository = "https://github.com/wso2/reference-implementations-afm" }
 dependencies = [
-    "afm-core==0.1.7",
-    "afm-langchain>=0.1.0",
+    "afm-core==0.2.0",
+    "afm-langchain>=0.2.0",
 ]
 
 [project.scripts]

python-interpreter/packages/afm-core/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "afm-core"
-version = "0.1.7"
+version = "0.2.0"
 description = "AFM (Agent-Flavored Markdown) core: parser, CLI, protocols, and interfaces"
 readme = "README.md"
 classifiers = [

python-interpreter/packages/afm-core/src/afm/cli.py

@@ -39,6 +39,7 @@
 )
 from .models import (
     ConsoleChatInterface,
+    HttpTransport,
     WebChatInterface,
     WebhookInterface,
 )
@@ -232,7 +233,12 @@ def format_validation_output(afm: AFMRecord) -> str:
         lines.append("")
         lines.append("  MCP Servers:")
         for server in afm.metadata.tools.mcp:
-            lines.append(f"    - {server.name}: {server.transport.url}")
+            transport = server.transport
+            if isinstance(transport, HttpTransport):
+                transport_info = transport.url
+            else:
+                transport_info = transport.command
+            lines.append(f"    - {server.name}: {transport_info}")
             if server.tool_filter:
                 if server.tool_filter.allow:
                     lines.append(f"      Allow: {', '.join(server.tool_filter.allow)}")
@@ -499,10 +505,16 @@ def framework_list() -> None:
     runners = discover_runners()
 
     if not runners:
+        from afm.update import _detect_install_command
+
         click.echo("No runner backends found.")
         click.echo("")
-        click.echo("Install a backend package such as 'afm-langchain':")
-        click.echo("  uv add afm-langchain")
+        install_cmd = _detect_install_command("afm-langchain")
+        if install_cmd is None:
+            click.echo("Use a container image that includes 'afm-langchain'.")
+        else:
+            click.echo("Install a backend package such as 'afm-langchain':")
+            click.echo(f"  {install_cmd}")
         return
 
     click.echo("Discovered runner backends:")