Skip to content

Build AI methods with your coding agent, then run them anywhere: as an MCP for chatbots, as a webapp for people, or via API for your software.

fixapi

thomashebrard5509043bcea6
diff --git a/pipelex/client/api_serializer.py b/pipelex/client/api_serializer.py
index 03a0f0934..1c703c26e 100644
--- a/pipelex/client/api_serializer.py
+++ b/pipelex/client/api_serializer.py
@@ -2,16 +2,12 @@ from datetime import datetime
from decimal import Decimal
from enum import Enum
from pathlib import Path
-from typing import TYPE_CHECKING, Any, cast
+from typing import Any, cast
-from pipelex.client.protocol import DictMemory
-from pipelex.core.concepts.concept_native import NativeConceptCode
+from pipelex.client.protocol import DictMemory, ImplicitMemory
from pipelex.core.memory.working_memory import WorkingMemory
from pipelex.core.pipes.pipe_output import PipeOutput
-if TYPE_CHECKING:
- from pipelex.core.stuffs.text_content import TextContent
-
class ApiSerializer:
"""Handles API-specific serialization with kajson, datetime formatting, and cleanup."""
@@ -21,7 +17,7 @@ class ApiSerializer:
FIELDS_TO_SKIP = ("__class__", "__module__")
@classmethod
- def serialize_working_memory_for_api(cls, working_memory: WorkingMemory | None = None) -> DictMemory:
+ def serialize_working_memory_for_api(cls, working_memory: WorkingMemory | None = None) -> ImplicitMemory:
"""Convert WorkingMemory to API-ready format using kajson with proper datetime handling.
Args:
@@ -29,32 +25,22 @@ class ApiSerializer:
Returns:
ImplicitMemory ready for API transmission with datetime strings and no __class__/__module__.
- Its
"""
- dict_memory: DictMemory = {}
+ implicit_memory: ImplicitMemory = {}
if working_memory is None:
- return dict_memory
+ return implicit_memory
for stuff_name, stuff in working_memory.root.items():
- if NativeConceptCode.is_text_concept(concept_code=stuff.concept.code):
- stuff_content = cast("TextContent", stuff.content)
- item_dict: dict[str, Any] = {
- "concept_code": stuff.concept.code,
- "content": stuff_content.text,
- }
- else:
- content_dict = stuff.content.model_dump(serialize_as_any=True)
- clean_content = cls._clean_and_format_content(content_dict)
-
- item_dict = {
- "concept_code": stuff.concept.code,
- "content": clean_content,
- }
-
- dict_memory[stuff_name] = item_dict
-
- return dict_memory
+ content_dict = stuff.content.model_dump(serialize_as_any=True)
+ clean_content = cls._clean_and_format_content(content_dict)
+
+ implicit_memory[stuff_name] = {
+ "concept": stuff.concept.code,
+ "content": clean_content,
+ }
+
+ return implicit_memory
@classmethod
def serialize_pipe_output_for_api(cls, pipe_output: PipeOutput) -> DictMemory:
diff --git a/pipelex/client/client.py b/pipelex/client/client.py
index ed3e488b6..ab447487d 100644
--- a/pipelex/client/client.py
+++ b/pipelex/client/client.py
@@ -54,14 +54,14 @@ class PipelexClient(PipelexProtocol):
await self.client.aclose()
self.client = None
- async def _make_api_call(self, endpoint: str, request: str | None = None) -> Any:
+ async def _make_api_call(self, endpoint: str, request: str | None = None) -> dict[str, Any]:
"""Make an API call to the Pipelex server.
Args:
endpoint: The API endpoint to call, relative to the base URL
request: A JSON-formatted string to send as the request body, or None if no body is needed
Returns:
- Any: The JSON-decoded response from the server
+ dict[str, Any]: The JSON-decoded response from the server
Raises:
httpx.HTTPError: If the request fails or returns a non-200 status code
@@ -74,7 +74,8 @@ class PipelexClient(PipelexProtocol):
content = request.encode("utf-8") if request is not None else None
response = await self.client.post(f"/{endpoint}", content=content, headers={"Content-Type": "application/json"}, timeout=1200)
response.raise_for_status()
- return response.json()
+ response_data: dict[str, Any] = response.json()
+ return response_data
@override
async def execute_pipeline(
@@ -87,7 +88,7 @@ class PipelexClient(PipelexProtocol):
dynamic_output_concept_code: str | None = None,
) -> PipelineResponse:
if working_memory and inputs:
- msg = f"working_memory and inputs cannot be provided together to the API execute_pipeline {pipe_code=}"
+ msg = f"'working_memory' and 'inputs' cannot be provided together to the API execute_pipeline {pipe_code=}."
raise ValueError(msg)
if inputs is not None:
@@ -99,6 +100,7 @@ class PipelexClient(PipelexProtocol):
output_multiplicity=output_multiplicity,
dynamic_output_concept_code=dynamic_output_concept_code,
)
+
response = await self._make_api_call(f"v1/pipeline/{pipe_code}/execute", request=pipeline_request.model_dump_json())
return PipelineResponseFactory.make_from_api_response(response)
@@ -113,7 +115,7 @@ class PipelexClient(PipelexProtocol):
dynamic_output_concept_code: str | None = None,
) -> PipelineResponse:
if working_memory and inputs:
- msg = f"working_memory and inputs cannot be provided together to the API start_pipeline {pipe_code=}"
+ msg = f"'working_memory' and 'inputs' cannot be provided together to the API start_pipeline {pipe_code=}."
raise ValueError(msg)
if inputs is not None:
diff --git a/pipelex/client/pipeline_request_factory.py b/pipelex/client/pipeline_request_factory.py
index dbd9683ef..e08d6dc35 100644
--- a/pipelex/client/pipeline_request_factory.py
+++ b/pipelex/client/pipeline_request_factory.py
@@ -1,7 +1,7 @@
from typing import Any
from pipelex.client.api_serializer import ApiSerializer
-from pipelex.client.protocol import ImplicitMemory, PipelineRequest
+from pipelex.client.protocol import PipelineRequest
from pipelex.core.memory.working_memory import WorkingMemory
from pipelex.pipe_run.pipe_run_params import PipeOutputMultiplicity
@@ -29,7 +29,7 @@ class PipelineRequestFactory:
"""
return PipelineRequest(
- inputs=ImplicitMemory(ApiSerializer.serialize_working_memory_for_api(working_memory=working_memory)),
+ inputs=ApiSerializer.serialize_working_memory_for_api(working_memory=working_memory),
output_name=output_name,
output_multiplicity=output_multiplicity,
dynamic_output_concept_code=dynamic_output_concept_code,
diff --git a/pipelex/client/pipeline_response_factory.py b/pipelex/client/pipeline_response_factory.py
index a4872e1a8..323147a64 100644
--- a/pipelex/client/pipeline_response_factory.py
+++ b/pipelex/client/pipeline_response_factory.py
@@ -1,22 +1,48 @@
from typing import Any
-from pipelex.client.api_serializer import ApiSerializer
-from pipelex.client.protocol import PipelineResponse, PipelineState
-from pipelex.core.memory.working_memory import MAIN_STUFF_NAME
+from pipelex.client.protocol import PipelineResponse, PipelineState, SerializedPipeOutput, SerializedWorkingMemory
+from pipelex.core.memory.working_memory import MAIN_STUFF_NAME, WorkingMemory
from pipelex.core.pipes.pipe_output import PipeOutput
+from pipelex.core.stuffs.stuff import DictStuff
class PipelineResponseFactory:
"""Factory class for creating PipelineResponse objects from PipeOutput."""
+ @staticmethod
+ def _serialize_working_memory_with_dict_stuffs(working_memory: WorkingMemory) -> SerializedWorkingMemory:
+ """Convert WorkingMemory to dict with DictStuff objects (content as dict).
+
+ Keeps the WorkingMemory structure but converts each Stuff.content to dict.
+
+ Args:
+ working_memory: The WorkingMemory to serialize
+
+ Returns:
+ Dict with root containing DictStuff objects (serialized) and aliases
+ """
+ dict_stuffs_root: dict[str, DictStuff] = {}
+
+ # Convert each Stuff → DictStuff by dumping only the content
+ for stuff_name, stuff in working_memory.root.items():
+ dict_stuff = DictStuff(
+ stuff_code=stuff.stuff_code,
+ stuff_name=stuff.stuff_name,
+ concept=stuff.concept,
+ content=stuff.content.model_dump(serialize_as_any=True),
+ )
+ dict_stuffs_root[stuff_name] = dict_stuff
+
+ return SerializedWorkingMemory(root=dict_stuffs_root, aliases=working_memory.aliases)
+
@staticmethod
def make_from_pipe_output(
pipe_output: PipeOutput,
+ status: str,
pipeline_run_id: str = "",
created_at: str = "",
pipeline_state: PipelineState = PipelineState.COMPLETED,
finished_at: str | None = None,
- status: str | None = "success",
message: str | None = None,
error: str | None = None,
) -> PipelineResponse:
@@ -36,14 +62,15 @@ class PipelineResponseFactory:
PipelineResponse with the pipe output serialized to reduced format
"""
- compact_output = ApiSerializer.serialize_pipe_output_for_api(pipe_output=pipe_output)
-
return PipelineResponse(
pipeline_run_id=pipeline_run_id,
created_at=created_at,
pipeline_state=pipeline_state,
finished_at=finished_at,
- pipe_output=compact_output,
+ pipe_output=SerializedPipeOutput(
+ working_memory=PipelineResponseFactory._serialize_working_memory_with_dict_stuffs(pipe_output.working_memory),
+ pipeline_run_id=pipe_output.pipeline_run_id,
+ ),
main_stuff_name=pipe_output.working_memory.aliases.get(MAIN_STUFF_NAME, MAIN_STUFF_NAME),
status=status,
message=message,
diff --git a/pipelex/client/protocol.py b/pipelex/client/protocol.py
index 328729faa..783abf819 100644
--- a/pipelex/client/protocol.py
+++ b/pipelex/client/protocol.py
@@ -2,10 +2,11 @@ from abc import abstractmethod
from typing import Any, Protocol, Sequence
from pydantic import BaseModel
-from typing_extensions import runtime_checkable
+from pydantic.functional_validators import SkipValidation
+from typing_extensions import Annotated, runtime_checkable
from pipelex.core.memory.working_memory import WorkingMemory
-from pipelex.core.pipes.pipe_output import PipeOutput
+from pipelex.core.stuffs.stuff import DictStuff
from pipelex.core.stuffs.stuff_content import StuffContent
from pipelex.pipe_run.pipe_run_params import PipeOutputMultiplicity
from pipelex.types import StrEnum
@@ -31,8 +32,18 @@ StuffContentOrData = (
| Sequence[StuffContent] # Case 1.4 (covariant - accepts list[TextContent], etc.)
| DictStuffContent # Case 2.1, 2.2, 2.3, 2.4, 2.5, 2.6
)
-DictMemory = dict[str, DictStuffContent] # Special case of ImplicitMemory (Case 2.1, 2.2, 2.3, 2.4, 2.5, 2.6)
-ImplicitMemory = dict[str, StuffContentOrData]
+DictMemory = dict[str, DictStuffContent] # Serialized dict format (no StuffContent objects)
+ImplicitMemory = dict[str, StuffContentOrData] # Can include both dict and StuffContent
+
+
+class SerializedWorkingMemory(BaseModel):
+ root: dict[str, DictStuff]
+ aliases: dict[str, str]
+
+
+class SerializedPipeOutput(BaseModel):
+ working_memory: SerializedWorkingMemory
+ pipeline_run_id: str
class PipelineState(StrEnum):
@@ -50,13 +61,13 @@ class ApiResponse(BaseModel):
"""Base response class for Pipelex API calls.
Attributes:
- status (str | None): Status of the API call ("success", "error", etc.)
+ status (str): Application-level status ("success", "error")
message (str | None): Optional message providing additional information
error (str | None): Optional error message when status is not "success"
"""
- status: str | None = None
+ status: str = "success"
message: str | None = None
error: str | None = None
@@ -65,14 +76,15 @@ class PipelineRequest(BaseModel):
"""Request for executing a pipeline.
Attributes:
- inputs (ImplicitMemory | None): Inputs in the format of WorkingMemory.to_implicit_memory()
+ inputs (ImplicitMemory | None): Inputs in ImplicitMemory format - Pydantic validation is skipped
+ to preserve the flexible format (dicts, strings, StuffContent objects, etc.)
output_name (str | None): Name of the output slot to write to
output_multiplicity (PipeOutputMultiplicity | None): Output multiplicity setting
dynamic_output_concept_code (str | None): Override for the dynamic output concept code
"""
- inputs: ImplicitMemory | None = None
+ inputs: Annotated[ImplicitMemory | None, SkipValidation] = None
output_name: str | None = None
output_multiplicity: PipeOutputMultiplicity | None = None
dynamic_output_concept_code: str | None = None
@@ -82,18 +94,21 @@ class PipelineResponse(ApiResponse):
"""Response for pipeline execution requests.
Attributes:
+ pipeline_run_id (str): Unique identifier for the pipeline run
created_at (str): Timestamp when the pipeline was created
pipeline_state (PipelineState): Current state of the pipeline
finished_at (str | None): Timestamp when the pipeline finished, if completed
- pipeline_run_id (str): Unique identifier for the pipeline run
- pipe_output (DictMemory | None): Output data from the pipeline execution as raw dict, if available
- main_stuff_name (str): Name of the main stuff in the pipeline output
+ pipe_output (SerializedPipeOutput | None): Output data from the pipeline execution (working_memory dict + pipeline_run_id)
+ main_stuff_name (str | None): Name of the main stuff in the pipeline output
+
"""
+ pipeline_run_id: str
created_at: str
- finished_at: str | None = None
pipeline_state: PipelineState
- pipe_output: PipeOutput | None = None
+ finished_at: str | None = None
+ pipe_output: SerializedPipeOutput | None = None
+ main_stuff_name: str | None = None
@runtime_checkable
diff --git a/pipelex/core/stuffs/stuff.py b/pipelex/core/stuffs/stuff.py
index 35a097fd5..4740c20fe 100644
--- a/pipelex/core/stuffs/stuff.py
+++ b/pipelex/core/stuffs/stuff.py
@@ -191,3 +191,18 @@ Forbidden fields are: 'stuff_name', 'content_class', 'concept_code', 'stuff_code
def as_mermaid(self) -> MermaidContent:
"""Get content as MermaidContent if applicable."""
return self.content_as(MermaidContent)
+
+
+class DictStuff(CustomBaseModel):
+ """Stuff with content as dict[str, Any] instead of StuffContent.
+
+ This is used for serialization where the content needs to be a plain dict.
+ Has the exact same structure as Stuff but with dict content.
+ """
+
+ model_config = ConfigDict(extra="ignore", strict=True)
+
+ stuff_code: str
+ stuff_name: str | None = None
+ concept: Concept
+ content: dict[str, Any]
diff --git a/pipelex/core/stuffs/stuff_content.py b/pipelex/core/stuffs/stuff_content.py
index b0a2fc8b7..8460c6271 100644
--- a/pipelex/core/stuffs/stuff_content.py
+++ b/pipelex/core/stuffs/stuff_content.py
@@ -1,4 +1,4 @@
-from abc import ABC, abstractmethod
+from abc import ABC
from typing import Any, TypeVar
from kajson import kajson
@@ -38,13 +38,13 @@ class StuffContent(ABC, CustomBaseModel):
def rendered_plain(self) -> str:
return self.rendered_markdown()
- @abstractmethod
def rendered_html(self) -> str:
- pass
+ """Default HTML rendering - subclasses can override for custom rendering."""
+ return f"<pre>{self.rendered_json()}</pre>"
- @abstractmethod
- def rendered_markdown(self, level: int = 1, is_pretty: bool = False) -> str:
- pass
+ def rendered_markdown(self, level: int = 1, is_pretty: bool = False) -> str: # noqa: ARG002
+ """Default Markdown rendering - subclasses can override for custom rendering."""
+ return f"```json\n{self.rendered_json()}\n```"
def render_spreadsheet(self) -> str:
return self.rendered_plain()
diff --git a/pipelex/pipeline/start.py b/pipelex/pipeline/start.py
index 862c97713..27fa0d1fa 100644
--- a/pipelex/pipeline/start.py
+++ b/pipelex/pipeline/start.py
@@ -20,7 +20,7 @@ async def start_pipeline(
output_multiplicity: PipeOutputMultiplicity | None = None,
dynamic_output_concept_code: str | None = None,
pipe_run_mode: PipeRunMode = PipeRunMode.LIVE,
-) -> asyncio.Task[PipeOutput]:
+) -> tuple[str, asyncio.Task[PipeOutput]]:
"""Start a pipeline in the background.
This function mirrors *execute_pipeline* but returns immediately with the
@@ -88,4 +88,4 @@ async def start_pipeline(
# Launch execution without awaiting the result.
task: asyncio.Task[PipeOutput] = asyncio.create_task(get_pipe_router().run(pipe_job))
- return task
+ return pipeline_run_id, task
diff --git a/tests/integration/pipelex/client/test_client.py b/tests/integration/pipelex/client/test_client.py
index e0d5fb205..7f4c08638 100644
--- a/tests/integration/pipelex/client/test_client.py
+++ b/tests/integration/pipelex/client/test_client.py
@@ -6,7 +6,6 @@ from pipelex.client.client import PipelexClient
from pipelex.client.protocol import PipelineState
from pipelex.core.concepts.concept_factory import ConceptFactory
from pipelex.core.concepts.concept_native import NativeConceptCode
-from pipelex.core.domains.domain import SpecialDomain
from pipelex.core.memory.working_memory_factory import WorkingMemoryFactory
from pipelex.core.stuffs.stuff import Stuff
from pipelex.core.stuffs.stuff_factory import StuffFactory
@@ -118,30 +117,16 @@ class TestPipelexApiClient:
assert pipeline_reponse.pipe_output is not None
working_memory = pipeline_reponse.pipe_output.working_memory
+ pretty_print(working_memory, title="WORKING MEMORY")
# Verify question structure
- assert working_memory["question"] == {
- "concept_code": "answer.Question",
- "content": {"text": "Aerodynamic features?"},
- }
+ assert working_memory.root["question"].content["text"] == "Aerodynamic features?"
# Verify main_stuff structure
- assert working_memory["main_stuff"] is not None
- assert working_memory["main_stuff"]["concept_code"] == "retrieve.RetrievedExcerpt"
- assert "content" in working_memory["main_stuff"]
- assert "items" in working_memory["main_stuff"]["content"]
- assert isinstance(working_memory["main_stuff"]["content"]["items"], list)
- assert len(working_memory["main_stuff"]["content"]["items"]) > 0
-
- # Verify each item has required fields
- for item in working_memory["main_stuff"]["content"]["items"]:
- assert "text" in item
- assert "justification" in item
- assert isinstance(item["text"], str)
- assert isinstance(item["justification"], str)
+ assert working_memory.root["main_stuff"] is not None
+ assert working_memory.root["main_stuff"].concept.code == "RetrievedExcerpt"
+ assert working_memory.root["main_stuff"].content is not None
+ assert len(working_memory.root["main_stuff"].content) > 0
# Verify text structure
- assert working_memory["text"]["concept_code"] == f"{SpecialDomain.NATIVE}.{NativeConceptCode.TEXT}"
- assert "content" in working_memory["text"]
- assert isinstance(working_memory["text"]["content"], str)
- assert "The Dawn of Ultra-Rapid Transit" in working_memory["text"]["content"]
+ assert "The Dawn of Ultra-Rapid Transit" in working_memory.root["text"].content["text"]
diff --git a/tests/unit/pipelex/client/test_api_serialization.py b/tests/unit/pipelex/client/test_api_serialization.py
index 154bb5c5f..bc3218a1c 100644
--- a/tests/unit/pipelex/client/test_api_serialization.py
+++ b/tests/unit/pipelex/client/test_api_serialization.py
@@ -2,7 +2,7 @@ import json
from datetime import datetime
from decimal import Decimal
from enum import Enum
-from typing import Any
+from typing import Any, cast
import pytest
from pydantic import BaseModel
@@ -143,7 +143,7 @@ class TestApiSerialization:
assert len(implicit_memory) == 1
assert "sample_text" in implicit_memory
- text_blueprint = implicit_memory["sample_text"]
+ text_blueprint = cast("dict[str, Any]", implicit_memory["sample_text"])
assert text_blueprint["concept_code"] == NativeConceptCode.TEXT
assert isinstance(text_blueprint["content"], str)
assert text_blueprint["content"] == "Sample text content"
@@ -154,7 +154,7 @@ class TestApiSerialization:
assert len(implicit_memory) == 1
assert "pi_value" in implicit_memory
- number_blueprint = implicit_memory["pi_value"]
+ number_blueprint = cast("dict[str, Any]", implicit_memory["pi_value"])
assert number_blueprint["concept_code"] == NativeConceptCode.NUMBER
assert isinstance(number_blueprint["content"], dict)
assert number_blueprint["content"]["number"] == 3.14159