feat: new features in scope (memory decay half_life, observability, examples, almock)

Author: divshekhar

CHANGELOG.md

@@ -5,48 +5,31 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [0.2.0] - 2026-02-26
 
 ### Added
 
-- **Code quality (Step 6):** `docs/ARCHITECTURE.md` with package layout, dependency direction, extension points, and §6 consistent patterns (naming: *Protocol/*Backend/*Config/*Store/*Manager; errors: SyrinError; Protocol vs ABC). `docs/code-quality.md` for mypy, ruff, public API typing, coverage, and dead-code rules. `tests/code_quality/`: `test_public_api_exports.py` (all `__all__` importable, no duplicates, run return type), `test_run_and_config_api.py` (run/config valid and edge cases with mocks), `test_critical_path_edge_cases.py` (threshold, config, run empty input).
-
-- **Core stability (Step 4):** New test suite `tests/core_stability/` with TDD tests for agent lifecycle (sync/async parity), loop strategies (LoopResult shape, exception handling), model resolution (valid provider, strict mode), budget enforcement (per-run, threshold actions), memory (remember/recall/forget, conversation path), Response contract (cost/tokens/tool_calls/stop_reason), and structured output validation.
-- **Model resolution:** `ProviderNotFoundError` exception and `get_provider(name, strict=True)`; when `strict=True`, unknown provider names raise with a clear message listing known providers. Agent uses strict resolution when resolving from `ModelConfig` so invalid `provider=` fails fast.
-- **Observability:** Span coverage for agent runs: root agent span plus automatic child spans for each LLM call and tool execution when the loop uses a tracer. `AgentRunContext` now exposes an optional `tracer` property so loops can create LLM/tool spans.
-- **Observability:** `_llm_span_context` and `_tool_span_context` helpers in `loop` so SingleShot and React loops create `SpanKind.LLM` and `SpanKind.TOOL` spans with semantic attributes (tokens, model, tool name, input/output).
-- **Observability:** OTLP exporter implementation in `syrin.observability.otlp`: `OTLPExporter` converts Syrin spans to OpenTelemetry and exports to OTLP HTTP endpoint when optional dependency is installed; no-op when not.
-- **Tests:** `tests/observability/test_observability_integration.py` — TDD tests for span coverage (agent/LLM/tool), session propagation, metrics schema, sampling parent-child consistency, debug mode, OTLP exporter, hook coverage, and export format.
+- **Almock (LLM Mock)** — `Model.Almock()` for development and testing without an API key. Configurable pricing tiers (LOW, MEDIUM, HIGH, ULTRA_HIGH), latency (default 1–3s or custom), and response (Lorem Ipsum or custom text). Examples and docs use Almock by default; swap to a real model with one line.
+- **Memory decay and consolidation** — Decay strategies with configurable min importance and optional reinforcement on access. `Memory.consolidate()` for content deduplication with optional budget. Entries without IDs receive auto-generated IDs.
+- **Checkpoint triggers** — Auto-save on STEP, TOOL, ERROR, or BUDGET in addition to MANUAL. Loop strategy comparison (REACT, SINGLE_SHOT, PLAN_EXECUTE, CODE_ACTION) documented in advanced topics.
+- **Provider resolution** — `ProviderNotFoundError` when using an unknown provider, with a message listing known providers. Strict resolution available via `get_provider(name, strict=True)`.
+- **Observability** — Agent runs emit a root span plus child spans for each LLM call and tool execution. Session ID propagates to all spans. Optional OTLP exporter (`syrin.observability.otlp`) for OpenTelemetry.
+- **Documentation** — Architecture guide, code quality guidelines, CONTRIBUTING.md. Community links (Discord, X) and corrected doc links.
 
 ### Changed
 
-- **Documentation (Step 7):** README: Discord link updated to https://discord.gg/p4jnKxYKpB, Twitter to https://x.com/syrin_dev; added “Connect here” community section. Docs: fixed dead links (anomalyco → syrin-labs/syrin-python, CHANGES.md → CHANGELOG.md); docs/README.md Quick Start uses `syrin` (lowercase). Created CONTRIBUTING.md and docs/code-quality.md. docs/guardrails.md and docs/ratelimit.md: corrected support/import links and `from syrin` imports. docs/advanced-topics.md: rate-limiting.md → ratelimit.md. Removed plan/*.md references from public docs (CHANGELOG).
-
-- **Code quality (Step 6):** `syrin.run()` signature: `tools` typed as `list[ToolSpec] | None`, return as `Response[str]`. Removed duplicate entries from `syrin.__all__` (BudgetThreshold, CheckpointTrigger). `syrin.config.__all__`: removed duplicate GlobalConfig. Ruff ignore list in pyproject.toml documented (E501, E402, ARG002, ARG001, F821, F811).
-
-- **Model resolution:** `get_provider(provider_name, *, strict=False)` — new `strict` parameter; Agent construction with `ModelConfig(provider="typo")` now raises `ProviderNotFoundError` (breaking for callers relying on fallback to LiteLLM).
-- **Observability:** Session ID from `trace.session()` now propagates to all spans created during agent runs (spans already had `session_id`; context was already used by tracer).
-- **Docs:** `docs/observability.md` — Updated "What's Traced by Default" with exact span kinds and tree shape; added Metrics schema subsection; fixed Production Setup imports (create_sampler from sampling).
-- **Plan:** Observability checklist for v0.2.0 marked complete.
+- **Model resolution** — Agent construction with an invalid `provider` in `ModelConfig` now raises `ProviderNotFoundError` instead of falling back (breaking for callers relying on LiteLLM fallback).
+- **API** — `syrin.run()` return type and `tools` parameter typing clarified. Duplicate symbols removed from public API exports.
+- **Docs** — README and guides use lowercase `syrin` imports. Guardrails and rate-limit docs: fixed imports and references.
 
 ### Fixed
 
-- **Step 5 (Bug fixes):** Response data regression tests for sync/async parity and tool_calls from loop. recall() contract tests (Agent/Memory/MemoryStore return shape). spawn() return type (Response vs Agent) and budget inheritance tests. Hook emission audit (agent run emits only Hook enum). Rate limit: threshold behavior is fully controlled by the user’s `action(ctx)` callback on `RateLimitThreshold` (no separate `rate_limit_action`; user implements stop/wait/switch in the callback). Guardrail block tests (input block skips LLM; output block returns GUARDRAIL response). Checkpoint trigger tests (STEP fires, MANUAL does not; save/load). Session `span_count` updated when spans are exported in session context. Edge-case tests (empty tools, no budget, no persistent memory, unknown provider) and typed errors.
-
-### Deprecated
-
-### Removed
-
-### Security
+- Response and recall contract; spawn return type and budget inheritance. Rate limit thresholds fully controlled by user action callback. Guardrail input block skips LLM; output block returns GUARDRAIL response. Checkpoint trigger behavior (STEP, MANUAL). Session span count when exporting. Edge cases: empty tools, no budget, unknown provider.
 
 ---
 
 ## [0.1.1] - 2026-02-25
 
-**syrin** v0.1.1 — Python library for building AI agents with budget management, declarative definitions, and production-ready observability.
-
-Initial Release
-
----
+- Initial release. Python library for building AI agents with budget management, declarative definitions, and observability.
 
 **Install:** `pip install syrin==0.1.1`

README.md

@@ -72,7 +72,8 @@ import os
 from syrin import Agent, Model, Budget, stop_on_exceeded
 
 class Researcher(Agent):
-    model = Model.OpenAI("gpt-4o-mini", api_key=os.getenv("OPENAI_API_KEY"))
+    # model = Model.OpenAI("gpt-4o-mini", api_key=os.getenv("OPENAI_API_KEY"))
+    model = Model.Almock()  # No API Key needed
     budget = Budget(run=0.50, on_exceeded=stop_on_exceeded)
 
 result = Researcher().response("Summarize quantum computing in 3 sentences")
@@ -84,6 +85,8 @@ print(f"Cost: ${result.cost:.4f}  |  Budget used: ${result.budget_used:.4f}")
 
 Pass your API key explicitly. The run is capped at $0.50; when the budget is exceeded, the agent stops.
 
+**No API key?** Examples and docs use `Model.Almock()` by default; comment it out and uncomment the real model when you have an API key.
+
 ---
 
 ## Basic agent (no budget)
@@ -95,7 +98,8 @@ import os
 from syrin import Agent, Model
 
 class Greeter(Agent):
-    model = Model.OpenAI("gpt-4o-mini", api_key=os.getenv("OPENAI_API_KEY"))
+    # model = Model.OpenAI("gpt-4o-mini", api_key=os.getenv("OPENAI_API_KEY"))
+    model = Model.Almock()  # No API Key needed
     system_prompt = "You are a helpful assistant."
 
 result = Greeter().response("Say hello in one sentence.")
@@ -116,7 +120,8 @@ import os
 from syrin import Agent, Model, Budget, stop_on_exceeded
 
 class SafeResearcher(Agent):
-    model = Model.OpenAI("gpt-4o-mini", api_key=os.getenv("OPENAI_API_KEY"))
+    # model = Model.OpenAI("gpt-4o-mini", api_key=os.getenv("OPENAI_API_KEY"))
+    model = Model.Almock()  # No API Key needed
     budget = Budget(run=0.50, on_exceeded=stop_on_exceeded)
 
 result = SafeResearcher().response("Explain photosynthesis briefly.")
@@ -138,7 +143,8 @@ import os
 from syrin import Agent, Model, Budget, BudgetThreshold
 
 class AdaptiveResearcher(Agent):
-    model = Model.OpenAI("gpt-4o-mini", api_key=os.getenv("OPENAI_API_KEY"))
+    # model = Model.OpenAI("gpt-4o-mini", api_key=os.getenv("OPENAI_API_KEY"))
+    model = Model.Almock()  # No API Key needed
     budget = Budget(
         run=0.50,
         thresholds=[
@@ -184,7 +190,8 @@ from syrin import Agent, Model, Budget
 from syrin.enums import Hook
 
 class ObservableAgent(Agent):
-    model = Model.OpenAI("gpt-4o-mini", api_key=os.getenv("OPENAI_API_KEY"))
+    # model = Model.OpenAI("gpt-4o-mini", api_key=os.getenv("OPENAI_API_KEY"))
+    model = Model.Almock()  # No API Key needed
     system_prompt = "You are a research assistant."
     budget = Budget(run=0.50)
 
@@ -212,7 +219,8 @@ from syrin import Agent, Model, Memory
 from syrin.enums import MemoryType
 
 agent = Agent(
-    model=Model.OpenAI("gpt-4o-mini", api_key=os.getenv("OPENAI_API_KEY")),
+    # model=Model.OpenAI("gpt-4o-mini", api_key=os.getenv("OPENAI_API_KEY")),
+    model=Model.Almock(),  # No API Key needed
     memory=Memory(types=[MemoryType.CORE, MemoryType.EPISODIC]),
 )
 
@@ -241,7 +249,8 @@ from syrin import Agent, Model, GuardrailChain
 from syrin.guardrails import LengthGuardrail, ContentFilter
 
 class SafeAgent(Agent):
-    model = Model.OpenAI("gpt-4o-mini", api_key=os.getenv("OPENAI_API_KEY"))
+    # model = Model.OpenAI("gpt-4o-mini", api_key=os.getenv("OPENAI_API_KEY"))
+    model = Model.Almock()  # No API Key needed
     guardrails = GuardrailChain([
         LengthGuardrail(max_length=4000),
         ContentFilter(blocked_words=["spam", "malicious"]),
@@ -269,7 +278,8 @@ from syrin import Agent, Model
 from syrin.context import Context
 
 agent = Agent(
-    model=Model.OpenAI("gpt-4o-mini", api_key=os.getenv("OPENAI_API_KEY")),
+    # model=Model.OpenAI("gpt-4o-mini", api_key=os.getenv("OPENAI_API_KEY")),
+    model=Model.Almock(),  # No API Key needed
     context=Context(max_tokens=8000),
 )
 
@@ -291,7 +301,8 @@ import os
 from syrin import Agent, Model, CheckpointConfig, CheckpointTrigger
 
 agent = Agent(
-    model=Model.OpenAI("gpt-4o-mini", api_key=os.getenv("OPENAI_API_KEY")),
+    # model=Model.OpenAI("gpt-4o-mini", api_key=os.getenv("OPENAI_API_KEY")),
+    model=Model.Almock(),  # No API Key needed
     checkpoint=CheckpointConfig(storage="memory", trigger=CheckpointTrigger.STEP),
 )
 
@@ -322,7 +333,8 @@ def search_web(query: str) -> str:
     return f"Results for: {query}"  # Replace with real search in production
 
 class Assistant(Agent):
-    model = Model.OpenAI("gpt-4o-mini", api_key=os.getenv("OPENAI_API_KEY"))
+    # model = Model.OpenAI("gpt-4o-mini", api_key=os.getenv("OPENAI_API_KEY"))
+    model = Model.Almock()  # No API Key needed
     tools = [search_web]
     budget = Budget(run=0.25)
 
@@ -345,7 +357,8 @@ import os
 from syrin import Agent, Model
 
 class Writer(Agent):
-    model = Model.OpenAI("gpt-4o-mini", api_key=os.getenv("OPENAI_API_KEY"))
+    # model = Model.OpenAI("gpt-4o-mini", api_key=os.getenv("OPENAI_API_KEY"))
+    model = Model.Almock()  # No API Key needed
 
 async def main():
     agent = Writer()

docs/README.md

@@ -91,7 +91,8 @@ Copy and run this to test your setup:
 from syrin import Agent, Model
 
 class MyAgent(Agent):
-    model = Model.OpenAI("gpt-4o-mini")
+    # model = Model.OpenAI("gpt-4o-mini")
+    model = Model.Almock()  # No API Key needed
     system_prompt = "You are helpful."
 
 agent = MyAgent()

docs/advanced-topics.md

@@ -21,6 +21,19 @@ The test suite in `tests/core_stability/` encodes these guarantees with TDD test
 
 ---
 
+## Loop strategy comparison
+
+| Strategy        | When to use it | Tool use | Typical flow |
+|----------------|----------------|----------|---------------|
+| **REACT**      | General agents that may call tools; one step per turn. | Yes | User → LLM → (tool calls or answer) → optional tool loop → final answer. |
+| **SINGLE_SHOT**| No tools; one prompt, one completion. | No | User → LLM → answer. |
+| **PLAN_EXECUTE**| Multi-step tasks: plan first, then execute steps. | Yes | User → plan → execute steps (each step can use tools). |
+| **CODE_ACTION**| Agent emits code or actions to run (e.g. sandbox). | Yes | User → LLM → code/actions → execute → optional loop. |
+
+All strategies return the same `LoopResult` shape (content, stop_reason, iterations, cost_usd, token_usage, tool_calls). Choose REACT for most agents with tools; SINGLE_SHOT when you have no tools; PLAN_EXECUTE for explicit planning; CODE_ACTION when the agent outputs code or structured actions.
+
+---
+
 ## Lifecycle Hooks
 
 Hooks let you execute code at specific moments during an agent's execution. This is essential for logging, metrics, authentication, and custom behaviors.
@@ -45,7 +58,8 @@ from Syrin.enums import Hook
 
 # Create agent
 agent = Agent(
-    model=Model.OpenAI("gpt-4o-mini"),
+    # model=Model.OpenAI("gpt-4o-mini"),
+    model=Model.Almock(),  # No API Key needed
     system_prompt="You are a helpful assistant.",
 )
 
@@ -71,7 +85,8 @@ from Syrin import Agent, Model
 from Syrin.enums import Hook
 
 agent = Agent(
-    model=Model.OpenAI("gpt-4o-mini"),
+    # model=Model.OpenAI("gpt-4o-mini"),
+    model=Model.Almock(),  # No API Key needed
     system_prompt="You are a helpful assistant.",
 )
 
@@ -206,7 +221,8 @@ for span in memory_exporter.spans:
 
 # Or enable debug mode on agent for automatic console output
 agent = Agent(
-    model=Model.OpenAI("gpt-4o-mini"),
+    # model=Model.OpenAI("gpt-4o-mini"),
+    model=Model.Almock(),  # No API Key needed
     debug=True,  # Enables trace output
 )
 ```
@@ -242,7 +258,8 @@ from Syrin.checkpoint import Checkpointer, CheckpointState
 checkpointer = Checkpointer()
 
 agent = Agent(
-    model=Model.OpenAI("gpt-4o-mini"),
+    # model=Model.OpenAI("gpt-4o-mini"),
+    model=Model.Almock(),  # No API Key needed
     system_prompt="You are a helpful assistant.",
 )
 
@@ -344,7 +361,8 @@ from Syrin.guardrails import ContentFilter, PIIScanner
 
 # Simple content filtering
 agent = Agent(
-    model=Model.OpenAI("gpt-4o"),
+    # model=Model.OpenAI("gpt-4o"),
+    model=Model.Almock(),  # No API Key needed
     guardrails=[
         ContentFilter(blocked_words=["password", "secret"]),
         PIIScanner(redact=True),
@@ -433,7 +451,8 @@ from Syrin import Agent, Model
 from Syrin.loop import SingleShotLoop
 
 agent = Agent(
-    model=Model.OpenAI("gpt-4o-mini"),
+    # model=Model.OpenAI("gpt-4o-mini"),
+    model=Model.Almock(),  # No API Key needed
     system_prompt="You are a helpful assistant.",
     loop=SingleShotLoop(),
 )
@@ -451,7 +470,8 @@ from Syrin import Agent, Model
 from Syrin.loop import ReactLoop
 
 agent = Agent(
-    model=Model.OpenAI("gpt-4o-mini"),
+    # model=Model.OpenAI("gpt-4o-mini"),
+    model=Model.Almock(),  # No API Key needed
     system_prompt="You are a helpful assistant.",
     loop=ReactLoop(),  # Default when tools are present
     tools=[my_tool],
@@ -473,7 +493,8 @@ async def approve_tool(tool_name: str, arguments: dict) -> bool:
     return response.lower() == 'y'
 
 agent = Agent(
-    model=Model.OpenAI("gpt-4o-mini"),
+    # model=Model.OpenAI("gpt-4o-mini"),
+    model=Model.Almock(),  # No API Key needed
     system_prompt="You are a helpful assistant.",
     loop=HumanInTheLoop(approve_tool),
     tools=[dangerous_tool],
@@ -490,7 +511,8 @@ The `PlanExecuteLoop` is a 3-phase loop that first generates a plan, then execut
 from Syrin.loop import PlanExecuteLoop
 
 agent = Agent(
-    model=Model.OpenAI("gpt-4o-mini"),
+    # model=Model.OpenAI("gpt-4o-mini"),
+    model=Model.Almock(),  # No API Key needed
     loop=PlanExecuteLoop(
         max_plan_iterations=3,      # Max iterations for planning
         max_execution_iterations=20,  # Max iterations for execution
@@ -510,7 +532,8 @@ The `CodeActionLoop` generates Python code, executes it, and interprets the resu
 from Syrin.loop import CodeActionLoop
 
 agent = Agent(
-    model=Model.OpenAI("gpt-4o-mini"),
+    # model=Model.OpenAI("gpt-4o-mini"),
+    model=Model.Almock(),  # No API Key needed
     loop=CodeActionLoop(
         max_iterations=5,       # Max code generation attempts
         timeout_seconds=30,     # Code execution timeout
@@ -545,7 +568,8 @@ class MyCustomLoop(Loop):
         )
 
 agent = Agent(
-    model=Model.OpenAI("gpt-4o-mini"),
+    # model=Model.OpenAI("gpt-4o-mini"),
+    model=Model.Almock(),  # No API Key needed
     loop=MyCustomLoop(),
 )
 ```
@@ -617,7 +641,8 @@ tracer = get_tracer()
 tracer.add_exporter(ConsoleExporter())
 
 agent = Agent(
-    model=Model.OpenAI("gpt-4o"),
+    # model=Model.OpenAI("gpt-4o"),
+    model=Model.Almock(),  # No API Key needed
     system_prompt="You are a professional customer support agent.",
     budget=budget,
     guardrails=guardrails,

docs/agent/README.md

@@ -7,11 +7,11 @@ Complete documentation for creating and configuring AI agents in Syrin. This dir
 ## Quick Start
 
 ```python
-from syrin import Agent
-from syrin.model import Model
+from syrin import Agent, Model
 
 agent = Agent(
-    model=Model.OpenAI("gpt-4o-mini"),
+    # model=Model.OpenAI("gpt-4o-mini"),
+    model=Model.Almock(),  # No API Key needed
     system_prompt="You are a helpful assistant.",
 )
 response = agent.response("Hello!")

docs/agent/constructor.md

@@ -43,9 +43,11 @@ LLM used by the agent.
 ```python
 from syrin.model import Model
 
-agent = Agent(model=Model.OpenAI("gpt-4o-mini"))
-agent = Agent(model=Model.Anthropic("claude-sonnet-4-5"))
-agent = Agent(model=Model.Ollama("llama3"))
+agent = Agent(
+    # model=Model.OpenAI("gpt-4o-mini"),
+    model=Model.Almock(),  # No API Key needed
+)
+# Or: Model.Anthropic("claude-sonnet-4-5"), Model.Ollama("llama3"), etc.
 ```
 
 Must be provided on the class or at construction. Raises `TypeError` if missing.
@@ -390,7 +392,8 @@ def search(query: str) -> str:
     return f"Results: {query}"
 
 agent = Agent(
-    model=Model.OpenAI("gpt-4o-mini"),
+    # model=Model.OpenAI("gpt-4o-mini"),
+    model=Model.Almock(),  # No API Key needed
     system_prompt="You are a research assistant.",
     tools=[search],
     budget=Budget(run=0.50),