|
1 | | -# ManagedCode Agent Lightning C# Migration Plan |
2 | | - |
3 | | -This document tracks the conversion of the original Python implementation to a .NET 9 / C# 13 codebase published under the ManagedCode namespace. |
4 | | -The Python reference lives in the `external/microsoft-agent-lightning` submodule and remains the |
5 | | -single source of truth for product behaviour until full parity is achieved. |
6 | | - |
7 | | -## Repository Layout |
8 | | - |
9 | | -- `external/microsoft-agent-lightning` — upstream Python sources used for reference and fixtures. |
10 | | -- `src/ManagedCode.AgentLightning.Core` — shared domain models and primitives. |
11 | | -- `src/ManagedCode.AgentLightning.AgentRuntime` — runtime orchestration for agents backed by `Microsoft.Extensions.AI`. |
12 | | -- `src/ManagedCode.AgentLightning.Cli` — self-hosted CLI harness that exercises the C# runtime. |
13 | | -- `tests/ManagedCode.AgentLightning.Tests` — xUnit test suite validating the C# port. |
14 | | - |
15 | | -## Python Module Inventory |
16 | | - |
17 | | -| Python Module | Summary | Migration Target | Status | Notes | |
18 | | -|-------------------------------------------------------------------|--------------------------------------------------------------|-------------------------------------------------|----------------|-------| |
19 | | -| `agentlightning/types/core.py`, `types/tracer.py` | Core data models, spans, rollouts | `ManagedCode.AgentLightning.Core/Models` | **In progress** | Triplet, Rollout, Attempt ported; tracer shapes pending. | |
20 | | -| `agentlightning/litagent/` | Agent lifecycle, rollout orchestration | `ManagedCode.AgentLightning.AgentRuntime` | **In progress** | `LightningAgent` implemented with `IChatClient`; advanced features pending. | |
21 | | -| `agentlightning/runner/` | Runner coordination, hooks, parallel execution | `ManagedCode.AgentLightning.AgentRuntime` | Not started | Need scheduling and multi-attempt coordination. | |
22 | | -| `agentlightning/tracer/` | OpenTelemetry integrations | `ManagedCode.AgentLightning.Core` / `ManagedCode.AgentLightning.AgentRuntime` | Not started | Requires .NET OTEL pipeline. | |
23 | | -| `agentlightning/store/` | Persistence layer | TBD | Not started | Identify .NET storage abstraction. | |
24 | | -| `agentlightning/reward/` | Reward calculation utilities | TBD | Not started | Requires parity with RL tooling. | |
25 | | -| `agentlightning/adapter/`, `execution/`, `algorithm/`, `trainer/` | Training pipelines, adapters, algorithms | TBD | Not started | Dependent on runner and tracer ports. | |
26 | | -| `agentlightning/cli/` | Python CLI entry points | `ManagedCode.AgentLightning.Cli` | **In progress** | New CLI harness available; parity with Python commands pending. | |
27 | | -| `agentlightning/server.py`, `client.py` | Legacy HTTP server/client | Separate ASP.NET/API project (future) | Not started | Decide on long-term hosting story. | |
28 | | -| `agentlightning/logging.py` | Logging helpers | `.NET logging abstractions` | **In progress** | Logging routed through `Microsoft.Extensions.Logging`. | |
29 | | -| `tests/` | Integration and parity tests | `tests/ManagedCode.AgentLightning.Tests` | Not started | Need fixtures mirroring upstream scenarios. | |
| 1 | + |
| 2 | +# ManagedCode Agent Lightning Migration Plan |
| 3 | + |
| 4 | +This plan tracks parity work between `external/microsoft-agent-lightning` (Python) and the C# port. |
| 5 | + |
| 6 | +## Status Legend |
| 7 | + |
| 8 | +- ✅ Complete in C# |
| 9 | +- 🚧 Planned / not yet ported |
| 10 | +- ❓ Needs investigation / decide if we port |
| 11 | + |
| 12 | +## Core Building Blocks |
| 13 | + |
| 14 | +| Component | Python Source | Status | Notes | |
| 15 | +| --- | --- | --- | --- | |
| 16 | +| Domain models | `agentlightning/types/core.py` | ✅ | `ManagedCode.AgentLightning.Core/Models` – rollout/attempt/triplet + hooks | |
| 17 | +| Tracing models | `agentlightning/types/tracer.py` | ✅ | `ManagedCode.AgentLightning.Core/Tracing` – span DTOs & helpers with OpenTelemetry tests | |
| 18 | +| Resources | `agentlightning/types/resources.py` | ✅ | `ManagedCode.AgentLightning.Core/Resources` – LLM/proxy/prompt resources mirrored | |
| 19 | +| LitAgent base | `agentlightning/litagent/litagent.py` | ✅ | `LitAgentBase<T>` with hook lifecycle, `LightningAgent` derives from it | |
| 20 | +| Adapter infrastructure | `agentlightning/adapter/base.py` | ✅ | `Adapters/Adapter`, `TraceAdapter`, `TraceToMessagesAdapter` implemented with tests | |
| 21 | +| Runner infrastructure | `agentlightning/runner/base.py` | ✅ | `LitAgentRunner` processes rollouts via LightningAgent and stores spans | |
| 22 | +| Store interface | `agentlightning/store/base.py` | ✅ | `ILightningStore` contract + `InMemoryLightningStore` covering queue/attempt/span lifecycle | |
| 23 | +| Trainer orchestration | `agentlightning/trainer/trainer.py` | ✅ | `Trainer` orchestrates batches via store + runner (tested) | |
| 24 | + |
| 25 | +## Span & Resource Adapters |
| 26 | + |
| 27 | +| Adapter | Python Source | Status | Notes | |
| 28 | +| --- | --- | --- | --- | |
| 29 | +| Trace → messages | `adapter/messages.py` | 🚧 | Convert spans to chat history for `IChatClient` | |
| 30 | +| Trace → triplets | `adapter/triplet.py` | 🚧 | Build reward-aware triplets from spans | |
| 31 | +| OTEL trace adapter | `adapter/base.py` | 🚧 | Hook Activity -> SpanModel bridging | |
| 32 | + |
| 33 | +## Execution & Store Layers |
| 34 | + |
| 35 | +| Component | Python Source | Status | Notes | |
| 36 | +| --- | --- | --- | --- | |
| 37 | +| LightningStore (async) | `store/base.py` | 🚧 | Async contract mirroring enqueue/start/query APIs | |
| 38 | +| In-memory store | `store/memory.py` | 🚧 | Production-grade concurrency port | |
| 39 | +| Client/server bridge | `store/client_server.py` | ❓ | Decide ASP.NET hosting approach | |
| 40 | +| Runner execution strategies | `execution/*` | 🚧 | Channel/task-based equivalents | |
| 41 | + |
| 42 | +## Algorithms & Training Pipelines |
| 43 | + |
| 44 | +| Component | Python Source | Status | Notes | |
| 45 | +| --- | --- | --- | --- | |
| 46 | +| Algorithm base class | `algorithm/base.py` | 🚧 | Define async lifecycle (`SetupAsync`, `TrainAsync`, `TeardownAsync`) with dataset plumbing | |
| 47 | +| Fast baseline algorithms | `algorithm/fast.py` | ❓ | Decide whether to port representative baseline for smoke tests | |
| 48 | +| APO (Automatic Prompt Optimization) | `algorithm/apo/apo.py` | 🚧 | Requires prompt diffing, versioned templates, and evaluation harness | |
| 49 | +| VERL distributed trainer | `algorithm/verl/*` | ❓ | Needs multi-process orchestration design in .NET (potential future phase) | |
| 50 | +| Trainer legacy compat | `trainer/legacy.py` | 🚧 | Implement legacy hooks while aligning with new runner/store abstractions | |
| 51 | +| Trainer orchestration | `trainer/trainer.py` | 🚧 | Port training loop, scheduler, and algorithm/run coordination | |
| 52 | +| Registry/config utilities | `trainer/registry.py`, `trainer/init_utils.py` | 🚧 | Recreate component registration and config binding over `Options` | |
| 53 | + |
| 54 | +## Reward & Instrumentation |
| 55 | + |
| 56 | +| Component | Python Source | Status | Notes | |
| 57 | +| --- | --- | --- | --- | |
| 58 | +| Reward emitters | `emitter/reward.py`, `reward.py` | 🚧 | Implement reward span helpers with OTEL integration | |
| 59 | +| Message/object emitters | `emitter/message.py`, `emitter/object.py`, `emitter/utils.py` | 🚧 | Required for parity in trace adapters | |
| 60 | +| Instrumentation (AgentOps, LiteLLM, vLLM) | `instrumentation/*` | ❓ | Determine .NET bindings and optionality | |
| 61 | +| Logging utilities | `logging.py` | ✅ | Replaced with `Microsoft.Extensions.Logging` configuration helpers | |
| 62 | +| LLM proxy instrumentation | `llm_proxy.py` | ❓ | Evaluate hosting (ASP.NET Core) and span exporter support | |
| 63 | + |
| 64 | +## Fixtures, Docs & Tooling |
| 65 | + |
| 66 | +| Area | Status | Notes | |
| 67 | +| --- | --- | --- | |
| 68 | +| Python fixture import | 🚧 | Need harness to reuse JSON/SQLite fixtures from submodule | |
| 69 | +| Integration test parity | 🚧 | Blocked until adapters, store, runner port complete | |
| 70 | +| Docs & README updates | 🚧 | Document hosting, configuration, and migration progress | |
| 71 | +| Packaging & CI | ✅ | .NET solution, format/test gates, and workflows in place | |
| 72 | + |
| 73 | +## External Interfaces |
| 74 | + |
| 75 | +| Component | Python Source | Status | Notes | |
| 76 | +| --- | --- | --- | --- | |
| 77 | +| LLM proxy service | `llm_proxy.py` | ❓ | Evaluate ASP.NET Core standalone proxy | |
| 78 | +| Logging helpers | `logging.py` | ✅ | Using `Microsoft.Extensions.Logging` | |
| 79 | +| Legacy server/client | `server.py`, `client.py` | ❓ | Decide on support for legacy flows | |
| 80 | + |
| 81 | +## Test Parity |
| 82 | + |
| 83 | +| Area | Status | Notes | |
| 84 | +| --- | --- | --- | |
| 85 | +| Core models & resources | ✅ | Unit tests in `ManagedCode.AgentLightning.Tests` | |
| 86 | +| Span conversions | ✅ | `Tracing/SpanModelTests` | |
| 87 | +| Resource helper coverage | ✅ | `Resources/ResourceModelTests` | |
| 88 | +| Adapter tests | 🚧 | Need to mirror upstream fixtures | |
| 89 | +| Runner/store/trainer integration | 🚧 | Blocked until components ported | |
30 | 90 |
|
31 | 91 | ## Completed Work |
32 | 92 |
|
33 | | -- Converted repository scaffold to .NET 9 / C# 13 solution with central package management. |
34 | | -- Implemented core rollout models (`Triplet`, `Attempt`, `Rollout`, hooks) in `ManagedCode.AgentLightning.Core`. |
35 | | -- Ported fundamental agent execution pipeline powered by `Microsoft.Extensions.AI.IChatClient`. |
36 | | -- Added `LocalChatClient` for offline validation and connected CLI harness. |
37 | | -- Established CI, CodeQL, and release workflows mirroring ManagedCode patterns. |
38 | | -- Added initial integration test covering `LightningAgent` execution against the local client. |
| 93 | +- .NET 9 solution scaffolding with central package management |
| 94 | +- Core rollout/attempt models and runtime scaffolding (`LightningAgent` + `LocalChatClient`) |
| 95 | +- CI/CodeQL/release workflows (ManagedCode templates) |
| 96 | +- Span/resource models with OpenTelemetry conversions and unit coverage |
39 | 97 |
|
40 | 98 | ## Near-Term Priorities |
41 | 99 |
|
42 | | -1. Port tracer data structures (`Span`, OTEL conversions) and integrate with .NET OpenTelemetry. |
43 | | -2. Bring over runner orchestration primitives (parallel workers, retry policies, resource slots). |
44 | | -3. Reproduce Python parity tests by sourcing fixtures from the submodule. |
45 | | -4. Introduce configurable connectors for real AI providers using `Microsoft.Extensions.AI` builders. |
46 | | -5. Document configuration and extension points in `README.md`. |
47 | | - |
48 | | -## Tracking Progress |
| 100 | +1. Port trace adapters (messages, triplets) to convert spans into actionable payloads. |
| 101 | +2. Implement store abstractions (interface + in-memory implementation) to unblock runner tests. |
| 102 | +3. Port runner orchestration and cover end-to-end execution (agent + store + adapters). |
| 103 | +4. Reproduce key Python fixtures/tests for adapters and store logic. |
| 104 | +5. Plan hosting story for LLM proxy / legacy endpoints (document decisions). |
49 | 105 |
|
50 | | -Update this file whenever: |
| 106 | +## Tracking Guidance |
51 | 107 |
|
52 | | -- A Python module gains a parity implementation or has design decisions documented. |
53 | | -- Tests are ported or new coverage approaches are introduced. |
54 | | -- Workflow or packaging behaviours change. |
55 | | -- Deprecated guidance is removed or superseded. |
| 108 | +Update this document whenever a component moves between statuses or when new design decisions affect parity. |
0 commit comments