feat: add python implementation

.env.test.example

@@ -1,5 +1,5 @@
 # Test environment configuration
-TEST_API_BASE_URL=http://localhost:8010
-TEST_API_TOKEN=your_posthog_api_token_here
+TEST_POSTHOG_API_BASE_URL=http://localhost:8010
+TEST_POSTHOG_PERSONAL_API_KEY=your_posthog_api_token_here
 TEST_ORG_ID=your_test_organization_id_here
 TEST_PROJECT_ID=your_test_project_id_here

.github/workflows/ci-python.yml

@@ -0,0 +1,172 @@
+name: Python CI
+permissions:
+  contents: read
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  lint-and-format:
+    name: Lint, Format, and Type Check
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          version: "latest"
+
+      - name: Install dependencies
+        run: |
+          cd python
+          uv sync --dev
+
+      - name: Run ruff linter
+        run: |
+          cd python
+          uv run ruff check --fix .
+
+      - name: Run ruff formatter
+        run: |
+          cd python
+          uv run ruff format .
+
+      - name: Check for changes
+        run: |
+          if [ -n "$(git status --porcelain)" ]; then
+            echo "Code formatting or linting changes detected!"
+            git diff
+            exit 1
+          fi
+
+      - name: Run type checking
+        run: |
+          cd python
+          uvx ty check
+
+  unit-tests:
+    name: Unit Tests
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          version: "latest"
+
+      - name: Install dependencies
+        run: |
+          cd python
+          uv sync --dev
+
+      - name: Run unit tests
+        run: |
+          cd python
+          uv run pytest tests/ -v --tb=short --ignore-glob="*_integration.py"
+        env:
+          PYTHONPATH: ${{ github.workspace }}/python
+
+  integration-tests:
+    name: Integration Tests
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    concurrency:
+      group: ${{ github.workflow }}-integration-${{ github.head_ref || github.ref }}
+      cancel-in-progress: true
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.11'
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v3
+      with:
+        version: "latest"
+
+    - name: Install dependencies
+      run: |
+        cd python
+        uv sync --dev
+
+    - name: Run integration tests
+      run: |
+        cd python
+        uv run pytest tests/tools/ -v --tb=short
+      env:
+        PYTHONPATH: ${{ github.workspace }}/python
+        TEST_POSTHOG_API_BASE_URL: ${{ secrets.TEST_API_BASE_URL }}
+        TEST_POSTHOG_PERSONAL_API_KEY: ${{ secrets.TEST_API_TOKEN }}
+        TEST_ORG_ID: ${{ secrets.TEST_ORG_ID }}
+        TEST_PROJECT_ID: ${{ secrets.TEST_PROJECT_ID }}
+
+  schema-sync:
+    name: Schema Synchronization Check
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'pnpm'
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          version: "latest"
+
+      - name: Install Node.js dependencies
+        run: pnpm install
+
+      - name: Install Python dependencies
+        run: |
+          cd python
+          uv sync --dev
+
+      - name: Generate schemas
+        run: pnpm run schema:build
+
+      - name: Check if schemas are up to date
+        run: |
+          if [ -n "$(git status --porcelain)" ]; then
+            echo "Python schemas are out of sync with TypeScript definitions!"
+            echo "Please run 'pnpm run schema:build' to regenerate the schemas."
+            git diff
+            exit 1
+          fi

.github/workflows/test.yml → .github/workflows/ci-typescript.yml

@@ -1,4 +1,4 @@
-name: Tests
+name: TypeScript CI
 
 on:
   push:
@@ -7,13 +7,50 @@
     branches: [ main ]
 
 jobs:
+  lint-and-format:
+    name: Lint, Format, and Type Check
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'pnpm'
+
+      - name: Install dependencies
+        run: pnpm i
+
+      - name: Run linter
+        run: pnpm run lint:fix
+
+      - name: Run formatter
+        run: pnpm run format
+
+      - name: Run type check
+        run: pnpm run typecheck
+
+      - name: Check for changes
+        run: |
+          if [ -n "$(git status --porcelain)" ]; then
+            echo "Code formatting or linting changes detected!"
+            git diff
+            exit 1
+          fi
+
   unit-tests:
     name: Unit Tests
     runs-on: ubuntu-latest
     permissions:
       contents: read
     concurrency:
-      group: ${{ github.workflow }}-${{ github.head_ref || github.ref }}
+      group: ${{ github.workflow }}-unit-${{ github.head_ref || github.ref }}
       cancel-in-progress: true
 
     steps:
@@ -32,12 +69,6 @@
     - name: Install dependencies
       run: pnpm install
 
-    - name: Run linting
-      run: pnpm run lint:fix
-
-    - name: Run formatting check
-      run: pnpm run format
-
     - name: Run unit tests
       run: pnpm run test
 
@@ -48,7 +79,7 @@
     permissions:
       contents: read
     concurrency:
-      group: ${{ github.workflow }}-${{ github.head_ref || github.ref }}
+      group: ${{ github.workflow }}-integration-${{ github.head_ref || github.ref }}
       cancel-in-progress: true
 
     steps:
@@ -70,7 +101,7 @@
     - name: Run integration tests
       run: pnpm run test:integration
       env:
-        TEST_API_BASE_URL: ${{ secrets.TEST_API_BASE_URL }}
-        TEST_API_TOKEN: ${{ secrets.TEST_API_TOKEN }}
+        TEST_POSTHOG_API_BASE_URL: ${{ secrets.TEST_API_BASE_URL }}
+        TEST_POSTHOG_PERSONAL_API_KEY: ${{ secrets.TEST_API_TOKEN }}
         TEST_ORG_ID: ${{ secrets.TEST_ORG_ID }}
         TEST_PROJECT_ID: ${{ secrets.TEST_PROJECT_ID }}

.gitignore

@@ -10,7 +10,9 @@ node_modules
 .cursor/
 
 # Python
+python/venv/
 __pycache__/
-.mypy_cache/
-.ruff_cache/
-.pytest_cache/
+.mypy_cache/.ruff_cache/
+.pytest_cache/
+
+.env

package.json

@@ -16,6 +16,10 @@
 		"schema:build:json": "tsx typescript/scripts/generate-tool-schema.ts",
 		"schema:build:python": "bash python/scripts/generate-pydantic-models.sh",
 		"schema:build": "pnpm run schema:build:json && pnpm run schema:build:python",
+		"test:python": "cd python && uv run pytest tests/ -v",
+		"lint:python": "cd python && uv run ruff check --fix .",
+		"format:python": "cd python && uv run ruff format .",
+		"typecheck:python": "cd python && uvx ty check",
 		"typecheck": "tsc --project typescript/tsconfig.json --noEmit"
 	},
 	"devDependencies": {

python/.env.example

@@ -0,0 +1,7 @@
+# PostHog API Configuration
+POSTHOG_API_TOKEN=your-posthog-api-token-here
+POSTHOG_BASE_URL=https://app.posthog.com
+
+# Optional: OpenAI API key for agent testing
+# Without this, only individual tool tests will work
+OPENAI_API_KEY=your-openai-api-key-here

python/.vscode/settings.json

@@ -0,0 +1,19 @@
+{
+	"python.defaultInterpreterPath": "./.venv/bin/python",
+	"python.linting.enabled": true,
+	"python.linting.ruffEnabled": true,
+	"python.linting.flake8Enabled": false,
+	"python.formatting.provider": "none",
+	"editor.formatOnType": false,
+	"editor.codeActionsOnSave": {
+		"source.fixAll": "never"
+	},
+	"[python]": {
+		"editor.defaultFormatter": "charliermarsh.ruff",
+		"editor.formatOnSave": true,
+		"editor.codeActionsOnSave": {
+			"source.organizeImports": "explicit",
+			"source.fixAll.ruff": "explicit"
+		}
+	}
+}