feat: Add create_span function for observability and examples parameter to module decorator.

Author: tercel

src/apcore/__init__.py

@@ -129,6 +129,7 @@
     SpanExporter,
     StdoutExporter,
     TracingMiddleware,
+    create_span,
 )
 
 # Trace Context
@@ -258,6 +259,7 @@
     "InMemoryExporter",
     "OTLPExporter",
     "SpanExporter",
+    "create_span",
     # Trace Context
     "TraceContext",
     "TraceParent",

src/apcore/acl.py

@@ -85,6 +85,7 @@ def __init__(
         self._audit_logger: Callable[[AuditEntry], None] | None = audit_logger
         self._logger: logging.Logger = logging.getLogger(__name__)
         self._lock = threading.Lock()
+        self.debug: bool = False
 
     @classmethod
     def load(cls, yaml_path: str) -> ACL:

src/apcore/decorator.py

@@ -13,6 +13,7 @@
 from apcore._docstrings import parse_docstring
 from apcore.context import Context
 from apcore.errors import FuncMissingReturnTypeError, FuncMissingTypeHintError
+from apcore.module import ModuleExample
 
 
 def _has_explicit_field_description(annotation: Any) -> bool:
@@ -175,6 +176,7 @@ def __init__(
         version: str = "1.0.0",
         annotations: dict[str, Any] | None = None,
         metadata: dict[str, Any] | None = None,
+        examples: list[ModuleExample] | None = None,
         input_schema: type[BaseModel] | None = None,
         output_schema: type[BaseModel] | None = None,
     ) -> None:
@@ -202,6 +204,7 @@ def __init__(
         self.version = version
         self.annotations = annotations
         self.metadata = metadata
+        self.examples = examples
 
         # Create execute closures — two separate defs required so that
         # inspect.iscoroutinefunction returns the correct value.
@@ -249,6 +252,7 @@ def module(
     tags: list[str] | None = None,
     version: str = "1.0.0",
     metadata: dict[str, Any] | None = None,
+    examples: list[ModuleExample] | None = None,
     registry: Any = None,
 ) -> Any:
     """Wrap a Python function as an apcore module.
@@ -267,6 +271,7 @@ def _wrap(func: Callable, *, return_module: bool = False) -> Any:
             tags=tags,
             version=version,
             metadata=metadata,
+            examples=examples,
         )
         if registry is not None:
             registry.register(fm.module_id, fm)

src/apcore/observability/__init__.py

@@ -23,6 +23,7 @@
     SpanExporter,
     StdoutExporter,
     TracingMiddleware,
+    create_span,
 )
 
 __all__ = [
@@ -36,4 +37,5 @@
     "SpanExporter",
     "StdoutExporter",
     "TracingMiddleware",
+    "create_span",
 ]

src/apcore/observability/context_logger.py

@@ -28,14 +28,16 @@ class ContextLogger:
 
     def __init__(
         self,
-        name: str,
+        name: str = "apcore",
+        *,
+        format: str | None = None,
         output_format: str = "json",
         level: str = "info",
         redact_sensitive: bool = True,
         output: Any = None,
     ) -> None:
         self._name = name
-        self._output_format = output_format
+        self._output_format = format if format is not None else output_format
         self._level = level
         self._level_value = _LEVELS.get(level, 20)
         self._redact_sensitive = redact_sensitive

src/apcore/observability/tracing.py

@@ -32,6 +32,26 @@ class Span:
     events: list[dict[str, Any]] = field(default_factory=list)
 
 
+def create_span(
+    *,
+    trace_id: str,
+    name: str,
+    start_time: float,
+    span_id: str | None = None,
+    parent_span_id: str | None = None,
+    attributes: dict[str, Any] | None = None,
+) -> Span:
+    """Factory function to create a Span with sensible defaults."""
+    return Span(
+        trace_id=trace_id,
+        name=name,
+        start_time=start_time,
+        span_id=span_id if span_id is not None else os.urandom(8).hex(),
+        parent_span_id=parent_span_id,
+        attributes=attributes if attributes is not None else {},
+    )
+
+
 @runtime_checkable
 class SpanExporter(Protocol):
     """Protocol for span export destinations."""
@@ -293,6 +313,7 @@ def on_error(self, module_id: str, inputs: dict[str, Any], error: Exception, con
 
 __all__ = [
     "Span",
+    "create_span",
     "SpanExporter",
     "StdoutExporter",
     "InMemoryExporter",

src/apcore/schema/exporter.py

@@ -52,7 +52,7 @@ def export_mcp(
                 "destructiveHint": annotations.destructive if annotations else False,
                 "idempotentHint": annotations.idempotent if annotations else False,
                 "openWorldHint": annotations.open_world if annotations else True,
-                "streaming": getattr(annotations, "streaming", False) if annotations else False,
+                "streaming": annotations.streaming if annotations else False,
             },
         }
 

tests/observability/test_observability_package.py

@@ -80,6 +80,7 @@ def test_all_contains_all_public_names(self):
             "SpanExporter",
             "StdoutExporter",
             "TracingMiddleware",
+            "create_span",
         }
         assert set(obs.__all__) == expected
 

tests/test_public_api.py

@@ -440,6 +440,7 @@ class TestPublicAPIAll:
         "SpanExporter",
         "StdoutExporter",
         "InMemoryExporter",
+        "create_span",
         "OTLPExporter",
         # Trace Context
         "TraceContext",