feat: gRPC adapter for language-agnostic agent support

.github/workflows/ci.yml

@@ -0,0 +1,108 @@
+name: CI
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  # ──────────────────────────────────────────────────────────────
+  # Unit tests — fast, hermetic, no network, no ports
+  # ──────────────────────────────────────────────────────────────
+  unit-tests:
+    name: Unit Tests
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --locked --all-extras --dev
+
+      - name: Run pre-commit checks
+        run: uv run pre-commit run --all-files
+
+      - name: Run unit tests with coverage
+        run: |
+          uv run pytest tests/unit/ \
+            --cov=bindu \
+            --cov-report=term-missing \
+            --cov-report=xml:coverage.xml \
+            --cov-fail-under=60 \
+            -v
+
+      - name: Upload coverage
+        if: matrix.python-version == '3.13'
+        uses: coverallsapp/github-action@v2
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          file: coverage.xml
+
+  # ──────────────────────────────────────────────────────────────
+  # E2E gRPC tests — real servers, real ports, full round-trip
+  # ──────────────────────────────────────────────────────────────
+  e2e-grpc-tests:
+    name: E2E gRPC Tests
+    runs-on: ubuntu-latest
+    needs: unit-tests
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+
+      - name: Set up Python 3.13
+        run: uv python install 3.13
+
+      - name: Install dependencies
+        run: uv sync --locked --all-extras --dev
+
+      - name: Run E2E gRPC integration tests
+        run: |
+          uv run pytest tests/integration/grpc/ \
+            -v -m e2e \
+            --timeout=60
+
+  # ──────────────────────────────────────────────────────────────
+  # TypeScript SDK — build and verify
+  # ──────────────────────────────────────────────────────────────
+  typescript-sdk:
+    name: TypeScript SDK Build
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+
+      - name: Install and build SDK
+        working-directory: sdks/typescript
+        run: |
+          npm install
+          npm run build
+
+      - name: Verify example dependencies
+        working-directory: examples/typescript-openai-agent
+        run: npm install

.gitignore

@@ -187,6 +187,8 @@ examples/.bindu/public.pem
 examples/agent_swarm/.bindu/private.pem
 examples/agent_swarm/.bindu/public.pem
 
+examples/typescript-openai-agent/logs/
+
 # Pebbling keys (DID private/public keys)
 examples/.pebbling/*
 **/.pebbling/private.pem
@@ -203,3 +205,14 @@ bindu/penguin/.bindu/public.pem
 .bindu/
 
 postman/*
+node_modules/
+**/node_modules/
+
+# TypeScript SDK
+sdks/typescript/dist/
+sdks/typescript/node_modules/
+
+# Kotlin SDK
+sdks/kotlin/build/
+sdks/kotlin/.gradle/
+sdks/kotlin/bin/

.pre-commit-config.yaml

@@ -13,19 +13,19 @@ repos:
     hooks:
       - id: ruff
         args: ["--fix"]
-        exclude: ^examples/
+        exclude: ^(examples/|bindu/grpc/generated/)
       - id: ruff-format
-        exclude: ^examples/
+        exclude: ^(examples/|bindu/grpc/generated/)
 
   - repo: local
     hooks:
       - id: ty
         name: ty type checker
-        entry: uv run ty check bindu/ tests/
+        entry: uv run ty check bindu/ tests/ --exclude bindu/grpc/generated/
         language: system
         types: [python]
         pass_filenames: false
-        exclude: ^examples/
+        exclude: ^(examples/|bindu/grpc/generated/)
 
       - id: pytest
         name: pytest with coverage
@@ -84,4 +84,4 @@ repos:
     rev: 6.3.0
     hooks:
       - id: pydocstyle
-        exclude: ^examples/
+        exclude: ^(examples/|bindu/grpc/generated/)

README.md

@@ -221,7 +221,46 @@ $env:BINDU_PORT="4000"
 
 Existing examples that use `http://localhost:3773` are automatically overridden when `BINDU_PORT` is set.
 
-### Option 2: Zero-Config Local Agent
+### Option 2: TypeScript Agent
+
+Same pattern, different language. Create `index.ts`:
+
+```typescript
+import { bindufy } from "@bindu/sdk";
+import OpenAI from "openai";
+
+const openai = new OpenAI();
+
+bindufy({
+  author: "your.email@example.com",
+  name: "research_agent",
+  description: "A research assistant agent",
+  deployment: { url: "http://localhost:3773", expose: true },
+  skills: ["skills/question-answering"],
+}, async (messages) => {
+  const response = await openai.chat.completions.create({
+    model: "gpt-4o",
+    messages: messages.map(m => ({
+      role: m.role as "user" | "assistant" | "system",
+      content: m.content,
+    })),
+  });
+  return response.choices[0].message.content || "";
+});
+```
+
+Run it:
+
+```bash
+npm install @bindu/sdk openai
+npx tsx index.ts
+```
+
+The SDK launches the Bindu core automatically in the background. Your agent is live at `http://localhost:3773` — same A2A protocol, same DID, same everything.
+
+> See [examples/typescript-openai-agent/](examples/typescript-openai-agent/) for the full working example with setup instructions.
+
+### Option 3: Zero-Config Local Agent
 
 Try Bindu without setting up Postgres, Redis, or any cloud services. Runs entirely locally using in-memory storage and scheduler.
 
@@ -437,6 +476,7 @@ Output:
 | 🔄 **Retry Mechanism** | Automatic retry with exponential backoff for resilient agents | [Guide →](https://docs.getbindu.com/bindu/learn/retry/overview) |
 | 🔑 **Decentralized Identifiers (DIDs)** | Cryptographic identity for verifiable, secure agent interactions and payment integration | [Guide →](docs/DID.md) |
 | 🏥 **Health Check & Metrics** | Monitor agent health and performance with built-in endpoints | [Guide →](docs/HEALTH_METRICS.md) |
+| 🌍 **Language-Agnostic (gRPC)** | Bindufy agents written in TypeScript, Kotlin, Rust, or any language via gRPC adapter | [Guide →](docs/GRPC_LANGUAGE_AGNOSTIC.md) |
 
 ---
 
@@ -502,17 +542,61 @@ NightSky enables swarms of agents. Each Bindu is a dot annotating agents with th
 
 <br/>
 
+## 🌍 Language-Agnostic Agents
+
+Bindu isn't limited to Python. Write your agent in **any language** — the gRPC adapter handles the rest.
+
+**Python** (direct, in-process):
+```python
+from bindu.penguin.bindufy import bindufy
+
+bindufy(config, handler)
+```
+
+**TypeScript** (via `@bindu/sdk`):
+```typescript
+import { bindufy } from "@bindu/sdk";
+
+bindufy(config, async (messages) => {
+  const res = await openai.chat.completions.create({ model: "gpt-4o", messages });
+  return res.choices[0].message.content;
+});
+```
+
+**Kotlin** (via `bindu-sdk`):
+```kotlin
+bindufy(config) { messages ->
+    myAgent.run(messages.last().content)
+}
+```
+
+All three produce the same result: a full A2A microservice with DID, auth, x402, scheduling, and storage. The TypeScript/Kotlin SDKs automatically launch the Bindu core in the background — one command, one terminal.
+
+See [examples/](examples/) for working examples and [docs/GRPC_LANGUAGE_AGNOSTIC.md](docs/GRPC_LANGUAGE_AGNOSTIC.md) for full details.
+
+---
+
+<br/>
+
 ## 🛠️ Supported Agent Frameworks
 
 Bindu is **framework-agnostic** and tested with:
 
+**Python:**
 - **AG2** (formerly AutoGen)
 - **Agno**
 - **CrewAI**
 - **LangChain**
 - **LlamaIndex**
 - **FastAgent**
 
+**TypeScript:**
+- **OpenAI SDK**
+- **LangChain.js**
+
+**Kotlin:**
+- **OpenAI Kotlin SDK**
+
 Want integration with your favorite framework? [Let us know on Discord](https://discord.gg/3w5zuYUuwt)!
 
 ---
@@ -524,10 +608,19 @@ Want integration with your favorite framework? [Let us know on Discord](https://
 Bindu maintains **70%+ test coverage** (target: 80%+):
 
 ```bash
+# Unit tests (fast, in pre-commit)
+uv run pytest tests/unit/ -v
+
+# E2E gRPC integration tests (real servers, full round-trip)
+uv run pytest tests/integration/grpc/ -v -m e2e
+
+# All tests with coverage
 uv run pytest -n auto --cov=bindu --cov-report=term-missing
 uv run coverage report --skip-covered --fail-under=70
 ```
 
+**CI runs automatically on every PR** — unit tests, E2E gRPC tests, and TypeScript SDK build verification. See [`.github/workflows/ci.yml`](.github/workflows/ci.yml).
+
 ---
 
 <br/>
@@ -653,10 +746,11 @@ Grateful to these projects:
 
 ## 🗺️ Roadmap
 
-- [ ] GRPC transport support
+- [x] gRPC transport + language-agnostic SDKs (TypeScript, Kotlin)
 - [ ] Increase test coverage to 80% (in progress)
 - [ ] AP2 end-to-end support
 - [ ] DSPy integration (in progress)
+- [ ] Rust SDK
 - [ ] MLTS support
 - [ ] X402 support with other facilitators