experia 0.2.1__py3-none-any.whl

experia/context/builder.py

@@ -0,0 +1,32 @@
+from typing import List
+
+from experia.memory.models import Memory
+
+
+class ContextBuilder:
+    """
+    Transforms raw memories into structured, usable intelligence for the agent.
+    """
+
+    def format_for_prompt(self, memories: List[Memory]) -> str:
+        """
+        Takes a list of memories and formats them into a text string
+        that can be injected into an LLM system prompt.
+        """
+        if not memories:
+            return ""
+
+        context_lines = ["--- User Context & Learned Experience ---"]
+
+        # Group by type for better readability by the LLM
+        grouped_memories = {}
+        for mem in memories:
+            grouped_memories.setdefault(mem.type.value, []).append(mem)
+
+        for mem_type, type_memories in grouped_memories.items():
+            context_lines.append(f"\n[{mem_type.upper()}]")
+            for mem in type_memories:
+                context_lines.append(f"- {mem.content}")
+
+        context_lines.append("\n---------------------------------------")
+        return "\n".join(context_lines)

experia/core/exceptions.py

@@ -0,0 +1,22 @@
+class ExperiaError(Exception):
+    """Base exception for all Experia errors."""
+
+    pass
+
+
+class StorageError(ExperiaError):
+    """Raised when a storage operation fails."""
+
+    pass
+
+
+class EvaluationError(ExperiaError):
+    """Raised when an experience evaluation fails."""
+
+    pass
+
+
+class ConfigurationError(ExperiaError):
+    """Raised when Experia is misconfigured."""
+
+    pass

experia/core/interfaces.py

@@ -0,0 +1,32 @@
+from typing import List, Optional, Protocol
+from uuid import UUID
+
+from experia.experience.models import ExperienceRecord, Lesson
+from experia.memory.models import Memory, MemoryType
+
+
+class MemoryStore(Protocol):
+    """Protocol for memory and experience storage backends."""
+
+    async def save_experience(self, experience: ExperienceRecord) -> None: ...
+
+    async def get_experience(
+        self, experience_id: UUID
+    ) -> Optional[ExperienceRecord]: ...
+
+    async def save_lesson(self, lesson: Lesson) -> None: ...
+
+    async def save_memory(self, memory: Memory) -> None: ...
+
+    async def search_memories(
+        self,
+        query: str = "",
+        memory_type: Optional[MemoryType] = None,
+        limit: int = 10,
+    ) -> List[Memory]: ...
+
+
+class Evaluator(Protocol):
+    """Protocol for experience evaluators."""
+
+    async def evaluate(self, experience: ExperienceRecord) -> Optional[Lesson]: ...

experia/core/learner.py

@@ -0,0 +1,85 @@
+from typing import Any, Dict, Optional
+
+from experia.context.builder import ContextBuilder
+from experia.core.exceptions import ConfigurationError
+from experia.core.interfaces import Evaluator, MemoryStore
+from experia.core.logging import logger
+from experia.experience.models import ExperienceRecord
+from experia.improvement.rules import RuleGenerator
+from experia.memory.models import Memory, MemoryType
+
+
+class Learner:
+    """
+    The main asynchronous entry point for the Experia AI Cognitive Layer.
+    Uses Dependency Injection to accept any MemoryStore and Evaluator implementations.
+    """
+
+    def __init__(
+        self,
+        store: MemoryStore,
+        evaluator: Evaluator,
+        rule_generator: Optional[RuleGenerator] = None,
+    ):
+        if not store or not evaluator:
+            raise ConfigurationError("Learner requires both a store and an evaluator.")
+
+        self.store = store
+        self.evaluator = evaluator
+        self.rule_generator = rule_generator
+        self.context_builder = ContextBuilder()
+        logger.info("Experia Learner initialized successfully.")
+
+    async def record(
+        self,
+        task: str,
+        action: str,
+        result: str,
+        context: Optional[Dict[str, Any]] = None,
+    ) -> ExperienceRecord:
+        """Records an agent's action and its result asynchronously."""
+        experience = ExperienceRecord(
+            task=task, action=action, result=result, context=context or {}
+        )
+        await self.store.save_experience(experience)
+        logger.debug(f"Recorded experience {experience.id} for task '{task}'")
+
+        await self._evaluate_and_remember(experience)
+        return experience
+
+    async def _evaluate_and_remember(self, experience: ExperienceRecord) -> None:
+        """Internal asynchronous method to evaluate an experience and store its lesson."""
+        lesson = await self.evaluator.evaluate(experience)
+        if lesson:
+            await self.store.save_lesson(lesson)
+
+            memory = Memory(
+                content=lesson.content,
+                type=MemoryType.LESSON,
+                confidence=lesson.confidence,
+                importance=0.7,
+                source=f"Experience:{experience.id}",
+            )
+            await self.store.save_memory(memory)
+            logger.info(
+                f"Learned and remembered lesson from experience {experience.id}"
+            )
+
+            # Optionally generate a global rule
+            if self.rule_generator:
+                await self.rule_generator.consolidate_lesson(lesson)
+
+    async def retrieve_context(self, query: str = "", limit: int = 5) -> str:
+        """Searches cognitive memory and builds a prompt string asynchronously."""
+        memories = await self.store.search_memories(query=query, limit=limit)
+        logger.debug(f"Retrieved {len(memories)} memories for context.")
+        return self.context_builder.format_for_prompt(memories)
+
+    async def remember(
+        self, content: str, memory_type: MemoryType = MemoryType.FACT
+    ) -> Memory:
+        """Manually add a piece of knowledge to the memory store asynchronously."""
+        memory = Memory(content=content, type=memory_type, importance=0.9)
+        await self.store.save_memory(memory)
+        logger.debug(f"Manually remembered explicit knowledge: {memory.id}")
+        return memory

experia/core/logging.py

@@ -0,0 +1,17 @@
+import logging
+
+# Configure the package-level logger
+logger = logging.getLogger("experia")
+
+# Prevent log propagation to the root logger by default to avoid duplicate logs
+# if the user hasn't configured a handler.
+logger.propagate = False
+
+if not logger.handlers:
+    handler = logging.StreamHandler()
+    formatter = logging.Formatter(
+        "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+    )
+    handler.setFormatter(formatter)
+    logger.addHandler(handler)
+    logger.setLevel(logging.INFO)

experia/experience/evaluator.py

@@ -0,0 +1,38 @@
+from typing import Optional
+
+from experia.core.interfaces import Evaluator
+from experia.core.logging import logger
+from experia.experience.models import ExperienceRecord, Lesson
+
+
+class SimpleHeuristicEvaluator(Evaluator):
+    """
+    An asynchronous heuristic-based evaluator for testing and basic usage.
+    Implements the Evaluator Protocol.
+    """
+
+    async def evaluate(self, experience: ExperienceRecord) -> Optional[Lesson]:
+        """Evaluates the experience asynchronously."""
+        lower_result = experience.result.lower()
+
+        if "fail" in lower_result or "error" in lower_result:
+            content = (
+                f"The action '{experience.action}' failed during "
+                f"'{experience.task}'. Ensure prerequisites are met before retrying."
+            )
+            confidence = 0.6
+            logger.info(f"Evaluator detected failure for experience {experience.id}")
+        elif "success" in lower_result:
+            content = (
+                f"The action '{experience.action}' was successful for "
+                f"'{experience.task}'. This strategy works."
+            )
+            confidence = 0.8
+            logger.info(f"Evaluator detected success for experience {experience.id}")
+        else:
+            logger.debug(f"No actionable lesson found for experience {experience.id}")
+            return None
+
+        return Lesson(
+            experience_id=experience.id, content=content, confidence=confidence
+        )

experia/experience/llm_evaluator.py

@@ -0,0 +1,86 @@
+import json
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+from experia.core.exceptions import EvaluationError
+from experia.core.interfaces import Evaluator
+from experia.core.logging import logger
+from experia.experience.models import ExperienceRecord, Lesson
+
+try:
+    import litellm
+except ImportError:
+    litellm = None
+
+
+class EvaluatorResponseSchema(BaseModel):
+    """Internal schema to force structured JSON output from the LLM."""
+
+    lesson: str = Field(description="The extracted lesson or behavioral rule.")
+    root_cause: str = Field(description="The root cause analysis of the outcome.")
+    confidence: float = Field(description="Confidence from 0.0 to 1.0.")
+
+
+class LLMEvaluator(Evaluator):
+    """
+    An advanced evaluator that uses an LLM via litellm to deeply analyze experiences.
+    Requires litellm and a configured API key for the chosen model.
+    """
+
+    def __init__(self, model: str = "gpt-4o"):
+        if not litellm:
+            raise EvaluationError(
+                "litellm is not installed. Please install experia[llm] or litellm to use the LLMEvaluator."
+            )
+        self.model = model
+        self.system_prompt = (
+            "You are an expert cognitive evaluator for an AI agent. "
+            "Analyze the given agent's action and its result.\n"
+            "1. Identify the root cause of why it succeeded or failed.\n"
+            "2. Extract a concise, generalized lesson that the agent should remember for the future.\n"
+            "Return the output in valid JSON format matching this schema:\n"
+            '{"lesson": "string", "root_cause": "string", "confidence": float}'
+        )
+
+    async def evaluate(self, experience: ExperienceRecord) -> Optional[Lesson]:
+        user_prompt = (
+            f"Task: {experience.task}\n"
+            f"Action Taken: {experience.action}\n"
+            f"Result/Outcome: {experience.result}\n"
+            f"Active Context: {json.dumps(experience.context)}\n"
+        )
+
+        try:
+            response = await litellm.acompletion(
+                model=self.model,
+                messages=[
+                    {"role": "system", "content": self.system_prompt},
+                    {"role": "user", "content": user_prompt},
+                ],
+                response_format={"type": "json_object"},
+                temperature=0.2,
+            )
+
+            raw_content = response.choices[0].message.content
+            if not raw_content:
+                logger.warning(
+                    f"LLM returned empty content for experience {experience.id}"
+                )
+                return None
+
+            parsed = EvaluatorResponseSchema.model_validate_json(raw_content)
+
+            logger.info(f"LLM successfully evaluated experience {experience.id}")
+            return Lesson(
+                experience_id=experience.id,
+                content=parsed.lesson,
+                root_cause=parsed.root_cause,
+                confidence=parsed.confidence,
+            )
+
+        except Exception as e:
+            logger.error(
+                f"LLMEvaluator failed to evaluate experience {experience.id}: {e}"
+            )
+            raise EvaluationError(f"LLM evaluation failed: {e}")

experia/experience/models.py

@@ -0,0 +1,77 @@
+from datetime import datetime, timezone
+from typing import Any, Dict, Optional
+from uuid import UUID, uuid4
+
+from pydantic import BaseModel, Field
+
+
+class ExperienceRecord(BaseModel):
+    """
+    Represents a raw experience captured from an agent's execution.
+    It logs the exact task, action taken, and the subsequent outcome.
+    """
+
+    id: UUID = Field(
+        default_factory=uuid4,
+        description="Unique identifier for the experience record.",
+    )
+    task: str = Field(
+        ...,
+        description="The high-level task or goal the agent was attempting.",
+        json_schema_extra={"example": "Deploy web application"},
+    )
+    action: str = Field(
+        ...,
+        description="The specific action or tool call executed.",
+        json_schema_extra={"example": "Run command: docker restart nginx"},
+    )
+    result: str = Field(
+        ...,
+        description="The raw outcome, error message, or output of the action.",
+        json_schema_extra={"example": "Failed: port 80 is already bound."},
+    )
+    context: Optional[Dict[str, Any]] = Field(
+        default_factory=dict,
+        description="Optional state variables or memory context active during the action.",
+    )
+    created_at: datetime = Field(
+        default_factory=lambda: datetime.now(timezone.utc),
+        description="Timestamp when the experience occurred.",
+    )
+
+
+class Lesson(BaseModel):
+    """
+    Represents a discrete lesson extracted by the Evaluator engine from an experience.
+    """
+
+    id: UUID = Field(
+        default_factory=uuid4, description="Unique identifier for the lesson."
+    )
+    experience_id: UUID = Field(
+        ..., description="The ID of the experience this lesson was derived from."
+    )
+    content: str = Field(
+        ...,
+        description="The actual knowledge or rule extracted.",
+        json_schema_extra={
+            "example": "Always verify port availability using lsof -i :80 before starting the web server."
+        },
+    )
+    root_cause: Optional[str] = Field(
+        default=None,
+        description="The underlying reason why the action succeeded or failed.",
+        json_schema_extra={
+            "example": "The port 80 was still bound by an old docker container."
+        },
+    )
+    confidence: float = Field(
+        default=0.8,
+        ge=0.0,
+        le=1.0,
+        description="The system's confidence in this lesson (0.0 to 1.0).",
+    )
+    created_at: datetime = Field(
+        default_factory=lambda: datetime.now(timezone.utc),
+        description="Timestamp when the lesson was extracted.",
+    )

experia/improvement/rules.py

@@ -0,0 +1,71 @@
+from typing import Optional
+
+from experia.core.interfaces import MemoryStore
+from experia.core.logging import logger
+from experia.experience.models import Lesson
+from experia.memory.models import Memory, MemoryType
+
+try:
+    import litellm
+except ImportError:
+    litellm = None
+
+
+class RuleGenerator:
+    """
+    Analyzes lessons and elevates them into permanent behavioral rules using an LLM.
+    """
+
+    def __init__(self, store: MemoryStore, model: str = "gpt-4o"):
+        self.store = store
+        self.model = model
+        self.system_prompt = (
+            "You are a cognitive consolidator for an AI agent. "
+            "You will be given a recent 'Lesson' the agent learned from an experience. "
+            "Determine if this lesson represents a fundamental, reusable behavioral rule "
+            "that the agent should ALWAYS follow. "
+            "If yes, extract it as a concise, generalized RULE (e.g. 'Always do X before Y'). "
+            "If no (it is too specific or trivial), return 'NONE'.\n"
+            "Return ONLY the rule string, or 'NONE'."
+        )
+
+    async def consolidate_lesson(self, lesson: Lesson) -> Optional[Memory]:
+        """Evaluates a lesson and potentially creates a RULE memory."""
+        if not litellm:
+            logger.debug("litellm is not installed. Rule generation skipped.")
+            return None
+
+        user_prompt = (
+            f"Lesson Content: {lesson.content}\n"
+            f"Root Cause: {lesson.root_cause or 'Unknown'}\n"
+        )
+
+        try:
+            response = await litellm.acompletion(
+                model=self.model,
+                messages=[
+                    {"role": "system", "content": self.system_prompt},
+                    {"role": "user", "content": user_prompt},
+                ],
+                temperature=0.1,
+            )
+
+            rule_text = response.choices[0].message.content.strip()
+            if not rule_text or rule_text == "NONE":
+                logger.debug(f"Lesson {lesson.id} was not elevated to a rule.")
+                return None
+
+            rule_memory = Memory(
+                content=rule_text,
+                type=MemoryType.RULE,
+                importance=1.0,  # Rules are highly important
+                source=f"Lesson:{lesson.id}",
+            )
+
+            await self.store.save_memory(rule_memory)
+            logger.info(f"Generated new RULE from lesson {lesson.id}: {rule_text}")
+            return rule_memory
+
+        except Exception as e:
+            logger.error(f"RuleGenerator failed for lesson {lesson.id}: {e}")
+            return None

experia/memory/models.py

@@ -0,0 +1,64 @@
+from datetime import datetime, timezone
+from enum import Enum
+from typing import Any, Dict, Optional
+from uuid import UUID, uuid4
+
+from pydantic import BaseModel, Field
+
+
+class MemoryType(str, Enum):
+    """Enumeration of the different cognitive types of memory."""
+
+    FACT = "fact"
+    PREFERENCE = "preference"
+    LESSON = "lesson"
+    RULE = "rule"
+    EXPERIENCE = "experience"
+
+
+class Memory(BaseModel):
+    """
+    Represents a unit of knowledge stored in the cognitive memory layer.
+    """
+
+    id: UUID = Field(
+        default_factory=uuid4, description="Unique identifier for the memory."
+    )
+    content: str = Field(
+        ...,
+        description="The actual knowledge stored.",
+        json_schema_extra={"example": "User prefers short, concise answers."},
+    )
+    type: MemoryType = Field(..., description="The category/type of this memory.")
+    confidence: float = Field(
+        default=0.8,
+        ge=0.0,
+        le=1.0,
+        description="Confidence level in the accuracy of this memory.",
+    )
+    importance: float = Field(
+        default=0.5,
+        ge=0.0,
+        le=1.0,
+        description="Importance weight used for retrieval ranking (0.0 to 1.0).",
+    )
+    source: Optional[str] = Field(
+        default=None,
+        description="Where this memory originated from (e.g., user input, experience ID).",
+    )
+    metadata: Optional[Dict[str, Any]] = Field(
+        default_factory=dict,
+        description="Additional custom data for advanced filtering.",
+    )
+
+    created_at: datetime = Field(
+        default_factory=lambda: datetime.now(timezone.utc),
+        description="When the memory was first created.",
+    )
+    updated_at: datetime = Field(
+        default_factory=lambda: datetime.now(timezone.utc),
+        description="When the memory was last modified or reinforced.",
+    )
+    expires_at: Optional[datetime] = Field(
+        default=None, description="Optional expiration time for ephemeral memories."
+    )

experia/memory/store.py

@@ -0,0 +1,224 @@
+import json
+from datetime import datetime
+from typing import List, Optional
+from uuid import UUID
+
+import aiosqlite
+
+from experia.core.exceptions import StorageError
+from experia.experience.models import ExperienceRecord, Lesson
+from experia.memory.models import Memory, MemoryType
+
+
+class SQLiteStore:
+    """
+    An asynchronous SQLite-based local storage backend for Experia.
+    Implements the MemoryStore Protocol.
+    """
+
+    def __init__(self, db_path: str = "experia.db"):
+        self.db_path = db_path
+
+    async def initialize(self) -> None:
+        """Initializes the database schema if it doesn't exist."""
+        try:
+            async with aiosqlite.connect(self.db_path) as conn:
+                # Experiences Table
+                await conn.execute("""
+                    CREATE TABLE IF NOT EXISTS experiences (
+                        id TEXT PRIMARY KEY,
+                        task TEXT NOT NULL,
+                        action TEXT NOT NULL,
+                        result TEXT NOT NULL,
+                        context TEXT,
+                        created_at TEXT NOT NULL
+                    )
+                """)
+
+                # Lessons Table
+                await conn.execute("""
+                    CREATE TABLE IF NOT EXISTS lessons (
+                        id TEXT PRIMARY KEY,
+                        experience_id TEXT NOT NULL,
+                        content TEXT NOT NULL,
+                        root_cause TEXT,
+                        confidence REAL NOT NULL,
+                        created_at TEXT NOT NULL,
+                        FOREIGN KEY (experience_id) REFERENCES experiences (id)
+                    )
+                """)
+
+                # Check for existing table and add root_cause if missing (migration)
+                cursor = await conn.execute("PRAGMA table_info(lessons)")
+                columns = [row[1] for row in await cursor.fetchall()]
+                if "root_cause" not in columns:
+                    await conn.execute("ALTER TABLE lessons ADD COLUMN root_cause TEXT")
+
+                # Memories Table
+                await conn.execute("""
+                    CREATE TABLE IF NOT EXISTS memories (
+                        id TEXT PRIMARY KEY,
+                        content TEXT NOT NULL,
+                        type TEXT NOT NULL,
+                        confidence REAL NOT NULL,
+                        importance REAL NOT NULL,
+                        source TEXT,
+                        metadata TEXT,
+                        created_at TEXT NOT NULL,
+                        updated_at TEXT NOT NULL,
+                        expires_at TEXT
+                    )
+                """)
+                await conn.commit()
+        except Exception as e:
+            raise StorageError(f"Failed to initialize SQLite database: {e}")
+
+    # --- Experience Methods ---
+
+    async def save_experience(self, experience: ExperienceRecord) -> None:
+        """Saves a raw experience record asynchronously."""
+        try:
+            async with aiosqlite.connect(self.db_path) as conn:
+                await conn.execute(
+                    """
+                    INSERT INTO experiences (id, task, action, result, context, created_at)
+                    VALUES (?, ?, ?, ?, ?, ?)
+                    """,
+                    (
+                        str(experience.id),
+                        experience.task,
+                        experience.action,
+                        experience.result,
+                        json.dumps(experience.context) if experience.context else None,
+                        experience.created_at.isoformat(),
+                    ),
+                )
+                await conn.commit()
+        except Exception as e:
+            raise StorageError(f"Failed to save experience: {e}")
+
+    async def get_experience(self, experience_id: UUID) -> Optional[ExperienceRecord]:
+        """Retrieves an experience by its ID asynchronously."""
+        try:
+            async with aiosqlite.connect(self.db_path) as conn:
+                cursor = await conn.execute(
+                    "SELECT * FROM experiences WHERE id = ?", (str(experience_id),)
+                )
+                row = await cursor.fetchone()
+
+                if row:
+                    return ExperienceRecord(
+                        id=UUID(row[0]),
+                        task=row[1],
+                        action=row[2],
+                        result=row[3],
+                        context=json.loads(row[4]) if row[4] else {},
+                        created_at=datetime.fromisoformat(row[5]),
+                    )
+            return None
+        except Exception as e:
+            raise StorageError(f"Failed to retrieve experience: {e}")
+
+    # --- Lesson Methods ---
+
+    async def save_lesson(self, lesson: Lesson) -> None:
+        """Saves an extracted lesson asynchronously."""
+        try:
+            async with aiosqlite.connect(self.db_path) as conn:
+                await conn.execute(
+                    """
+                    INSERT INTO lessons (id, experience_id, content, root_cause, confidence, created_at)
+                    VALUES (?, ?, ?, ?, ?, ?)
+                    """,
+                    (
+                        str(lesson.id),
+                        str(lesson.experience_id),
+                        lesson.content,
+                        lesson.root_cause,
+                        lesson.confidence,
+                        lesson.created_at.isoformat(),
+                    ),
+                )
+                await conn.commit()
+        except Exception as e:
+            raise StorageError(f"Failed to save lesson: {e}")
+
+    # --- Memory Methods ---
+
+    async def save_memory(self, memory: Memory) -> None:
+        """Saves a memory object asynchronously."""
+        try:
+            async with aiosqlite.connect(self.db_path) as conn:
+                await conn.execute(
+                    """
+                    INSERT OR REPLACE INTO memories 
+                    (id, content, type, confidence, importance, source, metadata, 
+                    created_at, updated_at, expires_at)
+                    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+                    """,
+                    (
+                        str(memory.id),
+                        memory.content,
+                        memory.type.value,
+                        memory.confidence,
+                        memory.importance,
+                        memory.source,
+                        json.dumps(memory.metadata) if memory.metadata else None,
+                        memory.created_at.isoformat(),
+                        memory.updated_at.isoformat(),
+                        memory.expires_at.isoformat() if memory.expires_at else None,
+                    ),
+                )
+                await conn.commit()
+        except Exception as e:
+            raise StorageError(f"Failed to save memory: {e}")
+
+    async def search_memories(
+        self,
+        query: str = "",
+        memory_type: Optional[MemoryType] = None,
+        limit: int = 10,
+    ) -> List[Memory]:
+        """
+        Asynchronous simple text-based search for memories.
+        """
+        memories = []
+        try:
+            async with aiosqlite.connect(self.db_path) as conn:
+                sql = "SELECT * FROM memories WHERE 1=1"
+                params = []
+
+                if query:
+                    sql += " AND content LIKE ?"
+                    params.append(f"%{query}%")
+
+                if memory_type:
+                    sql += " AND type = ?"
+                    params.append(memory_type.value)
+
+                sql += " ORDER BY importance DESC, confidence DESC LIMIT ?"
+                params.append(limit)
+
+                cursor = await conn.execute(sql, tuple(params))
+                rows = await cursor.fetchall()
+
+                for row in rows:
+                    memories.append(
+                        Memory(
+                            id=UUID(row[0]),
+                            content=row[1],
+                            type=MemoryType(row[2]),
+                            confidence=row[3],
+                            importance=row[4],
+                            source=row[5],
+                            metadata=json.loads(row[6]) if row[6] else {},
+                            created_at=datetime.fromisoformat(row[7]),
+                            updated_at=datetime.fromisoformat(row[8]),
+                            expires_at=datetime.fromisoformat(row[9])
+                            if row[9]
+                            else None,
+                        )
+                    )
+            return memories
+        except Exception as e:
+            raise StorageError(f"Failed to search memories: {e}")

experia-0.2.1.dist-info/METADATA

@@ -0,0 +1,102 @@
+Metadata-Version: 2.4
+Name: experia
+Version: 0.2.1
+Summary: The open-source experience learning layer for AI agents.
+Author-email: Experia AI Contributors <hello@experia.ai>
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: aiosqlite>=0.20.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.4.0; extra == 'dev'
+Provides-Extra: llm
+Requires-Dist: litellm>=1.0.0; extra == 'llm'
+Description-Content-Type: text/markdown
+
+# Experia AI
+
+The open-source experience learning layer for AI agents.
+
+Experia enables agents to learn from past actions, failures, and outcomes.
+It provides experience capture, lesson extraction, behavioral improvement,
+and long-term cognitive memory without replacing existing agent frameworks.
+
+## Vision
+
+Current AI agents start from zero on every interaction. Experia adds an **experience learning loop** around agents. It allows agents to remember what happened, understand why it worked or failed, and improve future decisions.
+
+**Observation → Action → Result → Experience → Lesson → Memory → Better Future Action**
+
+```mermaid
+flowchart TD
+    subgraph Agent Application
+        Agent[AI Agent / LLM]
+        Task[Execute Task]
+        Agent -- Takes Action --> Task
+    end
+
+    subgraph Experia AI Cognitive Layer [Experia Async Cognitive Layer]
+        Store[(MemoryStore Protocol)]
+        Eval[Evaluator Protocol]
+        Ctx[Context Builder]
+        
+        Task -- 1. await record() --> Store
+        Store -- 2. Analyze Experience --> Eval
+        Eval -- 3. Extract Lesson --> Store
+        Store -- 4. await retrieve_context() --> Ctx
+    end
+    
+    Ctx -- 5. Inject Knowledge --> Agent
+```
+
+## Integrations
+
+Experia acts as a cognitive plugin. It does not replace your agent frameworks (like LangChain, AutoGen, CrewAI), it enhances them by managing long-term memory, learned experiences, user knowledge, and behavioral patterns.
+
+## Getting Started
+
+Experia uses an **asynchronous** and **pluggable** architecture.
+
+```bash
+pip install experia
+```
+
+```python
+import asyncio
+from experia.core.learner import Learner
+from experia.memory.store import SQLiteStore
+from experia.experience.evaluator import SimpleHeuristicEvaluator
+
+
+async def main():
+    # 1. Dependency Injection setup
+    store = SQLiteStore("my_agent.db")
+    await store.initialize()
+
+    evaluator = SimpleHeuristicEvaluator()
+
+    # 2. Initialize Learner
+    agent = Learner(store=store, evaluator=evaluator)
+
+    # 3. Use the async API to record actions
+    await agent.record(
+        task="Deploy web app",
+        action="Restart Nginx",
+        result="failed with config syntax error",
+    )
+
+    # 4. Retrieve memory context for your LLM
+    context = await agent.retrieve_context()
+    print(context)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## License
+
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.

experia-0.2.1.dist-info/RECORD

@@ -0,0 +1,34 @@
+experia/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+experia/adapters/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+experia/adapters/mem0.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+experia/adapters/postgres.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+experia/adapters/zep.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+experia/context/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+experia/context/builder.py,sha256=b1Q2WHyb6Z5bskqqY8QXPDy640EBYixR08RA9yAfz3c,1044
+experia/core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+experia/core/exceptions.py,sha256=9DjA6BTXxPf--_8d5bNe-8CP2LX1eBcFm_V0_qSPKoY,388
+experia/core/interfaces.py,sha256=4-2mIhSmwxIPIk6GAkdjsD1aBqhnjP-fktErafDuvn8,920
+experia/core/learner.py,sha256=6nrUQXduu8O0RDj_ATBTAoTkZaoY2Cug1GpfBJ_v9PM,3356
+experia/core/logging.py,sha256=ogjeDG2oqKhpdI1xmJlbT8tztr_H5V9q9bGK7EGKLno,508
+experia/experience/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+experia/experience/collector.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+experia/experience/evaluator.py,sha256=L55SaurrtfJVd5-ttWpp3dEKm7ay5_pyExP1J0uX10Q,1472
+experia/experience/lessons.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+experia/experience/llm_evaluator.py,sha256=hBw6d_Tx0ONcq_a1kzgYpnuAaXFQBOxVRJ7cljSooZ4,3228
+experia/experience/models.py,sha256=5YVkr9qTYmqF5jLpymDGB-BwlYG858DpeeZz1mBO2VE,2585
+experia/improvement/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+experia/improvement/rules.py,sha256=bj3i85NlRUb8Dkrk4wjAI-Z-4eAXVMdDbdlNrn4Tx7k,2594
+experia/improvement/strategies.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+experia/integrations/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+experia/integrations/langchain.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+experia/integrations/langgraph.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+experia/memory/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+experia/memory/models.py,sha256=k6GBTmbvMCO3NMwQuo0ftUHlMI_zGmbxo0QlxCHvUnE,1977
+experia/memory/store.py,sha256=Nl6QMuL2sq7vMWsn1Pzksy2Mh-DdJxa4EQNL_2Ew3eE,8762
+experia/reflection/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+experia/reflection/conflict.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+experia/reflection/consolidation.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+experia-0.2.1.dist-info/METADATA,sha256=0T6QaqSnVsExk_vMo7u38gVJ05R8BqsalHTpj77KP2Q,3043
+experia-0.2.1.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+experia-0.2.1.dist-info/licenses/LICENSE,sha256=EXGi_NZXQyjN9a23PCxw4Gmy4HrUviDJpsfHslDgn4Q,1080
+experia-0.2.1.dist-info/RECORD,,

experia-0.2.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

experia-0.2.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Experia AI Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.