{"id":49003216,"url":"https://github.com/yangfei222666-9/self-improving-loop","last_synced_at":"2026-04-25T16:01:18.708Z","repository":{"id":342537414,"uuid":"1165572129","full_name":"yangfei222666-9/self-improving-loop","owner":"yangfei222666-9","description":"Safety-first self-improvement loop for AI agents — auto-rollback on regression, pure stdlib, MIT","archived":false,"fork":false,"pushed_at":"2026-04-17T11:02:44.000Z","size":26,"stargazers_count":0,"open_issues_count":8,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-17T13:09:30.652Z","etag":null,"topics":["agent-evolution","ai-agents","auto-rollback","autonomous-agents","feedback-loop","llm-tooling","python","self-improving","taijios"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/yangfei222666-9.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-24T10:03:42.000Z","updated_at":"2026-04-17T11:02:47.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/yangfei222666-9/self-improving-loop","commit_stats":null,"previous_names":["yangfei222666-9/self-improving-loop"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/yangfei222666-9/self-improving-loop","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yangfei222666-9%2Fself-improving-loop","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yangfei222666-9%2Fself-improving-loop/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yangfei222666-9%2Fself-improving-loop/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yangfei222666-9%2Fself-improving-loop/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yangfei222666-9","download_url":"https://codeload.github.com/yangfei222666-9/self-improving-loop/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yangfei222666-9%2Fself-improving-loop/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31980845,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-18T17:30:12.329Z","status":"ssl_error","status_checked_at":"2026-04-18T17:29:59.069Z","response_time":103,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-evolution","ai-agents","auto-rollback","autonomous-agents","feedback-loop","llm-tooling","python","self-improving","taijios"],"created_at":"2026-04-18T19:07:31.181Z","updated_at":"2026-04-25T16:01:18.695Z","avatar_url":"https://github.com/yangfei222666-9.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# self-improving-loop\n\n\u003e A hexagram-guided reliability loop for AI agents:\n\u003e **trace → six lines → hexagram policy → guarded patch → rollback on regression.**\n\n[![GitHub Release](https://img.shields.io/github/v/release/yangfei222666-9/self-improving-loop?display_name=tag)](https://github.com/yangfei222666-9/self-improving-loop/releases/tag/v0.1.1)\n[![CI](https://github.com/yangfei222666-9/self-improving-loop/actions/workflows/ci.yml/badge.svg)](https://github.com/yangfei222666-9/self-improving-loop/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![Python](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org/)\n[![LLM overhead](https://img.shields.io/badge/LLM%20overhead-%3C1%25-brightgreen)](#performance)\n\nLatest verified release: [v0.1.1](https://github.com/yangfei222666-9/self-improving-loop/releases/tag/v0.1.1) · Launch copy: [English + 中文](LAUNCH_COPY_BILINGUAL.md)\n\nMost \"self-improving agent\" projects stop at *\"log the failures, let the next run read the log\"*. That's a methodology, not a loop. **This package is the loop, implemented as a compact pure-stdlib Python runtime** — no framework lock-in, no LLM dependency, no cloud.\n\nThe differentiator is the optional Yijing strategy: runtime signals are mapped\ninto six engineering lines, recognized as a hexagram state, converted into a\nbounded policy patch, then verified through the same rollback guard as any\nother strategy. It is a state machine, not fortune telling.\n\nOverhead is negligible for normal LLM/HTTP agent calls; for sub-10ms in-memory functions, measure before wrapping.\n\nWrap any function, get:\n\n- 📊 **Automatic execution tracking** (success rate, latency, rolling window)\n- 🗄 **Trace storage choice**: readable JSONL by default, SQLite/WAL for multi-worker deployments\n- 🧠 **Adaptive thresholds** per agent profile (high-freq / mid-freq / low-freq / critical)\n- ☯️ **Optional hexagram state strategy**: six runtime dimensions → policy patch\n- 🛠 **Strategy hook** for proposing improvement configs when failure patterns are detected\n- 🧩 **ConfigAdapter contract** for real config backup / patch / restore\n- 🛡 **Rollback trigger** when the new config regresses (\u003e10% success drop, \u003e20% latency gain, or 5 consecutive failures)\n- 📬 **Pluggable notifier** (stub by default — swap in Telegram / Slack / whatever)\n\nExtracted from [**TaijiOS**](https://github.com/yangfei222666-9/taiji), where the same six-line state model is used for production-scale agent workloads.\n\n![self-improving-loop terminal demo](assets/demo/self_improving_loop_demo.svg)\n\nDemo artifacts: [terminal transcript](assets/demo/self_improving_loop_demo.txt) · [asciinema cast](assets/demo/self_improving_loop_demo.cast)\n\n---\n\n## Install\n\nLatest verified GitHub release:\n\n```bash\npip install https://github.com/yangfei222666-9/self-improving-loop/releases/download/v0.1.1/self_improving_loop-0.1.1-py3-none-any.whl\n```\n\nFrom source:\n\n```bash\npip install git+https://github.com/yangfei222666-9/self-improving-loop.git@v0.1.1\n```\n\nZero required dependencies. Everything is Python stdlib, including optional\nSQLite trace storage via `sqlite3`.\n\n---\n\n## Not a...\n\n- **...methodology doc.** Many \"self-improving agent\" repos are markdown templates that ask *you* to log learnings to `CLAUDE.md`. This is the runtime loop that does it for you.\n- **...heavyweight framework.** Compact stdlib code. Drop it next to your existing code. No decorators forced on you. No background process.\n- **...LLM-dependent.** The analysis is statistical, not LLM-based. If you want LLM-authored config tweaks, pass an `improvement_strategy` object and ask your favorite LLM inside its `analyze()` method.\n\n---\n\n## What is stable today\n\nStable:\n\n- Execution tracking\n- Adaptive failure thresholds\n- JSONL trace storage with a cross-process lock\n- Optional SQLite/WAL trace storage\n- Strategy-triggered config patching\n- ConfigAdapter-backed rollback when a patch regresses\n- Optional Yijing hexagram strategy as a deterministic state router:\n  runtime traces -\u003e six engineering lines -\u003e hexagram -\u003e bounded policy patch\n\nExperimental:\n\n- Choosing the best config patch automatically. The loop calls your\n  `improvement_strategy`; it does not pretend to know your agent better than\n  your production tests.\n- Full 64-hexagram policy coverage. The first Yijing strategy supports only\n  eight core states and should be treated as a bounded policy router.\n\n---\n\n## 30-second example\n\n```python\nfrom self_improving_loop import SelfImprovingLoop\n\nloop = SelfImprovingLoop()\n\ndef my_agent_work():\n    # Your actual agent call / LLM chain / tool invocation\n    return {\"status\": \"ok\", \"data\": ...}\n\nresult = loop.execute_with_improvement(\n    agent_id=\"my-agent\",\n    task=\"handle user query\",\n    execute_fn=my_agent_work,\n)\n\nif result[\"improvement_triggered\"]:\n    print(f\"Strategy applied {result['improvement_applied']} config tweaks\")\n\nif result[\"rollback_executed\"]:\n    print(f\"Rolled back because: {result['rollback_executed']['reason']}\")\n```\n\nThat's it. The loop watches every execution and decides when to trigger tuning.\nTo mutate and restore real agent config, provide a strategy hook plus either a\n`ConfigAdapter` or the legacy strategy `current_config/apply/rollback` methods.\n\n---\n\n## Run the four useful examples\n\nFrom a repo checkout, start here:\n\n```bash\npython examples/01_basic_tracking.py\npython examples/02_config_rollback.py\npython examples/03_langgraph_adapter.py\npython examples/04_yijing_strategy.py\n```\n\nThey prove the four important contracts:\n\n- `01_basic_tracking.py`: wrapper records traces and exposes stats.\n- `02_config_rollback.py`: a bad patch is applied, regression is detected, and `ConfigAdapter.rollback_config()` restores the previous config.\n- `03_langgraph_adapter.py`: a LangGraph-style node can be wrapped without adopting a new framework.\n- `04_yijing_strategy.py`: traces become six runtime lines, a hexagram state, and a bounded policy patch.\n\nFor the verbose rollback event trail, run:\n\n```bash\npython examples/regression_rollback_demo.py\n```\n\n---\n\n## Use it as a safety layer for your current agent\n\nThis package is not trying to replace LangGraph, CrewAI, AutoGen, OpenAI\nAgents, or your own internal runner. It wraps the callable you already trust:\n\n```python\nresult = loop.execute_with_improvement(\n    agent_id=\"support-agent\",\n    task=\"answer ticket\",\n    execute_fn=lambda: existing_agent.run(ticket),\n    context={\"framework\": \"your-current-stack\"},\n)\n```\n\n`loop.track(...)` is also available as a shorter alias for the same API.\n\nDependency-free examples show the integration seam:\n\n```bash\npython examples/03_langgraph_adapter.py\npython examples/wrap_existing_agent.py\n```\n\nThe goal is narrow: traces, thresholds, guarded strategy application, and\nrollback evidence around an agent you already have.\n\n---\n\n## Trace storage\n\nBy default, traces are written to a readable `traces.jsonl` file with a\ncross-platform sidecar lock. For multi-worker deployments, switch to SQLite:\n\n```python\nfrom self_improving_loop import SelfImprovingLoop\n\nloop = SelfImprovingLoop(storage=\"sqlite\")\n```\n\nThis writes `traces.sqlite3` with WAL mode enabled. The public API is unchanged:\n`execute_with_improvement()` records traces, and the loop reads them back for\nthresholds, metrics, and rollback checks.\n\n---\n\n## Optional Yijing policy strategy\n\nThe Yijing layer is implemented as a deterministic state machine, not as a\nfortune-telling layer:\n\n`runtime traces -\u003e six engineering lines -\u003e hexagram state -\u003e policy patch`\n\nThe six lines are:\n\n1. stability\n2. efficiency\n3. learning activity\n4. routing accuracy\n5. collaboration\n6. governance\n\nUse it as the strategy:\n\n```python\nfrom self_improving_loop import SelfImprovingLoop, YijingEvolutionStrategy\n\nloop = SelfImprovingLoop(\n    strategy=YijingEvolutionStrategy(),\n    config_adapter=my_config_adapter,\n)\n```\n\n`improvement_strategy=` remains supported for backward compatibility.\n\nThe engineering mapping is explicit:\n\n| Line | Dimension | Yang means | Yin means |\n|---|---|---|---|\n| 1 | stability | dependencies are healthy | API/network/dependency failure |\n| 2 | efficiency | high success, low latency | low success or high latency |\n| 3 | learning activity | feedback / recovery signal exists | repeated failure without learning |\n| 4 | routing accuracy | model/tool choice looks correct | wrong model/tool/schema drift |\n| 5 | collaboration | tools / agents hand off cleanly | conflicts or context breaks |\n| 6 | governance | cost and rollout are bounded | quota, cost, or policy drift |\n\nThe first version supports eight core policy states: Qian, Kun, Zhen, Kan, Bo,\nFu, Ji Ji, and Wei Ji. It returns a bounded config patch and relies on the same\ncanary/rollback path as any other strategy.\n\n---\n\n## Why this exists\n\nMost agents have this failure mode:\n\n1. You ship an agent.\n2. It works for a week.\n3. Something upstream changes (rate limits, schema drift, a new edge case).\n4. Your agent starts failing.\n5. You find out three days later from angry users.\n6. You tweak a config, hope for the best, ship it.\n7. The tweak makes another scenario worse.\n8. You roll it back manually, losing the original learning.\n\n`self-improving-loop` turns steps 3–8 into a tight feedback loop that runs inside your process, without needing observability infra, Kubernetes, or a dedicated ML team.\n\n---\n\n## Adaptive thresholds (no magic numbers)\n\nDifferent agents have different \"pulse rates\". A critical alerting agent should reconsider after 1 failure; a batch classifier can tolerate 5 before triggering analysis. The library classifies agents by execution frequency and adjusts:\n\nThe automatic profile is based on `exec_count_24h`; override it with `set_manual_threshold()` when production semantics matter more than raw frequency.\n\n| Agent profile | Failure trigger | Analysis window | Cooldown |\n|---|---|---|---|\n| High-frequency (\u003e10/day) | 5 failures | 48h | 3h |\n| Medium-frequency (3-10/day) | 3 failures | 24h | 6h |\n| Low-frequency (\u003c3/day) | 2 failures | 72h | 12h |\n| Critical (user-marked) | 1 failure | 24h | 6h |\n\nOr bypass the classifier and set manually:\n\n```python\nfrom self_improving_loop import AdaptiveThreshold\n\nadaptive = AdaptiveThreshold()\nadaptive.set_manual_threshold(\n    \"critical-agent\",\n    failure_threshold=1,\n    analysis_window_hours=12,\n    cooldown_hours=1,\n    is_critical=True,\n)\n```\n\n---\n\n## Auto-rollback (the safety net)\n\nWhen a config change ships, the loop keeps watching. It rolls back if **any** of these become true:\n\n- Success rate drops \u003e10%\n- Average latency increases \u003e20%\n- ≥5 consecutive failures after the change\n\nReal rollback requires a config hook. Prefer an explicit `ConfigAdapter`:\n\n```python\nfrom self_improving_loop import SelfImprovingLoop\n\nclass MyConfigAdapter:\n    def get_config(self, agent_id):\n        return load_agent_config(agent_id)\n\n    def apply_config(self, agent_id, config_patch):\n        save_agent_config(agent_id, {**load_agent_config(agent_id), **config_patch})\n        return True\n\n    def rollback_config(self, agent_id, backup_config):\n        save_agent_config(agent_id, backup_config)\n\nloop = SelfImprovingLoop(\n    improvement_strategy=my_strategy,\n    config_adapter=MyConfigAdapter(),\n)\n```\n\nWithout a config adapter or strategy rollback hook, the loop will record the\nrollback decision but will not claim that your external agent config was\nrestored.\n\n```python\n# See recent rollbacks\nrollback_history = loop.auto_rollback.get_rollback_history(\"my-agent\")\nfor event in rollback_history:\n    print(event[\"reason\"], event[\"timestamp\"])\n```\n\n---\n\n## Pluggable notifier\n\nThe built-in `TelegramNotifier` is a stub — it logs to stdout. Override `_send_message()` to hook any channel:\n\n```python\nfrom self_improving_loop import TelegramNotifier\n\nclass MySlackNotifier(TelegramNotifier):\n    def __init__(self, webhook_url, **kw):\n        super().__init__(**kw)\n        self.webhook_url = webhook_url\n\n    def _send_message(self, message, priority=\"normal\"):\n        import requests\n        requests.post(self.webhook_url, json={\"text\": f\"[{priority}] {message}\"})\n\nloop = SelfImprovingLoop(notifier=MySlackNotifier(webhook_url=\"https://hooks...\"))\n```\n\n---\n\n## Performance\n\nMeasured locally with `benchmarks/overhead.py` (200 iterations per workload, Python 3.12, Windows):\n\n| Workload profile | Absolute overhead | Relative overhead |\n|---|---|---|\n| ~100 ms agent call (typical LLM) | +0.27 ms | **+0.3%** |\n| ~10 ms agent call (tool call) | +0.31 ms | **+3.0%** |\n| sub-millisecond call | +0.08 ms | \u003e\u003e% (don't wrap these) |\n\nThe wrapper adds a stable **~300 μs of fixed cost per call** (trace append + threshold check). Whether that's negligible depends on your workload:\n\n- LLM calls (\u003e500 ms): overhead is ≤0.06% — invisible\n- HTTP / DB calls (~30-100 ms): ≤1%\n- Fast in-memory work (\u003c10 ms): 3%+ — reconsider whether you need this for those\n\nRerun the benchmark on your own machine with `python benchmarks/overhead.py`.\n\nSeparate operation costs (triggered occasionally, not per-call):\n\n| Operation | Cost |\n|---|---|\n| Failure analysis (only when threshold crossed) | ~100 ms |\n| Applying improvement config | ~200 ms |\n| Rollback execution | ~10 ms |\n\n---\n\n## Background\n\nExtracted from [**TaijiOS**](https://github.com/yangfei222666-9/taiji) — a self-learning AI operating system with 5 *I Ching*–bound engines and a 346-heartbeat Ising physics experiment. The parent project has 14 modules; this one is the most generally reusable, so it lives as a standalone package.\n\nTaijiOS started on **Chinese New Year 2026-02-17** and has been built through multi-AI collaboration since then.\n\n---\n\n## License\n\nMIT. Ship it wherever.\n\n## Contact / Feedback\n\nThis is a very early release. Every bug report, every \"didn't work for me\", every \"I wish it did X\" is read:\n\n- GitHub Issue: [open one](https://github.com/yangfei222666-9/self-improving-loop/issues/new)\n- Parent project: [TaijiOS](https://github.com/yangfei222666-9/taiji)\n\n---\n\n*\"Safety first, then automation.\"*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyangfei222666-9%2Fself-improving-loop","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyangfei222666-9%2Fself-improving-loop","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyangfei222666-9%2Fself-improving-loop/lists"}