prme 0.15.0__py3-none-any.whl

prme/__init__.py

@@ -0,0 +1,317 @@
+"""PRME - Portable Relational Memory Engine.
+
+A local-first, embeddable memory substrate for LLM-powered systems.
+Combines event sourcing, graph-based relational modeling, hybrid retrieval,
+and explicit or opportunistic memory reorganization.
+"""
+
+__version__ = "0.15.0"
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from prme.workspace import (
+        MemoryWorkspace,
+        NamespaceInfo,
+        NamespaceMemory,
+        WorkspaceError,
+    )
+    from prme.client import MemoryClient, config_from_directory, config_from_pack
+    from prme.ingestion.pipeline import IngestionPipeline
+    from prme.retrieval.models import RetrievalResponse
+    from prme.retrieval.pipeline import RetrievalPipeline
+
+from prme.config import PRMEConfig
+from prme.config_audit import (
+    HypothesisAudit as HypothesisAudit,
+    HypothesisSetting as HypothesisSetting,
+    audit_hypotheses as audit_hypotheses,
+)
+from prme.ingestion.errors import ExtractionError, MaterializationError
+from prme.models.aggregation import (
+    AssertionAggregation,
+    AssertionGroup,
+    AssertionQuery,
+    QuantityAggregation,
+    QuantityAggregationPlan,
+    QuantityAggregationQuery,
+    QuantityGroup,
+    QuantitySample,
+    PlannedQuantityAggregation,
+)
+from prme.models.temporal import (
+    AssertionState,
+    AssertionStateConflict,
+    AssertionStateEntry,
+    AssertionStateHistoricalCoverage,
+    AssertionStateQuery,
+    AssertionStateValue,
+)
+from prme.models.processing import (
+    FastIngestItem,
+    ProcessingResult,
+    ProcessingStatus,
+    StoreReceipt,
+)
+from prme.models.value_bindings import (
+    MemoryValueBinding,
+    RetrievedValueBinding,
+    ToolArgumentBindingUse,
+    ToolArgumentReplacement,
+    ToolArgumentResolution,
+)
+from prme.storage.fast_ingest import FastIngestConflict
+from prme.storage.alias_review import (
+    AliasProposalDecision,
+    AliasProposalInboxItem,
+    AliasProposalReviewConflict,
+    AliasProposalReviewRecord,
+    AliasProposalReviewResult,
+    AliasProposalStatus,
+    StaleAliasProposal,
+)
+from prme.integrations.product_candidates import (
+    PRODUCT_CANDIDATE_POLICY,
+    ProductAlignmentCandidate,
+    ProductCandidateEntity,
+    rank_product_alignment_candidates,
+)
+from prme.models.credit import ContextAblation, ContextPresenceCredit
+from prme.models.profile import (
+    StaleProfileError,
+    ProfileJobStatus,
+    ProfileProcessingResult,
+    ProfileCollectionResult,
+)
+from prme.models.relevance import (
+    AnswerCitationRecord,
+    AnswerCitationSubmission,
+    RelevanceRecord,
+    RelevanceSubmission,
+    RetrievalReceipt,
+)
+from prme.models.provenance import NodeProvenance, OperationAuditRecord
+from prme.models.learning import (
+    FullRetrievalEvaluation,
+    FullRetrievalEvaluationConfig,
+    FullRetrievalQueryResult,
+    FullRetrievalTrial,
+    LearningConfig,
+    LearningEvaluation,
+    RankingMultipliers,
+    RankingProfile,
+    RankingProfileApplication,
+    RankingProfileState,
+    RankingProfileStatus,
+)
+from prme.models.extraction import ExtractionRecord
+from prme.models.extraction_work import ExtractionStatus, ExtractionProcessingResult
+from prme.storage.engine import MemoryEngine
+from prme.storage.namespace_identity import NamespaceIdentityError
+from prme.storage.ranking_profiles import StaleRankingProfileError
+from prme.storage.embedding import (
+    CachedEmbeddingProvider,
+    EmbeddingProvider,
+    QueryEmbeddingProvider,
+)
+from prme.retrieval.credit import ablate_context, assess_context_presence
+from prme.retrieval.answerability import (
+    AnswerabilityAction,
+    AnswerabilityAssessment,
+    AnswerabilityConfig,
+    AnswerabilityError,
+    AnswerabilityEvaluator,
+    AnswerabilityRequirement,
+    AnswerabilityStatus,
+    AnswerabilityVerdict,
+    assess_answerability,
+)
+from prme.retrieval.claim_verification import (
+    ClaimEvidence,
+    ClaimVerification,
+    ClaimVerificationConfig,
+    ClaimVerificationDecisionBasis,
+    ClaimVerificationError,
+    ClaimVerificationLimitation,
+    ClaimVerificationStatus,
+    ClaimVerifier,
+    EvidenceGroupScore,
+    LocalizedEvidenceAssessment,
+)
+from prme.retrieval.full_learning import evaluate_full_retrieval
+from prme.retrieval.temporal_relation_models import TemporalRelationMetadata
+from prme.retrieval.temporal_relations import TemporalRelationConfig
+from prme.types import (
+    ConditionEvaluationMethod,
+    ConditionState,
+    DECAY_LAMBDAS,
+    DEFAULT_DECAY_PROFILE_MAPPING,
+    DecayProfile,
+    EdgeType,
+    EpistemicType,
+    LifecycleState,
+    NodeType,
+    RetrievalMode,
+    Scope,
+    SourceType,
+)
+
+
+def __getattr__(name: str):
+    """Lazy imports for heavy modules to avoid circular import chains."""
+    if name in {
+        "MemoryWorkspace",
+        "NamespaceInfo",
+        "NamespaceMemory",
+        "WorkspaceError",
+    }:
+        from prme import workspace
+
+        return getattr(workspace, name)
+    if name == "MemoryClient":
+        from prme.client import MemoryClient
+
+        return MemoryClient
+    if name == "config_from_directory":
+        from prme.client import config_from_directory
+
+        return config_from_directory
+    if name == "config_from_pack":
+        from prme.client import config_from_pack
+
+        return config_from_pack
+    if name == "IngestionPipeline":
+        from prme.ingestion.pipeline import IngestionPipeline
+
+        return IngestionPipeline
+    if name == "RetrievalResponse":
+        from prme.retrieval.models import RetrievalResponse
+
+        return RetrievalResponse
+    if name == "RetrievalPipeline":
+        from prme.retrieval.pipeline import RetrievalPipeline
+
+        return RetrievalPipeline
+    raise AttributeError(f"module 'prme' has no attribute {name!r}")
+
+
+__all__ = [
+    "AnswerCitationRecord",
+    "AnswerCitationSubmission",
+    "AliasProposalDecision",
+    "AliasProposalInboxItem",
+    "AliasProposalReviewConflict",
+    "AliasProposalReviewRecord",
+    "AliasProposalReviewResult",
+    "AliasProposalStatus",
+    "AnswerabilityAction",
+    "AnswerabilityAssessment",
+    "AnswerabilityConfig",
+    "AnswerabilityError",
+    "AnswerabilityEvaluator",
+    "AnswerabilityRequirement",
+    "AnswerabilityStatus",
+    "AnswerabilityVerdict",
+    "AssertionAggregation",
+    "AssertionGroup",
+    "AssertionQuery",
+    "AssertionState",
+    "AssertionStateConflict",
+    "AssertionStateEntry",
+    "AssertionStateHistoricalCoverage",
+    "AssertionStateQuery",
+    "AssertionStateValue",
+    "ClaimEvidence",
+    "ClaimVerification",
+    "ClaimVerificationConfig",
+    "ClaimVerificationDecisionBasis",
+    "ClaimVerificationError",
+    "ClaimVerificationLimitation",
+    "ClaimVerificationStatus",
+    "ClaimVerifier",
+    "LocalizedEvidenceAssessment",
+    "QuantityAggregation",
+    "QuantityAggregationPlan",
+    "QuantityAggregationQuery",
+    "QuantityGroup",
+    "QuantitySample",
+    "PlannedQuantityAggregation",
+    "ConditionEvaluationMethod",
+    "ConditionState",
+    "ContextAblation",
+    "ContextPresenceCredit",
+    "DECAY_LAMBDAS",
+    "DEFAULT_DECAY_PROFILE_MAPPING",
+    "DecayProfile",
+    "CachedEmbeddingProvider",
+    "EmbeddingProvider",
+    "QueryEmbeddingProvider",
+    "EdgeType",
+    "EpistemicType",
+    "EvidenceGroupScore",
+    "ExtractionError",
+    "ExtractionRecord",
+    "ExtractionStatus",
+    "ExtractionProcessingResult",
+    "FastIngestItem",
+    "FastIngestConflict",
+    "IngestionPipeline",
+    "LifecycleState",
+    "LearningConfig",
+    "LearningEvaluation",
+    "FullRetrievalEvaluation",
+    "FullRetrievalEvaluationConfig",
+    "FullRetrievalQueryResult",
+    "FullRetrievalTrial",
+    "MaterializationError",
+    "MemoryClient",
+    "MemoryEngine",
+    "MemoryValueBinding",
+    "MemoryWorkspace",
+    "NamespaceInfo",
+    "NamespaceMemory",
+    "NamespaceIdentityError",
+    "WorkspaceError",
+    "NodeType",
+    "NodeProvenance",
+    "OperationAuditRecord",
+    "PRMEConfig",
+    "ProcessingResult",
+    "ProcessingStatus",
+    "PRODUCT_CANDIDATE_POLICY",
+    "ProductAlignmentCandidate",
+    "ProductCandidateEntity",
+    "ProfileJobStatus",
+    "ProfileProcessingResult",
+    "ProfileCollectionResult",
+    "RetrievalPipeline",
+    "RetrievalResponse",
+    "RetrievalReceipt",
+    "RetrievedValueBinding",
+    "RetrievalMode",
+    "RankingMultipliers",
+    "RankingProfile",
+    "RankingProfileApplication",
+    "RankingProfileState",
+    "RankingProfileStatus",
+    "RelevanceSubmission",
+    "RelevanceRecord",
+    "Scope",
+    "SourceType",
+    "StaleProfileError",
+    "StaleAliasProposal",
+    "StaleRankingProfileError",
+    "StoreReceipt",
+    "TemporalRelationConfig",
+    "TemporalRelationMetadata",
+    "ToolArgumentBindingUse",
+    "ToolArgumentReplacement",
+    "ToolArgumentResolution",
+    "ablate_context",
+    "assess_context_presence",
+    "assess_answerability",
+    "evaluate_full_retrieval",
+    "rank_product_alignment_candidates",
+    "config_from_directory",
+    "config_from_pack",
+]

prme/_temporal.py

@@ -0,0 +1,9 @@
+"""Guard PRME's entries into dateparser's process-wide mutable parser state."""
+
+from threading import RLock
+
+# Older supported dateparser versions share settings and lazy locale caches.
+# Ingestion and retrieval can run on different MemoryClient/event-loop threads.
+# Keep every PRME parse/search call in the same critical section; an independent
+# lock per pipeline does not protect either shared settings or locale caches.
+DATEPARSER_LOCK = RLock()

prme/api/__init__.py

@@ -0,0 +1,20 @@
+"""PRME HTTP API layer (FastAPI).
+
+Provides REST endpoints for store, retrieve, organize, and lifecycle
+operations. The API is an optional dependency — install with:
+
+    pip install prme[api]
+
+Usage:
+
+    from prme.api.app import create_app
+    app = create_app()
+
+Or run directly:
+
+    python -m prme.api
+"""
+
+from prme.api.app import create_app
+
+__all__ = ["create_app"]

prme/api/__main__.py

@@ -0,0 +1,64 @@
+"""Entry point for ``python -m prme.api``.
+
+Starts the PRME HTTP API server with default settings.
+Configuration is loaded from environment variables (PRME_ prefix).
+"""
+
+from __future__ import annotations
+
+import argparse
+
+
+def main() -> None:
+    """Parse CLI arguments and start the server."""
+    parser = argparse.ArgumentParser(
+        description="PRME HTTP API Server",
+        prog="python -m prme.api",
+        # The unauthenticated override must be spelled out in full.
+        allow_abbrev=False,
+    )
+    parser.add_argument(
+        "--host",
+        default="127.0.0.1",
+        help=(
+            "Bind address (default: 127.0.0.1). A non-loopback address such "
+            "as 0.0.0.0 requires API credentials (PRME_API_USER_KEYS or "
+            "PRME_API_API_KEY); without them startup is refused. Only literal "
+            "loopback addresses and localhost count as loopback."
+        ),
+    )
+    parser.add_argument(
+        "--port", type=int, default=8000, help="Port (default: 8000)"
+    )
+    parser.add_argument(
+        "--log-level", default="info", help="Log level (default: info)"
+    )
+    parser.add_argument(
+        "--allow-unauthenticated-external-bind",
+        action="store_true",
+        help=(
+            "Start on a non-loopback --host with no API credentials. Only for "
+            "a server reachable solely through an authenticating reverse "
+            "proxy: the API itself accepts every request, and every caller "
+            "has operator access to all users' memories."
+        ),
+    )
+    args = parser.parse_args()
+
+    from prme.api.server import UnauthenticatedBindError, run_server
+
+    try:
+        run_server(
+            host=args.host,
+            port=args.port,
+            log_level=args.log_level,
+            allow_unauthenticated_external_bind=(
+                args.allow_unauthenticated_external_bind
+            ),
+        )
+    except UnauthenticatedBindError as exc:
+        parser.error(str(exc))
+
+
+if __name__ == "__main__":
+    main()

prme/api/app.py

@@ -0,0 +1,106 @@
+"""PRME FastAPI application factory.
+
+Creates and configures the FastAPI app with lifespan management
+for the MemoryEngine. The engine is stored in app.state and shared
+across all request handlers.
+"""
+
+from __future__ import annotations
+
+import logging
+from contextlib import asynccontextmanager
+from typing import AsyncIterator
+
+from fastapi import FastAPI, Request
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import JSONResponse
+
+from prme import __version__
+from prme.config import PRMEConfig
+
+logger = logging.getLogger(__name__)
+
+
+def create_app(config: PRMEConfig | None = None) -> FastAPI:
+    """Create and configure the PRME FastAPI application.
+
+    Args:
+        config: Optional PRME configuration. Defaults to PRMEConfig().
+
+    Returns:
+        Configured FastAPI application with engine lifespan management.
+    """
+    if config is None:
+        config = PRMEConfig()
+
+    @asynccontextmanager
+    async def lifespan(app: FastAPI) -> AsyncIterator[None]:
+        """Manage MemoryEngine lifecycle."""
+        from prme.storage.engine import MemoryEngine
+
+        logger.info("Starting PRME MemoryEngine...")
+        engine = await MemoryEngine.create(config)
+        app.state.engine = engine
+        logger.info("PRME MemoryEngine ready (backend=%s)", config.backend)
+
+        yield
+
+        logger.info("Shutting down PRME MemoryEngine...")
+        await engine.close()
+        app.state.engine = None
+        logger.info("PRME MemoryEngine shut down")
+
+    app = FastAPI(
+        title="PRME API",
+        description="Portable Relational Memory Engine — HTTP API",
+        version=__version__,
+        lifespan=lifespan,
+    )
+
+    # Expose config to request handlers (auth dependency reads it).
+    app.state.config = config
+    app.state.engine = None
+
+    # CORS — disabled unless origins are explicitly pinned (issue #34).
+    # Credentials are never allowed with a wildcard origin: Starlette
+    # reflects the request Origin in that combination, letting any
+    # website read responses cross-origin.
+    cors_origins = config.api.cors_origins
+    if cors_origins:
+        allow_credentials = (
+            config.api.cors_allow_credentials and "*" not in cors_origins
+        )
+        if config.api.cors_allow_credentials and not allow_credentials:
+            logger.warning(
+                "cors_allow_credentials ignored: wildcard origin in "
+                "cors_origins. Pin explicit origins to allow credentials."
+            )
+        app.add_middleware(
+            CORSMiddleware,
+            allow_origins=cors_origins,
+            allow_credentials=allow_credentials,
+            allow_methods=["*"],
+            allow_headers=["*"],
+        )
+
+    # Generic handler for unexpected errors: log details server-side,
+    # never echo internals to the caller (issue #34).
+    @app.exception_handler(Exception)
+    async def unhandled_exception_handler(
+        request: Request, exc: Exception
+    ) -> JSONResponse:
+        logger.error(
+            "Unhandled error on %s %s", request.method, request.url.path,
+            exc_info=exc,
+        )
+        return JSONResponse(
+            status_code=500, content={"detail": "Internal server error"}
+        )
+
+    # Register routes
+    from prme.api.routes import public_router, router
+
+    app.include_router(public_router)
+    app.include_router(router)
+
+    return app