Initial commit: APAB v0.2.0

MCP-driven phased-array antenna design toolkit with 17 tools,
5 examples, full test suite (188 tests), and CI/CD workflows.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: jman4162

.github/workflows/lint.yml

@@ -0,0 +1,30 @@
+name: Lint
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Ruff check
+        run: ruff check src/ tests/
+
+      - name: Mypy
+        run: mypy src/apab/

.github/workflows/tests.yml

@@ -0,0 +1,36 @@
+name: Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev,ollama]"
+
+      - name: Run tests
+        run: pytest tests/ -v --timeout=60
+
+      - name: Run tests with coverage
+        if: matrix.python-version == '3.12'
+        run: |
+          coverage run -m pytest tests/ -v --timeout=60
+          coverage report --fail-under=70

.gitignore

@@ -0,0 +1,41 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg
+*.egg-info/
+dist/
+build/
+*.whl
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# Testing / Coverage
+.pytest_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+.ruff_cache/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Claude Code
+.claude/
+
+# Project artifacts
+workspace/
+*.hdf5
+*.h5

CHANGELOG.md

@@ -0,0 +1,38 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.0] - 2025-02-07
+
+### Added
+- **Agent orchestrator** with LLM tool-calling loop (`apab design`, `apab run`)
+- **17 MCP tools** covering unit-cell simulation, array patterns, system analysis, trade studies, I/O, and plotting
+- **EdgeFEM integration** for full-wave unit-cell frequency sweeps and surface impedance
+- **phased-array-modeling wrapper** (PAMPatternEngine) with full 2-D patterns, multi-beam, null steering, and hardware impairments
+- **phased-array-systems wrapper** (PASSystemEngine) with comms/radar link budgets and DOE trade studies with Pareto extraction
+- **Active impedance utilities** — reflection coefficient, impedance, scan-blindness detection
+- **Touchstone and far-field CSV importers** with flexible format support
+- **5 LLM providers** — Ollama (full), OpenAI/Anthropic/Gemini/OpenAI-compatible (stubs)
+- **CLI commands**: `init`, `design`, `run`, `report`, `mcp serve`
+- **Pydantic v2 configuration** with YAML load/save and full schema validation
+- **Workspace management** with run bundles, artifact directories, and caching
+- **5 working examples** demonstrating array patterns, coupling, trade studies, agent sessions, and Touchstone import
+- **188 passing tests** covering all layers
+- **Path traversal protection** via `is_within_workspace()` in all file-writing MCP tools
+- **Error handling** in all MCP tool functions with structured error JSON responses
+- **Logging** across MCP tools, domain wrappers, and CLI
+- **CI/CD** with GitHub Actions for testing (Python 3.10-3.13) and linting (ruff + mypy)
+
+### Fixed
+- NumPy 2.x compatibility — polyfill for removed `np.trapz` function
+- `pa.compute_directivity` now receives 2D meshgrids instead of 1D arrays
+
+## [0.1.0] - 2024-12-01
+
+### Added
+- Initial project scaffold and specification (SPEC.md)
+- Core Pydantic schemas and configuration system
+- Basic CLI framework

CLAUDE.md

@@ -0,0 +1,83 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+APAB (Agentic Phased Array Builder) is a Python package that connects an LLM to MCP-exposed engineering tools for phased-array antenna design and analysis. It plans and executes workflows end-to-end: full-wave unit-cell simulation with mutual coupling (over frequency, scan angle, polarization) propagated into array-level patterns and system-level metrics.
+
+The full-wave solver is **EdgeFEM** (not VectorEM).
+
+## Build & Development Commands
+
+```bash
+# Install in development mode (once pyproject.toml exists)
+pip install -e ".[dev]"
+
+# Run all tests
+pytest tests/
+
+# Run a single test
+pytest tests/test_file.py::test_name -v
+
+# Type checking
+mypy src/apab/
+
+# Linting
+ruff check src/ tests/
+
+# CLI entry points
+apab init          # scaffold project
+apab design        # interactive agent session
+apab run           # non-interactive from config
+apab report        # generate report from run bundle
+apab mcp serve     # run as MCP server
+```
+
+## Architecture (Four Layers)
+
+1. **Agent Orchestrator** (`src/apab/agent/`) - Talks to LLM providers via a `LLMProvider` protocol. Uses tool-calling to dispatch actions to MCP tools. Default: Ollama with `qwen2.5-coder:14b`, offline-capable.
+
+2. **MCP Tool Layer** (`src/apab/mcp/`) - First-party MCP server exposing tools for simulation (EdgeFEM), array patterns (phased-array-modeling), system trades (phased-array-systems), export/plot/report, and optional external EM adapters.
+
+3. **Execution/Compute Layer** (`src/apab/compute/`) - Local execution by default. `ComputeBackend` protocol designed for future cloud backends (AWS/GCP) via entry points (`apab.compute_backends`).
+
+4. **Artifact + Provenance Layer** - Run bundles at `workspace/runs/<run_id>/` containing manifest, config, logs, and artifacts. Cache keys include config/geometry/sweep hashes and dependency versions.
+
+## Key Required Dependencies
+
+- **edgefem** (PyPI) - Full-wave unit-cell solver backend (`jman4162/EdgeFEM`)
+- **phased-array-modeling** (PyPI) - Array factor/patterns/impairments (`jman4162/Phased-Array-Antenna-Model`)
+- **phased-array-systems** (GitHub: `jman4162/phased-array-systems`) - System-level trades/scenarios
+
+## Plugin/Extension Points (Entry Points)
+
+| Group | Purpose |
+|---|---|
+| `apab.llm_providers` | LLM provider plugins (Ollama, OpenAI, Anthropic, Gemini, OpenAI-compatible) |
+| `apab.em_adapters` | External EM tool adapters (HFSS, CST, FEKO) |
+| `apab.compute_backends` | Compute backend plugins (local, future AWS/GCP) |
+
+## Key Protocols
+
+- `LLMProvider` - Provider abstraction in `src/apab/providers/`. Implementations: `OllamaProvider`, `OpenAIProvider`, `AnthropicProvider`, `GeminiProvider`, `OpenAICompatibleProvider`.
+- `FullWaveUnitCellSolver` - Solver protocol. EdgeFEM integrated via `EdgeFEMAdapter`.
+- `FullWaveFiniteArraySolver` - Reserved for future finite-array simulations.
+- `ExternalEMToolAdapter` - For commercial EM tools (HFSS/CST/FEKO).
+- `ComputeBackend` - For local and future cloud execution.
+
+## Configuration
+
+Project config lives in `apab.yaml`, validated by Pydantic. Key sections: `project`, `llm`, `mcp`, `compute`, `solver`, `unit_cell`, `sweep`, `array`, `outputs`. See SPEC.md section 7 for full example.
+
+## Data Model
+
+Core data arrays use the shape convention `S[f, scan, pol, i, j]` (complex). Derived quantities: `Z_active[f, scan, pol]`, `Gamma_active[f, scan, pol]`. Storage: HDF5 (primary), NPZ (cache), Touchstone (`.sNp` export). All schemas must be JSON/YAML-serializable.
+
+## Security Constraints
+
+- Workspace-only filesystem access by default
+- Local-first, offline-capable defaults (safe mode ON)
+- Remote LLM providers and cloud compute require explicit opt-in
+- `llm.redaction_mode` levels: `none` (local default), `metadata_only`, `strict`
+- All tool calls and remote LLM egress must be audit-logged