friday-framework-core 0.1.0a0__tar.gz

friday_framework_core-0.1.0a0/.gitignore

@@ -0,0 +1,24 @@
+__pycache__/
+*.pyc
+.env
+.venv/
+.idea/
+.vscode/
+dist/
+build/
+*.egg-info/
+chroma_db/
+.friday/
+/vector/
+/exports/
+tests/integration/memory/vector/*/
+tests/integration/memory/vector/backups/*/
+tests/integration/memory/vector/reorganization_logs/*
+*.gpickle
+keys.txt
+experiments/*/config/runtime.local.yaml
+experiments/*/artifacts/*
+!experiments/*/artifacts/.gitkeep
+scripts/source-friday-chat-example-env.sh
+scripts/pypi.sh
+/docs/reference/PyPI-Recovery-Codes-cichuck-2026-07-20T15_36_49.709334.txt

friday_framework_core-0.1.0a0/PKG-INFO

@@ -0,0 +1,48 @@
+Metadata-Version: 2.4
+Name: friday-framework-core
+Version: 0.1.0a0
+Summary: Foundation interfaces and utilities for Friday
+Project-URL: Homepage, https://github.com/CIChuck/agent-framework
+Project-URL: Repository, https://github.com/CIChuck/agent-framework
+Project-URL: Issues, https://github.com/CIChuck/agent-framework/issues
+Project-URL: Documentation, https://github.com/CIChuck/agent-framework/tree/main/docs
+Project-URL: Source, https://github.com/CIChuck/agent-framework/tree/main/packages/friday-core
+Author: Friday Team
+License-Expression: MIT
+Requires-Python: >=3.10
+Requires-Dist: friday-framework-telemetry==0.1.0a0
+Requires-Dist: pydantic-settings>=2.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: structlog>=24.0.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Provides-Extra: telemetry
+Requires-Dist: opentelemetry-api>=1.20.0; extra == 'telemetry'
+Requires-Dist: opentelemetry-exporter-otlp>=1.20.0; extra == 'telemetry'
+Requires-Dist: opentelemetry-sdk>=1.20.0; extra == 'telemetry'
+Description-Content-Type: text/markdown
+
+# Friday Framework Core
+
+Foundation interfaces and utilities for the Friday Framework.
+
+This package provides shared protocols, configuration primitives, structured
+logging helpers, exceptions, and security-oriented types used across Friday
+packages.
+
+## Install
+
+```bash
+pip install friday-framework-core
+```
+
+## Import Package
+
+```python
+import friday_core
+```
+
+## License
+
+MIT

friday_framework_core-0.1.0a0/README.md

@@ -0,0 +1,23 @@
+# Friday Framework Core
+
+Foundation interfaces and utilities for the Friday Framework.
+
+This package provides shared protocols, configuration primitives, structured
+logging helpers, exceptions, and security-oriented types used across Friday
+packages.
+
+## Install
+
+```bash
+pip install friday-framework-core
+```
+
+## Import Package
+
+```python
+import friday_core
+```
+
+## License
+
+MIT

friday_framework_core-0.1.0a0/examples/01_introductory.py

@@ -0,0 +1,86 @@
+"""
+Introductory Example: Basic Structured Logging
+
+This example demonstrates:
+- Creating loggers with get_logger()
+- Logging at different levels (debug, info, warning, error)
+- Adding structured context to log messages
+- Switching between development and production output formats
+
+Run with: uv run python packages/friday-core/examples/01_introductory.py
+"""
+
+from friday_core import get_logger
+
+
+def main():
+    # Create a logger for this module
+    # Development mode provides colored, human-readable output
+    logger = get_logger("my_app", environment="development")
+
+    print("=== Development Mode (Colored Console Output) ===\n")
+
+    # Basic logging at different levels
+    logger.debug("This is a debug message")
+    logger.info("Application started")
+    logger.warning("This is a warning")
+    logger.error("Something went wrong")
+
+    print("\n=== Structured Context Logging ===\n")
+
+    # Add structured context to log messages
+    # These key-value pairs are attached to the log entry
+    logger.info("User logged in", user_id="user_123", ip_address="192.168.1.1")
+
+    logger.info(
+        "Processing request",
+        request_id="req_abc",
+        method="POST",
+        path="/api/recall",
+    )
+
+    logger.warning(
+        "Slow response detected", latency_ms=1500, threshold_ms=1000, endpoint="/search"
+    )
+
+    logger.error(
+        "Database connection failed",
+        error_code="DB_001",
+        retry_count=3,
+        database="postgres",
+    )
+
+    print("\n=== Production Mode (JSON Output) ===\n")
+
+    # Production mode outputs JSON for machine parsing
+    prod_logger = get_logger("my_app_prod", environment="production")
+
+    prod_logger.info(
+        "Request completed",
+        request_id="req_xyz",
+        status_code=200,
+        duration_ms=45,
+    )
+
+    prod_logger.error(
+        "API rate limit exceeded",
+        provider="openai",
+        requests_remaining=0,
+        reset_at="2024-01-15T10:30:00Z",
+    )
+
+    print("\n=== Complex Nested Context ===\n")
+
+    # Loggers handle complex nested data structures
+    dev_logger = get_logger("complex_app", environment="development")
+
+    dev_logger.info(
+        "Memory operation completed",
+        user={"id": "user_456", "role": "admin"},
+        operation={"type": "recall", "budget_tokens": 4000},
+        metrics={"latency_ms": 120, "tokens_used": 350, "cache_hit": True},
+    )
+
+
+if __name__ == "__main__":
+    main()

friday_framework_core-0.1.0a0/examples/02_intermediate.py

@@ -0,0 +1,156 @@
+"""
+Intermediate Example: Telemetry with Events and Spans
+
+This example demonstrates:
+- TelemetryInterface protocol for instrumentation
+- DebugTelemetryRecorder for white-box testing
+- Capturing discrete events with data
+- Tracking operation timing with spans
+- Parent-child span relationships
+- Using helper methods for test assertions
+
+Run with: uv run python packages/friday-core/examples/02_intermediate.py
+"""
+
+import time
+
+from friday_core import (
+    DebugTelemetryRecorder,
+    TelemetryInterface,
+)
+
+
+def main():
+    # DebugTelemetryRecorder is an in-memory implementation
+    # Perfect for testing and development
+    recorder = DebugTelemetryRecorder()
+
+    print("=== Capturing Events ===\n")
+
+    # Events are discrete occurrences with associated data
+    recorder.capture_event("user_login", {"user_id": "user_123", "method": "oauth"})
+
+    recorder.capture_event(
+        "memory_recall",
+        {
+            "query": "What did we discuss about the API?",
+            "results_count": 5,
+            "latency_ms": 45,
+        },
+    )
+
+    recorder.capture_event(
+        "tool_execution",
+        {"tool_name": "web_search", "status": "success", "tokens_used": 150},
+    )
+
+    # View all captured events
+    print(f"Captured {len(recorder.events)} events:")
+    for event in recorder.events:
+        print(f"  - {event.name}: {event.data}")
+
+    print("\n=== Working with Spans ===\n")
+
+    # Spans track the duration of operations
+    # start_span returns a span_id for later reference
+    span_id = recorder.start_span("database_query")
+
+    # Simulate some work
+    time.sleep(0.05)  # 50ms
+
+    # End the span with optional result data
+    recorder.end_span(span_id, {"rows_returned": 42, "cache_hit": False})
+
+    # Retrieve and inspect the span
+    span = recorder.get_span(span_id)
+    print(f"Span '{span.name}':")
+    print(f"  Duration: {span.duration_ms:.2f}ms")
+    print(f"  Data: {span.data}")
+
+    print("\n=== Parent-Child Span Relationships ===\n")
+
+    # Spans can have parent-child relationships for tracing
+    parent_id = recorder.start_span("handle_request")
+
+    # Child spans reference their parent
+    child1_id = recorder.start_span("validate_input", parent_id=parent_id)
+    time.sleep(0.01)
+    recorder.end_span(child1_id, {"valid": True})
+
+    child2_id = recorder.start_span("process_query", parent_id=parent_id)
+    time.sleep(0.02)
+    recorder.end_span(child2_id, {"tokens": 500})
+
+    child3_id = recorder.start_span("format_response", parent_id=parent_id)
+    time.sleep(0.01)
+    recorder.end_span(child3_id, {"format": "json"})
+
+    recorder.end_span(parent_id, {"status": 200})
+
+    # Display the span hierarchy
+    parent_span = recorder.get_span(parent_id)
+    print(f"Parent: {parent_span.name} ({parent_span.duration_ms:.2f}ms)")
+
+    for span_id, span in recorder.spans.items():  # noqa: B007
+        if span.parent_id == parent_id:
+            print(f"  Child: {span.name} ({span.duration_ms:.2f}ms)")
+
+    print("\n=== Helper Methods for Testing ===\n")
+
+    # get_event retrieves the first event with a given name
+    login_data = recorder.get_event("user_login")
+    print(f"User login data: {login_data}")
+
+    # get_all_events retrieves all events with a given name
+    recorder.capture_event("api_call", {"endpoint": "/v1/chat"})
+    recorder.capture_event("api_call", {"endpoint": "/v1/embeddings"})
+    all_api_calls = recorder.get_all_events("api_call")
+    print(f"All API calls ({len(all_api_calls)}): {all_api_calls}")
+
+    # get_span_by_name finds a span by its name
+    query_span = recorder.get_span_by_name("database_query")
+    print(f"Database query span duration: {query_span.duration_ms:.2f}ms")
+
+    # event_names lists all event names in order
+    print(f"Event names: {recorder.event_names}")
+
+    print("\n=== Using Telemetry for Test Assertions ===\n")
+
+    # Clear previous data for a fresh test
+    recorder.clear()
+
+    # Simulate a component that uses telemetry
+    def memory_search(query: str, telemetry: TelemetryInterface):
+        span_id = telemetry.start_span("memory_search")
+
+        telemetry.capture_event("search_started", {"query": query})
+
+        # Simulate search
+        time.sleep(0.02)
+        results = ["result1", "result2", "result3"]
+
+        telemetry.capture_event(
+            "search_completed", {"query": query, "count": len(results)}
+        )
+
+        telemetry.end_span(span_id, {"results": len(results)})
+        return results
+
+    # Execute the function
+    memory_search("API design patterns", recorder)
+
+    # Now assert on the telemetry data
+    assert recorder.get_event("search_started")["query"] == "API design patterns"
+    assert recorder.get_event("search_completed")["count"] == 3
+
+    search_span = recorder.get_span_by_name("memory_search")
+    assert search_span is not None
+    assert search_span.duration_ms >= 20
+    assert search_span.data["results"] == 3
+
+    print("All assertions passed!")
+    print(f"Search completed in {search_span.duration_ms:.2f}ms")
+
+
+if __name__ == "__main__":
+    main()

friday_framework_core-0.1.0a0/examples/03_advanced.py

@@ -0,0 +1,327 @@
+"""
+Advanced Example: Production Patterns with Logging and Telemetry
+
+This example demonstrates:
+- Dependency injection pattern for observability
+- Combined logging and telemetry in components
+- Configuration-driven environment switching
+- Optional telemetry (graceful degradation)
+- Simulating a realistic service with full instrumentation
+- Test harness pattern for white-box testing
+
+Run with: uv run python packages/friday-core/examples/03_advanced.py
+"""
+
+import asyncio
+import time
+from dataclasses import dataclass
+from typing import Any
+
+from friday_core import (
+    DebugTelemetryRecorder,
+    FridayBaseSettings,
+    LoggerProtocol,
+    TelemetryInterface,
+    get_logger,
+)
+
+
+@dataclass
+class RetrievalResult:
+    """Result from memory retrieval."""
+
+    query: str
+    documents: list[dict[str, Any]]
+    latency_ms: float
+    source: str
+
+
+class MemoryService:
+    """
+    A service demonstrating production-ready observability patterns.
+
+    Key patterns:
+    - Telemetry is optional (works without it)
+    - Logger is injected for testability
+    - Both are used together for comprehensive observability
+    """
+
+    def __init__(
+        self,
+        logger: LoggerProtocol,
+        telemetry: TelemetryInterface | None = None,
+    ):
+        self._logger = logger
+        self._telemetry = telemetry
+
+    async def retrieve(self, query: str, limit: int = 5) -> RetrievalResult:
+        """
+        Retrieve relevant documents from memory.
+
+        Demonstrates:
+        - Span wrapping for timing
+        - Structured logging with context
+        - Event capture for discrete operations
+        """
+        span_id = None
+        if self._telemetry:
+            span_id = self._telemetry.start_span("memory_retrieve")
+            self._telemetry.capture_event(
+                "retrieve_started", {"query": query, "limit": limit}
+            )
+
+        self._logger.info("Starting memory retrieval", query=query, limit=limit)
+
+        start_time = time.perf_counter()
+
+        try:
+            # Simulate vector search
+            await self._vector_search(query)
+
+            # Simulate graph traversal
+            await self._graph_lookup(query)
+
+            # Simulate result ranking
+            documents = await self._rank_results(query, limit)
+
+            latency_ms = (time.perf_counter() - start_time) * 1000
+
+            self._logger.info(
+                "Memory retrieval completed",
+                query=query,
+                results_count=len(documents),
+                latency_ms=round(latency_ms, 2),
+            )
+
+            if self._telemetry:
+                self._telemetry.capture_event(
+                    "retrieve_completed",
+                    {
+                        "query": query,
+                        "results_count": len(documents),
+                        "latency_ms": latency_ms,
+                    },
+                )
+                if span_id:
+                    self._telemetry.end_span(
+                        span_id,
+                        {"results": len(documents), "status": "success"},
+                    )
+
+            return RetrievalResult(
+                query=query,
+                documents=documents,
+                latency_ms=latency_ms,
+                source="combined",
+            )
+
+        except Exception as e:
+            self._logger.error(
+                "Memory retrieval failed",
+                query=query,
+                error=str(e),
+            )
+
+            if self._telemetry:
+                self._telemetry.capture_event(
+                    "retrieve_failed", {"query": query, "error": str(e)}
+                )
+                if span_id:
+                    self._telemetry.end_span(
+                        span_id, {"status": "error", "error": str(e)}
+                    )
+
+            raise
+
+    async def _vector_search(self, query: str) -> list[dict]:
+        """Simulate vector similarity search."""
+        span_id = None
+        if self._telemetry:
+            span_id = self._telemetry.start_span("vector_search")
+
+        self._logger.debug("Executing vector search", query=query[:50])
+
+        # Simulate latency
+        await asyncio.sleep(0.02)
+
+        if self._telemetry and span_id:
+            self._telemetry.end_span(span_id, {"matches": 10})
+
+        return [{"id": f"vec_{i}", "score": 0.9 - i * 0.1} for i in range(10)]
+
+    async def _graph_lookup(self, query: str) -> list[dict]:
+        """Simulate knowledge graph traversal."""
+        span_id = None
+        if self._telemetry:
+            span_id = self._telemetry.start_span("graph_lookup")
+
+        self._logger.debug("Executing graph lookup", query=query[:50])
+
+        # Simulate latency
+        await asyncio.sleep(0.015)
+
+        if self._telemetry and span_id:
+            self._telemetry.end_span(span_id, {"nodes_visited": 25})
+
+        return [{"id": f"node_{i}", "relevance": 0.85 - i * 0.05} for i in range(5)]
+
+    async def _rank_results(self, query: str, limit: int) -> list[dict]:
+        """Simulate result ranking and deduplication."""
+        span_id = None
+        if self._telemetry:
+            span_id = self._telemetry.start_span("rank_results")
+
+        self._logger.debug("Ranking results", limit=limit)
+
+        # Simulate ranking computation
+        await asyncio.sleep(0.01)
+
+        results = [
+            {
+                "id": f"doc_{i}",
+                "content": f"Document {i} about {query}",
+                "score": 0.95 - i * 0.05,
+            }
+            for i in range(limit)
+        ]
+
+        if self._telemetry and span_id:
+            self._telemetry.end_span(span_id, {"final_count": len(results)})
+
+        return results
+
+
+class ApplicationContext:
+    """
+    Application context that wires up dependencies.
+
+    Demonstrates configuration-driven setup based on environment.
+    """
+
+    def __init__(self, settings: FridayBaseSettings):
+        self.settings = settings
+
+        # Configure logger based on environment
+        self.logger = get_logger("friday_app", environment=settings.APP_ENV)
+
+        # Telemetry is only enabled in development/testing
+        self.telemetry: TelemetryInterface | None = None
+        if settings.APP_ENV in ("development", "testing"):
+            self.telemetry = DebugTelemetryRecorder()
+            self.logger.info("Telemetry enabled", mode="debug_recorder")
+
+    def create_memory_service(self) -> MemoryService:
+        """Factory method for creating the memory service."""
+        return MemoryService(
+            logger=self.logger,
+            telemetry=self.telemetry,
+        )
+
+
+async def run_production_simulation():
+    """Simulate production usage with logging only."""
+    print("=== Production Mode (Logging Only) ===\n")
+
+    # Production settings - telemetry disabled
+    settings = FridayBaseSettings(APP_ENV="production")
+    ctx = ApplicationContext(settings)
+
+    service = ctx.create_memory_service()
+
+    result = await service.retrieve("What are the best practices for API design?")
+    print(
+        f"\nRetrieved {len(result.documents)} documents in {result.latency_ms:.2f}ms\n"
+    )
+
+
+async def run_development_simulation():
+    """Simulate development usage with full observability."""
+    print("=== Development Mode (Logging + Telemetry) ===\n")
+
+    settings = FridayBaseSettings(APP_ENV="development")
+    ctx = ApplicationContext(settings)
+
+    service = ctx.create_memory_service()
+
+    result = await service.retrieve("How do I implement authentication?", limit=3)
+    print(f"\nRetrieved {len(result.documents)} documents in {result.latency_ms:.2f}ms")
+
+    # Access telemetry data for debugging
+    if ctx.telemetry:
+        recorder = ctx.telemetry
+        print("\n--- Telemetry Summary ---")
+        print(f"Events captured: {len(recorder.events)}")
+        print(f"Event types: {set(recorder.event_names)}")
+        print(f"Spans recorded: {len(recorder.spans)}")
+
+        # Show span hierarchy
+        print("\nSpan timings:")
+        for _span_id, span in recorder.spans.items():
+            if span.duration_ms is not None:
+                indent = "  " if span.parent_id else ""
+                print(f"{indent}{span.name}: {span.duration_ms:.2f}ms")
+
+
+async def run_test_harness():
+    """Demonstrate white-box testing with telemetry assertions."""
+    print("\n=== Test Harness Pattern ===\n")
+
+    # Create a test-specific recorder
+    test_recorder = DebugTelemetryRecorder()
+    test_logger = get_logger("test", environment="development")
+
+    # Inject test dependencies
+    service = MemoryService(logger=test_logger, telemetry=test_recorder)
+
+    # Execute the operation
+    await service.retrieve("test query", limit=5)
+
+    # White-box assertions on internal behavior
+    print("Running assertions on telemetry data...")
+
+    # Assert events were captured
+    started_event = test_recorder.get_event("retrieve_started")
+    assert started_event is not None, "Should capture retrieve_started event"
+    assert started_event["query"] == "test query"
+    assert started_event["limit"] == 5
+
+    completed_event = test_recorder.get_event("retrieve_completed")
+    assert completed_event is not None, "Should capture retrieve_completed event"
+    assert completed_event["results_count"] == 5
+
+    # Assert spans were recorded
+    main_span = test_recorder.get_span_by_name("memory_retrieve")
+    assert main_span is not None, "Should record main span"
+    assert main_span.data["status"] == "success"
+
+    vector_span = test_recorder.get_span_by_name("vector_search")
+    assert vector_span is not None, "Should record vector_search span"
+
+    graph_span = test_recorder.get_span_by_name("graph_lookup")
+    assert graph_span is not None, "Should record graph_lookup span"
+
+    rank_span = test_recorder.get_span_by_name("rank_results")
+    assert rank_span is not None, "Should record rank_results span"
+
+    # Assert timing relationships
+    assert main_span.duration_ms >= (
+        vector_span.duration_ms + graph_span.duration_ms + rank_span.duration_ms
+    ), "Parent span should be >= sum of child spans"
+
+    print("All assertions passed!")
+    print(f"\nTotal operation time: {main_span.duration_ms:.2f}ms")
+    print(f"  - Vector search: {vector_span.duration_ms:.2f}ms")
+    print(f"  - Graph lookup: {graph_span.duration_ms:.2f}ms")
+    print(f"  - Ranking: {rank_span.duration_ms:.2f}ms")
+
+
+async def main():
+    await run_production_simulation()
+    print("\n" + "=" * 60 + "\n")
+    await run_development_simulation()
+    print("\n" + "=" * 60 + "\n")
+    await run_test_harness()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())