refactor: reorganize SDK structure into sdks/ directory (docs/implement-github-flow-strategy)

docker/Dockerfile.capability-sandbox

@@ -20,7 +20,7 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
 WORKDIR /app
 
 # Copy ARAL library (read-only at runtime)
-COPY --chown=aral:aral implementations/python/aral /app/aral
+COPY --chown=aral:aral sdks/python/aral /app/aral
 
 # Install Python dependencies
 COPY --chown=aral:aral requirements.txt /app/

docker/docker-compose.sandbox.yml

@@ -30,7 +30,7 @@ services:
     volumes:
       # Read-only application code
       - type: bind
-        source: ../implementations/python/aral
+        source: ../sdks/python/aral
         target: /app/aral
         read_only: true
 

docker/docker-compose.yml

@@ -112,7 +112,7 @@ services:
       - TESTING=1
 
     volumes:
-      - ./implementations/python/tests:/app/tests:ro
+      - ./sdks/python/tests:/app/tests:ro
 
     command: ["python", "-m", "pytest", "tests/test_capability_sandbox.py", "-v"]
 

sdks/README.md

@@ -0,0 +1,122 @@
+# ARAL SDKs
+
+This directory contains all SDK implementations for the ARAL (Autonomous Reasoning and Adaptive Learning) protocol.
+
+## 📁 Structure
+
+```
+sdks/
+├── python/          # Python SDK implementation
+│   ├── aral/        # Core Python package
+│   ├── docs/        # Python SDK documentation
+│   ├── examples/    # Usage examples
+│   └── tests/       # Test suite
+│
+└── typescript/      # TypeScript SDK implementation
+    ├── packages/    # Monorepo packages
+    │   └── core/    # Core TypeScript package
+    └── turbo.json   # Turborepo configuration
+```
+
+## 🐍 Python SDK
+
+The Python SDK provides a complete implementation of the ARAL protocol with:
+
+- ✅ All 7 protocol layers (Memory, Runtime, Persona, Capability, Orchestration, Reasoning, Protocol)
+- ✅ Privacy layer with GDPR compliance features
+- ✅ Multiple LLM provider support (OpenAI, Anthropic, Mock)
+- ✅ Comprehensive test coverage
+- ✅ Full Sphinx documentation
+
+**Quick Start:**
+```bash
+cd sdks/python
+pip install -e .
+python examples/simple_agent.py
+```
+
+**Documentation:** See [sdks/python/README.md](python/README.md)
+
+## 📘 TypeScript SDK
+
+The TypeScript SDK is a TypeScript implementation managed as a Turborepo monorepo:
+
+- ✅ Type-safe implementation of core layers
+- ✅ Monorepo structure with Turbo for efficient builds
+- ✅ Jest for testing
+- ⏳ In active development
+
+**Quick Start:**
+```bash
+cd sdks/typescript
+npm install
+npm test
+```
+
+**Documentation:** See [sdks/typescript/README.md](typescript/README.md) *(coming soon)*
+
+## 🔄 Migration Notice
+
+**BREAKING CHANGE (January 2026):**
+
+SDK paths have been reorganized for better project structure:
+
+| Old Path                     | New Path                |
+|------------------------------|-------------------------|
+| `implementations/python/`    | `sdks/python/`          |
+| `typescript-sdk/`            | `sdks/typescript/`      |
+
+**If you have local clones or references:**
+
+1. **Update Git remotes** (if needed):
+   ```bash
+   git pull origin <your-branch>
+   ```
+
+2. **Update import paths** in your code:
+   ```python
+   # Old
+   from aral import Memory
+
+   # New (no change - package name unchanged)
+   from aral import Memory
+   ```
+
+3. **Update file references**:
+   - Documentation: `implementations/python/` → `sdks/python/`
+   - Docker configs: Update volume mounts
+   - CI/CD: Update working directories
+
+## 🔗 Related Resources
+
+- [ARAL Protocol Specification](../SPEC/)
+- [Schema Definitions](../schemas/)
+- [Governance Documents](../governance/)
+- [Examples](../examples/)
+
+## 📝 Adding a New SDK
+
+To add a new language SDK:
+
+1. Create a new directory: `sdks/<language>/`
+2. Follow the ARAL protocol specification in `SPEC/`
+3. Implement all 7 core layers
+4. Add comprehensive tests
+5. Update this README with your SDK
+
+**Required Layers:**
+1. Memory Layer - Context management
+2. Runtime Layer - Execution environment
+3. Persona Layer - Identity management
+4. Capability Layer - Function calling
+5. Orchestration Layer - Workflow coordination
+6. Reasoning Layer - Decision making
+7. Protocol Layer - Message exchange
+
+## 🤝 Contributing
+
+See [governance/CONTRIBUTING.md](../governance/CONTRIBUTING.md) for contribution guidelines.
+
+## 📄 License
+
+All SDKs follow the project license. See [LICENSE](../LICENSE) for details.

implementations/python/GUIDE-CLE-API.md → sdks/python/GUIDE-CLE-API.md

@@ -5,7 +5,7 @@
 ### 1. Créer le fichier `.env`
 
 ```bash
-cd implementations/python
+cd sdks/python
 cp .env.example .env
 ```
 
@@ -71,7 +71,7 @@ python examples/llm_providers_example.py
 ## 📍 Où se Trouve Quoi ?
 
 ```
-implementations/python/
+sdks/python/
 ├── aral/providers/           # Providers LLM
 │   ├── openai_provider.py   # OpenAI / Azure
 │   ├── anthropic_provider.py # Anthropic Claude

implementations/python/README.md → sdks/python/README.md

@@ -54,7 +54,7 @@ Reference implementation of the ARAL (Agent Runtime Abstract Layer) Standard in
 
 ```bash
 git clone https://github.com/personalayer/aral-standard.git
-cd aral-standard/implementations/python
+cd aral-standard/sdks/python
 pip install -e .
 ```
 
@@ -322,7 +322,7 @@ mypy aral/
 ### Project Structure
 
 ```
-implementations/python/
+sdks/python/
 ├── aral/
 │   ├── __init__.py          # Package exports
 │   ├── runtime.py           # L1: Runtime implementation

implementations/python/RESUME-LLM-PROVIDERS.md → sdks/python/RESUME-LLM-PROVIDERS.md

@@ -30,7 +30,7 @@
 
 ```bash
 # 1. Créer le fichier .env
-cd implementations/python
+cd sdks/python
 cp .env.example .env
 
 # 2. Ajouter vos clés

implementations/python/docs/examples.rst → sdks/python/docs/examples.rst

@@ -9,7 +9,7 @@ Complete Examples
 Simple Agent
 ~~~~~~~~~~~~
 
-The `simple_agent.py <https://github.com/personamanagmentlayer/aral-standard/blob/main/implementations/python/examples/simple_agent.py>`_ demonstrates all 7 layers working together.
+The `simple_agent.py <https://github.com/personamanagmentlayer/aral-standard/blob/main/sdks/python/examples/simple_agent.py>`_ demonstrates all 7 layers working together.
 
 .. literalinclude:: ../examples/simple_agent.py
    :language: python

implementations/python/docs/migration.rst → sdks/python/docs/migration.rst

@@ -256,5 +256,5 @@ Need Help?
 If you encounter issues during migration:
 
 1. Check the `CHANGELOG.md <https://github.com/personamanagmentlayer/aral-standard/blob/main/CHANGELOG.md>`_
-2. Review the `integration tests <https://github.com/personamanagmentlayer/aral-standard/blob/main/implementations/python/tests/test_integration_full.py>`_
+2. Review the `integration tests <https://github.com/personamanagmentlayer/aral-standard/blob/main/sdks/python/tests/test_integration_full.py>`_
 3. Open an issue on `GitHub <https://github.com/personamanagmentlayer/aral-standard/issues>`_

implementations/python/docs/quickstart.rst → sdks/python/docs/quickstart.rst

@@ -17,7 +17,7 @@ Or install from source:
 .. code-block:: bash
 
    git clone https://github.com/personamanagmentlayer/aral-standard.git
-   cd aral-standard/implementations/python
+   cd aral-standard/sdks/python
    pip install -e ".[dev]"
 
 Basic Usage
@@ -256,7 +256,7 @@ The protocol layer handles MCP messages:
 Complete Example
 ----------------
 
-See the `simple_agent.py <https://github.com/personamanagmentlayer/aral-standard/blob/main/implementations/python/examples/simple_agent.py>`_ example for a complete working demonstration of all 7 layers.
+See the `simple_agent.py <https://github.com/personamanagmentlayer/aral-standard/blob/main/sdks/python/examples/simple_agent.py>`_ example for a complete working demonstration of all 7 layers.
 
 Common Patterns
 ---------------

implementations/python/examples/README.md → sdks/python/examples/README.md

@@ -50,7 +50,7 @@ Enterprise-grade agent with full security:
 ## Running Examples
 
 ```bash
-# From implementations/python directory
+# From sdks/python directory
 python examples/simple_agent.py
 
 # With verbose output

typescript-sdk/packages/core/package.json → sdks/typescript/packages/core/package.json

@@ -48,6 +48,6 @@
   "repository": {
     "type": "git",
     "url": "https://github.com/personamanagmentlayer/aral-standard.git",
-    "directory": "typescript-sdk/packages/core"
+    "directory": "sdks/typescript/packages/core"
   }
 }

update-paths.ps1

@@ -0,0 +1,43 @@
+# Script to update all path references from old to new SDK structure
+# Old: typescript-sdk/, implementations/python/
+# New: sdks/typescript/, sdks/python/
+
+Write-Host "Updating path references in documentation and config files..." -ForegroundColor Cyan
+
+# Files to update (excluding build artifacts and generated docs)
+$filesToUpdate = @(
+    "sdks/python/README.md",
+    "sdks/python/RESUME-LLM-PROVIDERS.md",
+    "sdks/python/GUIDE-CLE-API.md",
+    "sdks/python/examples/README.md",
+    "sdks/python/docs/quickstart.rst",
+    "sdks/python/docs/migration.rst",
+    "sdks/python/docs/examples.rst",
+    "sdks/typescript/packages/core/package.json",
+    "docker/docker-compose.yml",
+    "docker/Dockerfile.capability-sandbox",
+    "docker/docker-compose.sandbox.yml"
+)
+
+foreach ($file in $filesToUpdate) {
+    if (Test-Path $file) {
+        Write-Host "  Updating: $file" -ForegroundColor Yellow
+
+        # Read content
+        $content = Get-Content $file -Raw
+
+        # Replace paths
+        $content = $content -replace 'implementations/python', 'sdks/python'
+        $content = $content -replace 'typescript-sdk/', 'sdks/typescript/'
+
+        # Write back
+        Set-Content -Path $file -Value $content -NoNewline
+    }
+}
+
+Write-Host "Path updates complete!" -ForegroundColor Green
+Write-Host ""
+Write-Host "Next steps:" -ForegroundColor Cyan
+Write-Host "1. Review changes: git diff" -ForegroundColor White
+Write-Host "2. Commit: git commit -am 'docs: update SDK paths after reorganization'" -ForegroundColor White
+Write-Host "3. Push: git push" -ForegroundColor White