Metadata-Version: 2.4
Name: phoenixflight
Version: 0.1.8
Summary: PhoenixFlight: governance-aware runtime for dynamic agent and workload membership.
Author-email: Kinshuk Dutta <kinshuk.dutta@ieee.org>
License-Expression: CC-BY-4.0
Project-URL: Homepage, https://phoenixflight.app
Project-URL: Repository, https://github.com/KinshukON/DynamicMembershipArchitecture
Project-URL: Documentation, https://phoenixflight.app/docs.html
Project-URL: Bug Tracker, https://github.com/KinshukON/DynamicMembershipArchitecture/issues
Project-URL: Changelog, https://github.com/KinshukON/DynamicMembershipArchitecture/releases
Keywords: phoenixflight,dynamic-membership-architecture,agent-runtime,phoenixfile,flightpacket,pflight,governed-runtime,cli
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Topic :: System :: Distributed Computing
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
License-File: AUTHORS
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Provides-Extra: server
Requires-Dist: SQLAlchemy==1.4.54; extra == "server"
Requires-Dist: prometheus_client==0.25.0; extra == "server"
Requires-Dist: psycopg2-binary==2.9.11; extra == "server"
Provides-Extra: operator
Requires-Dist: kopf==1.38.0; extra == "operator"
Requires-Dist: kubernetes==35.0.0; extra == "operator"
Provides-Extra: all
Requires-Dist: phoenixflight[dev,operator,server]; extra == "all"
Dynamic: license-file

# PhoenixFlight

## Dynamic Membership Runtime for Governed Agent and Workload Handoff

[![PyPI version](https://badge.fury.io/py/phoenixflight.svg)](https://pypi.org/project/phoenixflight/)
[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/phoenixflight.svg)](https://pypi.org/project/phoenixflight/)
[![CI](https://github.com/KinshukON/DynamicMembershipArchitecture/actions/workflows/ci.yaml/badge.svg)](https://github.com/KinshukON/DynamicMembershipArchitecture/actions)
[![Release](https://img.shields.io/github/v/release/KinshukON/DynamicMembershipArchitecture?include_prereleases)](https://github.com/KinshukON/DynamicMembershipArchitecture/releases)
[![License](https://img.shields.io/github/license/KinshukON/DynamicMembershipArchitecture)](LICENSE)
[![Website](https://img.shields.io/badge/site-phoenixflight.app-blue)](https://phoenixflight.app)
[![Research DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.20693483.svg)](https://doi.org/10.5281/zenodo.20693483)
[![Software DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.20778458.svg)](https://doi.org/10.5281/zenodo.20778458)
[![ORCID](https://img.shields.io/badge/ORCID-0009--0002--6039--549X-green)](https://orcid.org/0009-0002-6039-549X)


PhoenixFlight is a local dynamic membership runtime for registering, discovering, assigning, handing off, retiring, and auditing agents, services, tools, and workload packets. It is based on Dynamic Membership Architecture, a framework for systems where computational participants dynamically join, leave, migrate, fail, recover, and retire while preserving execution continuity.

PhoenixFlight complements Docker and Kubernetes by adding a governance-aware membership contract for agentic and distributed runtime participation. It is a local MVP runtime backed by research-grade architecture.

> [!IMPORTANT]
> **Technical Specification:** Read the [Technical Blueprint](https://github.com/KinshukON/DynamicMembershipArchitecture/blob/main/docs/technical_blueprint.md) for an in-depth structural and mathematical specification of the Dynamic Membership Architecture (DMA) implementation.

---

## Product Mental Model

```
PhoenixFile  →  .pflight bundle  →  governed runtime execution  →  assignment  →  handoff  →  audit
```

| Stage | What happens |
|---|---|
| **PhoenixFile** | Declare participants, policies, capabilities, and governance contracts |
| **.pflight bundle** | Package + cryptographically verify the application for portable deployment |
| **Governed runtime** | Initialize the local runtime; register agents as members |
| **Assignment** | Policy-route a FlightPacket to the best-match member by trust + capability |
| **Handoff** | Migrate context from one member to another, preserving full lineage |
| **Audit** | Every event — register, assign, handoff, retire — written to JSONL audit trail |

---

## 60-Second Quickstart

Get started with PhoenixFlight immediately via PyPI:

```bash
# 1. Install PhoenixFlight
pip install phoenixflight

# 2. Scaffold a new governed application
phoenix new my-app
cd my-app

# 3. Initialize local runtime
phoenix init

# 4. Validate the declarative app descriptor
phoenix validate -f PhoenixFile

# 5. Register the agent
phoenix member register agents/my-app-agent.yaml

# 6. Create a workload packet
phoenix packet create my-app

# 7. Auto-assign the packet based on capability and trust policy
phoenix assign packet-001 --to my-app-agent

# 8. Check your runtime status
phoenix status

# 9. Build a portable, signed .pflight bundle
phoenix build -f PhoenixFile
```


# Scaffold a new app
phoenix new my-app

# Inspect local runtime state at any time
phoenix status
```

`phoenix status` is the fastest way to inspect your local runtime: it prints a one-screen summary of initialization state, member counts, packet counts, and the most recent audit event. It exits 0 whether or not the runtime has been initialized, so it is safe to run at any point in the workflow. Use `phoenix --no-color status` in CI or when piping output to a file.

### Shell Completion

PhoenixFlight can generate completion scripts for bash, zsh, and fish:

```bash
phoenix completion bash > ~/.phoenix-completion.bash && source ~/.phoenix-completion.bash  # bash
phoenix completion zsh  > ~/.zsh/completions/_phoenix                                      # zsh
phoenix completion fish > ~/.config/fish/completions/phoenix.fish                          # fish
```

Both `phoenix` and `pf` are covered by each generated script. Full install instructions are in [docs/INSTALL.md](docs/INSTALL.md).

See [docs/INSTALL.md](docs/INSTALL.md) for pipx, pip, Homebrew, and container install paths. See [docs/CHANGELOG.md](docs/CHANGELOG.md) for version history and [docs/RELEASE.md](docs/RELEASE.md) for the release runbook.

---


Watch PhoenixFlight register governed members, assign a FlightPacket, perform a handoff, write an audit trail, and build a verified `.pflight` bundle.

![PhoenixFlight v0.1.0 MVP terminal demo](media/phoenixflight-v0.1.0-demo.gif)

> Full walkthrough video available in the [v0.1.0-mvp release assets](https://github.com/KinshukON/DynamicMembershipArchitecture/releases/tag/v0.1.0-mvp).

---

## What PhoenixFlight Is

PhoenixFlight is a **local governance-aware runtime** that implements Dynamic Membership Architecture for real workloads and agents. It provides:

- A declarative application descriptor — **PhoenixFile** — describing participants, governance policies, and runtime contracts
- A portable unit of work — **FlightPacket** — that carries identity, capabilities, context, and audit history
- A packaged distribution format — **`.pflight` bundle** — for portable, cryptographically-verified deployment
- A **CLI and REST API** for the full membership lifecycle
- A **policy engine** for trust-scored, capability-routed assignment and handoff
- An **audit trail** capturing every membership event in structured JSONL

---

## Why It Exists

Modern distributed and agentic systems assume static participants. When an agent crashes, a service migrates, or a workload is handed off between providers, most frameworks lose context, history, and governance continuity.

Dynamic Membership Architecture formalizes the contract for systems where **membership is the variable**, not the exception. PhoenixFlight is the reference implementation of that contract.

PhoenixFlight does **not** claim to replace Docker or Kubernetes. Correct framing:

> PhoenixFlight adds governance-aware membership semantics — registration, trust, assignment, handoff, retirement, and audit — to complement the infrastructure scheduling and container packaging layers provided by Docker and Kubernetes.

---

## Core Runtime Lifecycle

```
Register → Discover → Assign → Handoff → Retire → Audit
```

| Step | What happens |
|---|---|
| **Register** | An agent or service joins the runtime with identity, capabilities, trust score, and namespace |
| **Discover** | The runtime finds eligible members matching required capabilities and trust thresholds |
| **Assign** | A FlightPacket is assigned to a member using policy-governed, trust-weighted capability routing |
| **Handoff** | A packet migrates from one member to another, preserving context, history, and ownership |
| **Retire** | A member gracefully drains its assignments and exits the runtime with an audit trail |
| **Audit** | Every event — registration, assignment, handoff, retirement, denial — is written to the audit log |

---

## PhoenixFile

`PhoenixFile` is the canonical declarative application descriptor for a governed participant group. It replaces nothing — it is the native PhoenixFlight contract.

```yaml
apiVersion: phoenixflight.io/v1alpha1
kind: PhoenixApp
metadata:
  name: customer-validation-app
  namespace: tenant-a
  version: 0.1.0

runtime:
  language: python
  entrypoint: src/app.py

controlPlane:
  auth:
    provider: local
  policies:
    - policies/can-register.yaml
    - policies/can-assign.yaml
    - policies/can-handoff.yaml
  audit:
    sink: local
    format: jsonl
  assignment:
    strategy: trust-weighted-capability-routing
  governance:
    minimumTrustScore: 0.85

dataPlane:
  agents:
    - agents/governance-agent.yaml
    - agents/metadata-agent.yaml
  packets:
    - packets/customer-validation.packet.yaml
  handoffContracts:
    - contracts/customer-context-handoff.yaml

membership:
  discovery:
    mode: capability
  migration:
    enabled: true
  retirement:
    drainTimeoutSeconds: 30
```

Full spec: [docs/PHOENIXFILE.md](docs/PHOENIXFILE.md)

---

## FlightPacket

A FlightPacket is a portable unit of work. It carries:

- **Workload identity and namespace**
- **Required capability constraints**
- **Context payload** (checkpoint state)
- **Policy tags** (e.g., PII, GDPR)
- **Ownership history** (full handoff chain)
- **Audit lineage**

Packets are created from YAML manifests, assigned to members via trust-weighted routing, handed off between members preserving context, and audited at every transition.

---

## `.pflight` Bundle

A `.pflight` bundle is a portable, signed runtime archive:

```
customer-validation-app-0.1.0.pflight (ZIP)
├── PhoenixFile
├── manifest.json
├── validation-report.json
├── hashes.json              ← SHA-256 for all files
├── agents/
├── packets/
├── policies/
└── contracts/
```

Build, inspect, verify, and unpack:

```bash
python3 -m src.phoenix_cli build -f examples/customer-validation/PhoenixFile
python3 -m src.phoenix_cli bundle inspect dist/customer-validation-app-0.1.0.pflight
python3 -m src.phoenix_cli bundle verify  dist/customer-validation-app-0.1.0.pflight
python3 -m src.phoenix_cli bundle unpack  dist/customer-validation-app-0.1.0.pflight --to ./unpacked
```

Full spec: [docs/BUNDLE_FORMAT.md](docs/BUNDLE_FORMAT.md)

---

## Local Runtime State

PhoenixFlight stores all runtime state under `.phoenixflight/`:

```
.phoenixflight/
├── members.json      ← registered member registry
├── packets.json      ← active flight packets
├── audit.jsonl       ← structured audit log
└── imports/          ← local bundle registry
```

Initialize:

```bash
python3 -m src.phoenix_cli init
```

---

## CLI Quickstart

### Prerequisites

```bash
git clone https://github.com/KinshukON/DynamicMembershipArchitecture.git
cd DynamicMembershipArchitecture
pip install -e .
```

### Full Local Demo

```bash
# 1. Initialize local runtime state
phoenix init

# 2. Validate a PhoenixFile
phoenix validate -f examples/customer-validation/PhoenixFile

# 3. Register members (agents)
phoenix member register examples/customer-validation/agents/governance-agent.yaml
phoenix member register examples/customer-validation/agents/metadata-agent.yaml

# 4. List members
phoenix member list

# 5. Create a flight packet
phoenix packet create customer-validation

# 6. List packets
phoenix packet list

# 7. Assign packet to a member (auto policy-checked)
phoenix assign packet-001 --to governance-agent

# 8. Inspect a packet
phoenix inspect packet-001

# 9. Handoff to another member
phoenix handoff packet-001 --from governance-agent --to metadata-agent

# 10. Retire a member
phoenix retire governance-agent

# 11. View audit log
phoenix audit

# 12. Build a portable .pflight bundle
phoenix build -f examples/customer-validation/PhoenixFile

# 13. Inspect the bundle
phoenix bundle inspect dist/customer-validation-app-0.1.0.pflight

# 14. Cryptographically verify bundle integrity
phoenix bundle verify dist/customer-validation-app-0.1.0.pflight

# 15. Unpack a bundle
phoenix bundle unpack dist/customer-validation-app-0.1.0.pflight --to ./unpacked

# 16. Emit a Dockerfile from PhoenixFile
phoenix emit dockerfile -f examples/customer-validation/PhoenixFile

# 17. Worker lifecycle
phoenix worker start     --id worker-01
phoenix worker heartbeat --id worker-01
phoenix worker retire    --id worker-01

# 18. Local registry
phoenix registry add     dist/customer-validation-app-0.1.0.pflight
phoenix registry list
phoenix registry inspect customer-validation-app
```

### Developer fallback (no install required)

If you do not run `pip install -e .`, use the direct module invocation:

```bash
PYTHONPATH=src python3 -m src.phoenix_cli init
PYTHONPATH=src python3 -m src.phoenix_cli version
```

Full reference: [docs/CLI_REFERENCE.md](docs/CLI_REFERENCE.md)

---

## API Quickstart

Start the API server:

```bash
python3 src/server.py --port 8000
```

Open `http://localhost:8000` in your browser for the runtime console and dashboard.

REST API reference: [docs/API.md](docs/API.md)

---

## Enterprise Readiness

| Capability | Status |
|---|---|
| PhoenixFile declarative descriptor | ✅ Implemented |
| Dynamic member registry | ✅ Implemented |
| Trust-weighted capability assignment | ✅ Implemented |
| Policy-governed handoff | ✅ Implemented |
| Graceful member retirement | ✅ Implemented |
| Portable `.pflight` bundle (SHA-256 verified) | ✅ Implemented |
| Bundle verification (strict integrity check) | ✅ Implemented |
| Dockerfile emitter from PhoenixFile | ✅ Implemented |
| Structured audit trail (JSONL) | ✅ Implemented |
| SIEM audit export | ✅ Implemented |
| Runtime worker lifecycle | ✅ Implemented |
| Auth dev mode / JWT enforcement mode | ✅ Implemented |
| Namespace isolation | ✅ Implemented |
| Local bundle registry | ✅ Implemented |
| Production JWT + OIDC | 🔲 Roadmap |
| Multi-node distributed registry | 🔲 Roadmap |
| Kubernetes operator | 🔲 Roadmap |

Full assessment: [docs/ENTERPRISE_READINESS.md](docs/ENTERPRISE_READINESS.md)

---

## Research Foundation

PhoenixFlight implements **Dynamic Membership Architecture (DMA)** — a formal framework for systems where participants dynamically join, leave, migrate, fail, recover, and retire while preserving execution continuity.

The DMA framework covers three major paradigms:

1. **Phoenix-style virtual nodes** — consistent hashing across a dynamic membership ring
2. **Kubernetes-style constraint scheduling** — capacity-scored workload placement
3. **Agentic AI registries** — capability-based routing with reliability scoring

The research demonstrates that all three paradigms instantiate the same six primitives: Identity, Discovery, Assignment, Migration, Retirement, Governance.

### Running the Research Simulator

```bash
python3 src/main.py
python3 src/main.py --steps 120 --initial-resources 8 --imbalance-threshold 0.10 --seed 101
```

### Research Materials

- `paper/` — Technical paper (PDF and DOCX)
- `figures/` — Architecture diagrams
- `docs/technical_blueprint.md` — Formal mathematical specification
- `docs/ARCHITECTURE.md` — Internal design specification

---

## Current Limitations

- **Local-only runtime:** PhoenixFlight currently runs on a single machine. Distributed multi-node registry is on the roadmap.
- **No production auth by default:** `PHOENIX_AUTH_MODE=dev` is the default. Set `PHOENIX_AUTH_MODE=jwt` with `PHOENIX_JWT_SECRET` for JWT enforcement.
- **Worker executes mock tasks only:** The runtime worker uses safe non-shell handlers. Real task execution is not implemented.
- **No container image registry:** The Dockerfile emitter generates a file for review; image push requires Docker to be installed and run separately.
- **SQLite state:** Runtime state is stored in SQLite (`phoenixflight.db`) for local persistence. No distributed store.

---

## Roadmap

- Production JWT/OIDC auth integration
- Multi-node distributed registry with leader election
- Kubernetes operator (`Dockerfile.operator`)
- LangGraph and LangChain adapter (in progress — `src/langgraph_adapter.py`)
- Live migration with checkpoint transfer
- Verifiable audit log (hash chain / Merkle)
- Helm chart for Kubernetes deployment

See [docs/ROADMAP.md](docs/ROADMAP.md) for details.

---

## DOI Records

PhoenixFlight is connected to two related but distinct archival records:

| Artifact | Type | DOI |
|---|---|---|
| Dynamic Membership Architecture paper | Publication / manuscript | https://doi.org/10.5281/zenodo.20693483 |
| PhoenixFlight runtime | Software artifact / GitHub release archive | https://doi.org/10.5281/zenodo.20778458 |

The publication DOI refers to the Dynamic Membership Architecture research manuscript.  
The software DOI refers to the runnable PhoenixFlight implementation and GitHub release archive.

---

## Citation / DOI / ORCID / Author

Please cite the v1.0.0 Zenodo publication as:

Dutta, K. (2026). *Dynamic Membership Architecture: From the Phoenix Computing Model to Cloud-Native and Agentic AI Runtime Systems* (v1.0.0). Zenodo. https://doi.org/10.5281/zenodo.20693483

```bibtex
@misc{dutta2026dynamicmembershiparchitecture,
  author       = {Dutta, Kinshuk},
  title        = {Dynamic Membership Architecture: From the Phoenix Computing Model to Cloud-Native and Agentic AI Runtime Systems},
  year         = {2026},
  publisher    = {Zenodo},
  version      = {v1.0.0},
  doi          = {10.5281/zenodo.20693483},
  url          = {https://doi.org/10.5281/zenodo.20693483}
}
```

### DOIs

- Version DOI (v1.0.0): https://doi.org/10.5281/zenodo.20693483
- Concept DOI (all versions): https://doi.org/10.5281/zenodo.20693482

### Links

- Zenodo v1.0.0: https://doi.org/10.5281/zenodo.20693483
- Zenodo all-versions: https://doi.org/10.5281/zenodo.20693482
- GitHub release v1.0.0: https://github.com/KinshukON/DynamicMembershipArchitecture/releases/tag/v1.0.0
- Author ORCID: https://orcid.org/0009-0002-6039-549X
- Author website: https://kinshukdutta.ai
- Live site: https://phoenixflight.app

---

## Provenance

PhoenixFlight and the Dynamic Membership Architecture implementation are originated and authored by Kinshuk Dutta.

Passive provenance marker: `PF-DMA-KD-ORIGIN-2026-PHOENIXFLIGHT`
