# Fluxibly — Changes & Removals from Current Design

This document details all changes needed to migrate from the current architecture to the new design described in `new_design.md`.

---

## Summary of Changes

| Category | Action | Impact |
|----------|--------|--------|
| **LLM Layer** | Complete rewrite | New BaseLLM with prepare()/forward() returning LLMResponse |
| **Agent Layer** | Complete rewrite | New BaseAgent/SimpleAgent, remove Orchestrator |
| **Tools Layer** | New addition | ToolService managing all tool types across providers |
| **Orchestrator** | **Remove entirely** | Replaced by Agent layer's flexible forward() |
| **Workflow Engine** | **Remove entirely** | Agents are self-contained; no engine needed |
| **State Management** | **Remove entirely** | Messages managed at LLM level, no DB persistence layer |
| **Schema/Input** | **Remove entirely** | Replaced by new schema/ module |
| **Config System** | Rewrite | Simpler loader, new YAML format for LLM & Agent |
| **Logging** | Rewrite | New Logger class with component/type tagging |
| **Dependencies** | Reduce | Remove LangGraph; make providers optional |
| **MCP Client** | Keep & refactor | Integrate into ToolService |
| **Tests** | Rewrite | New tests matching new architecture |

---

## 1. Files/Directories to REMOVE

### 1.1 Orchestrator (entire module)

**Remove: `fluxibly/orchestrator/`**

| File | Reason |
|------|--------|
| `fluxibly/orchestrator/__init__.py` | Module removed |
| `fluxibly/orchestrator/agent.py` | OrchestratorAgent replaced by flexible Agent layer |
| `fluxibly/orchestrator/planner.py` | TaskPlanner not needed — Agent forward() handles all logic |
| `fluxibly/orchestrator/executor.py` | PlanExecutor not needed — Agent handles execution |
| `fluxibly/orchestrator/selector.py` | MCPSelector not needed — tools managed by ToolService |
| `fluxibly/orchestrator/synthesizer.py` | ResultSynthesizer not needed — Agent handles synthesis |
| `fluxibly/orchestrator/config/__init__.py` | Config module removed |
| `fluxibly/orchestrator/config/prompts.py` | Prompt loading not needed — prompts in YAML config |
| `config/orchestrator/prompts.yaml` | Orchestrator prompts removed |

**Why:** The orchestrator was a rigid multi-step planner/executor. In the new design, an Agent's forward() can contain any logic — simple or complex. Users who need multi-step planning can implement a custom Agent subclass. The framework doesn't force this pattern.

### 1.2 Workflow Engine (entire module)

**Remove: `fluxibly/workflow/`**

| File | Reason |
|------|--------|
| `fluxibly/workflow/__init__.py` | Module removed |
| `fluxibly/workflow/engine.py` | WorkflowEngine & WorkflowSession removed |
| `fluxibly/workflow/config.py` | WorkflowConfig removed |

**Why:** The WorkflowEngine was a lifecycle manager (init → execute → shutdown). In the new design:
- Agents are self-contained — create, call forward(), done
- MCP lifecycle managed by ToolService (or MCPClientManager directly)
- No need for an extra orchestration layer between user and Agent

### 1.3 State Management (entire module)

**Remove: `fluxibly/state/`**

| File | Reason |
|------|--------|
| `fluxibly/state/__init__.py` | Module removed |
| `fluxibly/state/schema.py` | AgentState (LangGraph state) — LangGraph removed |
| `fluxibly/state/models.py` | ChatThread & ChatMessage — DB persistence removed |
| `fluxibly/state/manager.py` | StateManager — replaced by in-memory message management |
| `fluxibly/state/repository.py` | ConversationRepository — DB abstraction removed |
| `fluxibly/state/config.py` | State config removed |

**Why:** Conversation history is now managed as a simple `list[dict]` at the LLM level. The framework doesn't need database persistence — that's an application-level concern. Users can persist messages externally if needed.

### 1.4 Existing Agent Module (rewrite, not just remove)

**Remove & Replace: `fluxibly/agent/`**

| File | Action | Reason |
|------|--------|--------|
| `fluxibly/agent/base.py` | Rewrite | Current Agent class has MCP-specific logic baked in. New BaseAgent is clean abstract. |
| `fluxibly/agent/config.py` | Rewrite | AgentConfig redesigned with new fields |
| `fluxibly/agent/conversation.py` | Remove | ConversationHistory class removed — messages managed at LLM level |
| `fluxibly/agent/__init__.py` | Rewrite | New exports |

### 1.5 Existing LLM Module (rewrite)

**Remove & Replace: `fluxibly/llm/`**

| File | Action | Reason |
|------|--------|--------|
| `fluxibly/llm/base.py` | Rewrite | New BaseLLM with prepare()/forward() returning LLMResponse |
| `fluxibly/llm/langchain_llm.py` | Rewrite | New LangChainLLM implementation |
| `fluxibly/llm/litellm_llm.py` | Rewrite | New LiteLLM implementation (rename from litellm_wrapper) |
| `fluxibly/llm/custom_llm.py` | Remove | Not needed — users extend BaseLLM directly |
| `fluxibly/llm/__init__.py` | Rewrite | New exports |

**New files to add:**
- `fluxibly/llm/openai_llm.py` — Native OpenAI (chat + responses API)
- `fluxibly/llm/anthropic_llm.py` — Native Anthropic
- `fluxibly/llm/gemini_llm.py` — Native Gemini
- `fluxibly/llm/registry.py` — LLM registry & factory

### 1.6 Existing Schema Module

**Remove & Replace: `fluxibly/schema/`**

| File | Action | Reason |
|------|--------|--------|
| `fluxibly/schema/input.py` | Remove | Input validation replaced by AgentConfig |
| `fluxibly/schema/__init__.py` | Rewrite | New exports |

**New files to add:**
- `fluxibly/schema/response.py` — LLMResponse, LLMOutput, LLMMetadata, TokenUsage
- `fluxibly/schema/tools.py` — ToolCall, ToolResult, Citation, ContentItem

### 1.7 Config Profiles (domain-specific)

**Remove: `config/profiles/`**

| File | Reason |
|------|--------|
| `config/profiles/rag_assistant.yaml` | Domain-specific (RAG); not framework concern |
| `config/profiles/travel_assistant.yaml` | Domain-specific (travel); not framework concern |

**Why:** The new design doesn't have a profile system. Each Agent has its own YAML config. Domain-specific configurations are application concerns, not framework concerns.

### 1.8 Config Files

| File | Action | Reason |
|------|--------|--------|
| `config/framework.yaml` | Remove | No more framework-level defaults. Each Agent/LLM has its own config. |
| `config/mcp_servers.yaml` | Keep & update | MCP server definitions still needed |
| `config/orchestrator/prompts.yaml` | Remove | Orchestrator removed |

### 1.9 Examples & MCP Servers (domain-specific)

| File/Dir | Action | Reason |
|----------|--------|--------|
| `examples/rag_template_filling.py` | Remove | RAG-specific; not relevant to new framework |
| `examples/test_stateful_context.py` | Remove | Replaced with new examples |
| `examples/resources/` | Remove | RAG-specific resources |
| `examples/README_RAG_TEMPLATE_FILLING.md` | Remove | RAG-specific docs |
| `mcp_servers/custom_rag/` | Remove | Domain-specific MCP server |
| `mcp_servers/simple_math/` | Keep | Good example MCP server |

### 1.10 Existing Config Module

| File | Action | Reason |
|------|--------|--------|
| `fluxibly/config/loader.py` | Rewrite | Simpler loader, no profile system |
| `fluxibly/config/env.py` | Keep & simplify | Remove LangSmith-specific utilities |
| `fluxibly/config/__init__.py` | Rewrite | New exports |

### 1.11 Existing MCP Client

| File | Action | Reason |
|------|--------|--------|
| `fluxibly/mcp_client/manager.py` | Keep & refactor | Move to `fluxibly/tools/mcp_manager.py`, integrate with ToolService |
| `fluxibly/mcp_client/__init__.py` | Remove | Module moves to tools/ |

---

## 2. Files to ADD

### 2.1 New LLM Implementations

| File | Description |
|------|-------------|
| `fluxibly/llm/openai_llm.py` | Native OpenAI (chat + responses API support) |
| `fluxibly/llm/anthropic_llm.py` | Native Anthropic Messages API |
| `fluxibly/llm/gemini_llm.py` | Native Google Gemini API |
| `fluxibly/llm/registry.py` | LLM registry, factory function, auto-registration |

### 2.2 New Agent Module

| File | Description |
|------|-------------|
| `fluxibly/agent/base.py` | BaseAgent (abstract), AgentConfig, AgentResponse |
| `fluxibly/agent/simple_agent.py` | SimpleAgent implementation |

### 2.3 New Tools Module

| File | Description |
|------|-------------|
| `fluxibly/tools/__init__.py` | Exports |
| `fluxibly/tools/service.py` | ToolService — central tool management & execution |
| `fluxibly/tools/mcp_manager.py` | MCPClientManager (refactored from current) |
| `fluxibly/tools/function_executor.py` | Python function tool execution |
| `fluxibly/tools/types.py` | Tool type definitions & schemas |

### 2.4 New Schema Module

| File | Description |
|------|-------------|
| `fluxibly/schema/response.py` | LLMResponse, LLMOutput, LLMMetadata, TokenUsage |
| `fluxibly/schema/tools.py` | ToolCall, ToolResult, Citation, ContentItem |

### 2.5 New Logging Module

| File | Description |
|------|-------------|
| `fluxibly/logging/__init__.py` | Exports |
| `fluxibly/logging/logger.py` | Logger class with component/type tagging |

### 2.6 Exceptions

| File | Description |
|------|-------------|
| `fluxibly/exceptions.py` | Full exception hierarchy |

### 2.7 New Examples

| File | Description |
|------|-------------|
| `examples/basic_agent.py` | Simple agent usage |
| `examples/agent_with_tools.py` | Agent with MCP tools |
| `examples/multi_agent.py` | Agent with sub-agents |
| `examples/direct_llm.py` | Direct LLM usage without agent |

### 2.8 New Config Examples

| File | Description |
|------|-------------|
| `config/examples/simple_agent.yaml` | Example agent config |

---

## 3. Detailed Changes

### 3.1 LLM Layer Changes

| Aspect | Current | New |
|--------|---------|-----|
| **Base class** | `BaseLLM` with `forward(prompt: str) -> str` | `BaseLLM` with `prepare() -> dict`, `forward() -> LLMResponse` |
| **Input format** | Single string prompt | List of message dicts + tools |
| **Output format** | Raw string | Standardized `LLMResponse` with output, metadata, usage |
| **Message management** | None (done at Agent level) | Built into LLM: `set_messages()`, `add_message()`, etc. |
| **Tool support** | None (done at Agent level) | Built into LLM: `set_tools()`, formatted in `prepare()` |
| **Providers** | LangChain, LiteLLM only | OpenAI (native), Anthropic (native), Gemini (native), LangChain, LiteLLM |
| **OpenAI API** | Chat Completions only (via LangChain) | Both Chat Completions AND Responses API |
| **Retry logic** | Config exists but not implemented | Implemented in each provider's `forward()` |
| **Streaming** | `forward_stream() -> Generator[str]` | `forward_stream() -> Generator[LLMResponseChunk]` |
| **Logging** | Basic loguru | Structured Logger with type tags |

### 3.2 Agent Layer Changes

| Aspect | Current | New |
|--------|---------|-----|
| **Base class** | `Agent` with hardcoded MCP logic | `BaseAgent` (abstract), `SimpleAgent` (implementation) |
| **Orchestrator** | `OrchestratorAgent` with planner/executor/synthesizer | Removed. Custom agents can implement any logic. |
| **forward() input** | `(user_prompt: str, context: dict)` | `(messages: list[dict], context: dict)` — caller owns conversation history |
| **forward() output** | `str` (raw text) | `AgentResponse` with `content: LLMResponse` and `metadata: dict` |
| **Tool calling** | Text-based JSON parsing, 2 LLM calls | Native provider tool calling, agentic loop |
| **MCP integration** | Baked into Agent class | Delegated to ToolService/MCPClientManager |
| **Sub-agents** | Not supported | Agents can manage other agents (used as tools) |
| **Prompt templates** | Static string | Template with `{param}` substitution from context |
| **Conversation** | ConversationHistory class with token counting | Caller-managed `messages: list[dict]` passed into `forward()` |
| **Config** | AgentConfig + OrchestratorConfig | Single AgentConfig with all fields |

### 3.3 Tool Handling Changes

| Aspect | Current | New |
|--------|---------|-----|
| **Tool types** | MCP only | Functions, MCP, web search, file search, shell, skills, computer use |
| **Tool format** | Custom internal format | Unified format per tool type (see new_design.md Section 11) |
| **Tool selection** | LLM-based JSON selection (fragile) | Native provider tool calling (reliable) |
| **Tool execution** | MCPClientManager.invoke_tool() | ToolService.execute() — dispatches to right executor |
| **Tool results** | String returned to prompt | ToolResult objects fed back via message protocol |
| **MCP management** | In MCPClientManager | In ToolService wrapping MCPClientManager |

### 3.4 Configuration Changes

| Aspect | Current | New |
|--------|---------|-----|
| **Structure** | Hierarchical: framework.yaml → profiles → runtime | Per-component: each LLM/Agent has its own YAML |
| **Profile system** | ConfigLoader.load_profile() with deep merge | Removed. Direct YAML loading. |
| **LLM config** | `LLMConfig` with `framework` field | `LLMConfig` with `api_type` field (for OpenAI) |
| **Agent config** | `AgentConfig` + `OrchestratorConfig` | Single `AgentConfig` with all fields |
| **MCP config** | Separate mcp_servers.yaml | Kept as-is |
| **Env vars** | `env.py` with LangSmith support | Simplified env loading |

### 3.5 Dependency Changes

| Dependency | Current | New | Reason |
|-----------|---------|-----|--------|
| `langgraph` | Required | **Remove** | No longer using LangGraph for orchestration |
| `langchain` | Required | Optional (`[langchain]`) | Only needed for LangChainLLM |
| `langchain-core` | Required | Optional (`[langchain]`) | Same |
| `langchain-openai` | Required | Optional (`[langchain]`) | Same |
| `langchain-anthropic` | Required | Optional (`[langchain]`) | Same |
| `langchain-google-genai` | Required | Optional (`[langchain]`) | Same |
| `openai` | Not used | Optional (`[openai]`) | Native OpenAI support |
| `anthropic` | Not used directly | Optional (`[anthropic]`) | Native Anthropic support |
| `google-generativeai` | Not used directly | Optional (`[gemini]`) | Native Gemini support |
| `litellm` | Required | Optional (`[litellm]`) | Only needed for LiteLLM |
| `pydantic` | Required | Required | Core validation |
| `pydantic-settings` | Required | **Remove** | Not needed |
| `pyyaml` | Required | Required | Config loading |
| `loguru` | Required | Required | Logging |
| `python-dotenv` | Required | Required | Env loading |
| `anyio` | Required | Required | Async support |
| `httpx` | Required | Optional | HTTP client |
| `mcp` | Required | Required | MCP protocol |

### 3.6 Public API Changes

| Current Export | New Export | Status |
|---------------|-----------|--------|
| `run_workflow()` | — | **Removed** |
| `run_batch_workflow()` | — | **Removed** |
| `WorkflowEngine` | — | **Removed** |
| `WorkflowConfig` | — | **Removed** |
| `WorkflowSession` | — | **Removed** |
| `OrchestratorAgent` | — | **Removed** |
| `MCPClientManager` | `MCPClientManager` | Kept (moved to tools/) |
| `load_env` | `load_env` | Kept |
| `get_api_key` | `get_api_key` | Kept |
| `configure_langsmith` | — | **Removed** |
| `is_langsmith_enabled` | — | **Removed** |
| — | `BaseLLM` | **New** |
| — | `OpenAILLM` | **New** |
| — | `AnthropicLLM` | **New** |
| — | `GeminiLLM` | **New** |
| — | `LangChainLLM` | **New** |
| — | `LiteLLM` | **New** |
| — | `create_llm` | **New** |
| — | `register_llm` | **New** |
| — | `LLMConfig` | **New** |
| — | `BaseAgent` | **New** |
| — | `SimpleAgent` | **New** |
| — | `AgentConfig` | **New** |
| — | `AgentResponse` | **New** |
| — | `LLMResponse` | **New** |
| — | `LLMOutput` | **New** |
| — | `ToolCall` | **New** |
| — | `ToolResult` | **New** |
| — | `ToolService` | **New** |
| — | `ConfigLoader` | **New** |
| — | `Logger` | **New** |

---

## 4. Test Changes

### 4.1 Tests to Remove

| File | Reason |
|------|--------|
| `tests/unit/test_agent.py` | Agent rewritten |
| `tests/unit/test_llm.py` | LLM rewritten |
| `tests/unit/test_mcp_client_manager.py` | MCP manager refactored |
| `tests/unit/test_orchestrator_agent.py` | Orchestrator removed |
| `tests/unit/test_orchestrator_executor.py` | Orchestrator removed |
| `tests/unit/test_orchestrator_planner.py` | Orchestrator removed |
| `tests/unit/test_orchestrator_prompts.py` | Orchestrator removed |
| `tests/unit/test_orchestrator_selector.py` | Orchestrator removed |
| `tests/unit/test_orchestrator_synthesizer.py` | Orchestrator removed |

### 4.2 Tests to Add

| File | Description |
|------|-------------|
| `tests/unit/test_llm_base.py` | BaseLLM interface tests |
| `tests/unit/test_openai_llm.py` | OpenAI LLM (both API types) |
| `tests/unit/test_anthropic_llm.py` | Anthropic LLM |
| `tests/unit/test_gemini_llm.py` | Gemini LLM |
| `tests/unit/test_langchain_llm.py` | LangChain LLM |
| `tests/unit/test_litellm.py` | LiteLLM |
| `tests/unit/test_llm_response.py` | LLMResponse parsing |
| `tests/unit/test_simple_agent.py` | SimpleAgent |
| `tests/unit/test_tool_service.py` | ToolService |
| `tests/unit/test_mcp_manager.py` | MCPClientManager (updated) |
| `tests/unit/test_config_loader.py` | ConfigLoader |
| `tests/integration/test_end_to_end.py` | Full pipeline test |

---

## 5. Migration Path

### Phase 1: Foundation (LLM Layer)
1. Create `fluxibly/schema/` with all response types
2. Create `fluxibly/logging/` with Logger
3. Create `fluxibly/exceptions.py`
4. Rewrite `fluxibly/llm/base.py` with new BaseLLM
5. Create `fluxibly/llm/registry.py`
6. Create `fluxibly/llm/openai_llm.py`
7. Create `fluxibly/llm/anthropic_llm.py`
8. Create `fluxibly/llm/gemini_llm.py`
9. Rewrite `fluxibly/llm/langchain_llm.py`
10. Rewrite `fluxibly/llm/litellm_llm.py`

### Phase 2: Tools Layer
1. Create `fluxibly/tools/` module
2. Refactor MCPClientManager → `fluxibly/tools/mcp_manager.py`
3. Create `fluxibly/tools/service.py` (ToolService)
4. Create `fluxibly/tools/function_executor.py`
5. Create `fluxibly/tools/types.py`

### Phase 3: Agent Layer
1. Rewrite `fluxibly/agent/base.py` with new BaseAgent
2. Create `fluxibly/agent/simple_agent.py`

### Phase 4: Config & Integration
1. Rewrite `fluxibly/config/loader.py`
2. Simplify `fluxibly/config/env.py`
3. Rewrite `fluxibly/__init__.py` with new public API
4. Update `pyproject.toml` with new dependencies

### Phase 5: Cleanup
1. Remove `fluxibly/orchestrator/` (entire directory)
2. Remove `fluxibly/workflow/` (entire directory)
3. Remove `fluxibly/state/` (entire directory)
4. Remove `fluxibly/mcp_client/` (moved to tools/)
5. Remove domain-specific configs and examples
6. Remove old tests, add new tests

### Phase 6: Documentation & Examples
1. Create new examples
2. Update README
3. Create example YAML configs

---

## 6. Breaking Changes Summary

This is a **complete rewrite**. There is no backward compatibility with v0.2.x. Key breaking changes:

1. **No more `run_workflow()` / `run_batch_workflow()`** — use `agent.forward()` directly
2. **No more `WorkflowEngine` / `WorkflowSession`** — create Agent instances directly
3. **No more `OrchestratorAgent`** — implement custom Agent subclass if needed
4. **LLM `forward()` returns `LLMResponse` not `str`** — use `response.output.output_text` for text
5. **Agent `forward()` returns `AgentResponse` not `str`** — use `result.content.output.output_text`
6. **Config format changed** — new YAML structure for LLM and Agent configs
7. **Dependencies changed** — LangGraph removed, providers now optional extras
8. **No built-in DB persistence** — manage conversation persistence at application level
