{"id":44967748,"url":"https://github.com/amabito/veronica-core","last_synced_at":"2026-03-16T07:11:57.186Z","repository":{"id":338978834,"uuid":"1158931641","full_name":"amabito/veronica-core","owner":"amabito","description":"Runtime containment layer for LLM agents. Token budgets, concurrency gates, adversarial hardening. Zero dependencies.","archived":false,"fork":false,"pushed_at":"2026-03-08T07:00:49.000Z","size":2875,"stargazers_count":2,"open_issues_count":24,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-08T09:57:15.457Z","etag":null,"topics":["agents","ai","ai-safety","anthropic","budget-enforcement","cost-estimation","generative-ai","guardrails","langchain","llm","llmops","observability","openai","python","runtime-safety"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/veronica-core/","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/amabito.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":"docs/SECURITY_CLAIMS.md","support":null,"governance":null,"roadmap":"docs/ROADMAP.md","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-16T05:11:19.000Z","updated_at":"2026-03-08T07:00:52.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/amabito/veronica-core","commit_stats":null,"previous_names":["amabito/veronica-core"],"tags_count":76,"template":false,"template_full_name":null,"purl":"pkg:github/amabito/veronica-core","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amabito%2Fveronica-core","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amabito%2Fveronica-core/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amabito%2Fveronica-core/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amabito%2Fveronica-core/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/amabito","download_url":"https://codeload.github.com/amabito/veronica-core/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amabito%2Fveronica-core/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30463580,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-13T06:34:02.089Z","status":"ssl_error","status_checked_at":"2026-03-13T06:33:49.182Z","response_time":60,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: 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":["agents","ai","ai-safety","anthropic","budget-enforcement","cost-estimation","generative-ai","guardrails","langchain","llm","llmops","observability","openai","python","runtime-safety"],"created_at":"2026-02-18T15:02:13.845Z","updated_at":"2026-03-13T09:04:45.411Z","avatar_url":"https://github.com/amabito.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# VERONICA-core\n\n![PyPI](https://img.shields.io/pypi/v/veronica-core?label=PyPI\u0026cacheSeconds=60)\n![CI](https://img.shields.io/badge/tests-5766%20passing-brightgreen)\n![Coverage](https://img.shields.io/badge/coverage-94%25-brightgreen)\n![Python](https://img.shields.io/badge/python-3.10%2B-blue)\n![License](https://img.shields.io/badge/license-MIT-blue)\n\nStops LLM agent runs from burning money. Catches runaway retries, infinite agent loops, and surprise API bills before they happen.\n\nYour agent retries 3 times per layer. Three layers deep, that's 64 API calls from one user click. veronica-core enforces a hard budget across the entire run -- cost, steps, retries, timeouts -- and halts the call before it reaches the model.\n\n```bash\npip install veronica-core\n```\n\n```\n# 3-layer retry, no run-level cap:  up to 64 API calls per user action\n# 3-layer retry, with veronica-core: capped at 6 (example: max_retries_total=5)\n```\n\nNo required dependencies. Python 3.10+. Works with any LLM provider.\n\nContainment, not observability -- it doesn't inspect prompts or completions, it caps resource consumption.\n\nveronica-core is the enforcement kernel. [veronica](https://github.com/amabito/veronica-public) is the control plane (policy management, fleet coordination, dashboard).\n\n---\n\n## Quickstart\n\n```python\nfrom veronica_core import ExecutionContext, ExecutionConfig, WrapOptions\n\ndef simulated_llm_call(prompt: str) -\u003e str:\n    return f\"response to: {prompt}\"\n\nconfig = ExecutionConfig(\n    max_cost_usd=1.00,    # hard cost ceiling per chain\n    max_steps=50,         # hard step ceiling\n    max_retries_total=10,\n    timeout_ms=0,\n)\n\nwith ExecutionContext(config=config) as ctx:\n    for i in range(3):\n        decision = ctx.wrap_llm_call(\n            fn=lambda: simulated_llm_call(f\"prompt {i}\"),\n            options=WrapOptions(\n                operation_name=f\"generate_{i}\",\n                cost_estimate_hint=0.04,\n            ),\n        )\n        if decision.name == \"HALT\":\n            break\n\nsnap = ctx.get_graph_snapshot()\nprint(snap[\"aggregates\"])\n# {\"total_cost_usd\": 0.12, \"total_llm_calls\": 3, ...}\n```\n\nSDK-level injection (no per-call changes):\n\n```python\nfrom veronica_core.patch import patch_openai\nfrom veronica_core import veronica_guard\n\npatch_openai()\n\n@veronica_guard(max_cost_usd=1.0, max_steps=20)\ndef run_agent(prompt: str) -\u003e str:\n    from openai import OpenAI\n    return OpenAI().chat.completions.create(\n        model=\"gpt-4o-mini\",\n        messages=[{\"role\": \"user\", \"content\": prompt}],\n    ).choices[0].message.content\n```\n\n---\n\n## Features\n\n- **Budget enforcement** -- hard cost ceiling per chain, HALT before the call\n- **Step limits** -- bounded recursion depth per entity\n- **Circuit breaker** -- per-entity failure counting with COOLDOWN state (local and Redis-backed)\n- **Token budget** -- cumulative output/total token ceiling with DEGRADE zone\n- **Retry containment** -- amplification control with jitter and backoff\n- **Semantic loop detection** -- word-level Jaccard similarity, no ML dependencies\n- **Execution graph** -- typed node lifecycle, amplification metrics\n- **Degradation ladder** -- 4-tier graceful degradation (model_downgrade, context_trim, rate_limit, halt)\n- **Two-phase budget** -- reserve/commit prevents double-spending across concurrent calls\n- **Security containment** -- PolicyEngine, AuditLog, ed25519 signing, red-team regression suite\n- **MCP containment** -- sync and async MCP server adapters with per-tool budget enforcement\n- **Declarative policy** -- YAML/JSON policy files with hot-reload, 7 builtin rule types\n\nNo required dependencies. Works with any LLM provider.\n\nFull feature list: [docs/FEATURES.md](docs/FEATURES.md)\n\n---\n\n## Integrations\n\n| Framework | Adapter | Example |\n|-----------|---------|---------|\n| OpenAI SDK | `patch_openai()` | [examples/integrations/openai_sdk/](examples/integrations/openai_sdk/) |\n| Anthropic SDK | `patch_anthropic()` | -- |\n| LangChain | `VeronicaCallbackHandler` | [examples/integrations/langchain/](examples/integrations/langchain/) |\n| AG2 (AutoGen) | `CircuitBreakerCapability` | [examples/ag2_circuit_breaker.py](examples/ag2_circuit_breaker.py) |\n| LlamaIndex | `VeronicaLlamaIndexHandler` | -- |\n| CrewAI | `VeronicaCrewAIListener` | [examples/integrations/crewai/](examples/integrations/crewai/) |\n| LangGraph | `VeronicaLangGraphCallback` | [examples/langgraph_minimal.py](examples/langgraph_minimal.py) |\n| ASGI/WSGI | `VeronicaASGIMiddleware` | [docs/middleware.md](docs/middleware.md) |\n| MCP | `MCPContainmentAdapter` | -- |\n| ROS2 | `SafetyMonitor` | [examples/ros2/](examples/ros2/) |\n\nAG2 integration via `AgentCapability`: [PR #2430](https://github.com/ag2ai/ag2/pull/2430) (merged)\n\n---\n\n## Examples\n\n| File | Description |\n|------|-------------|\n| [basic_usage.py](examples/basic_usage.py) | Budget enforcement and step limits |\n| [execution_context_demo.py](examples/execution_context_demo.py) | Step limit, budget, abort, circuit, divergence |\n| [adaptive_demo.py](examples/adaptive_demo.py) | Adaptive ceiling, cooldown, anomaly, replay |\n| [ag2_circuit_breaker.py](examples/ag2_circuit_breaker.py) | AG2 agent-level circuit breaker |\n| [langchain_minimal.py](examples/langchain_minimal.py) | LangChain integration quickstart |\n| [langgraph_minimal.py](examples/langgraph_minimal.py) | LangGraph integration quickstart |\n\n---\n\n## Architecture\n\n![Architecture overview](docs/diagrams/architecture-overview.svg)\n\nEach call passes through a `ShieldPipeline` of registered hooks. Any hook may emit `DEGRADE` or `HALT`. A `HALT` blocks the call and emits a `SafetyEvent`. veronica-core enforces that the evaluation occurs and the call does not proceed past `HALT`.\n\nveronica-core does not schedule, route, or orchestrate agents. Policy management and fleet coordination belong to [veronica](https://github.com/amabito/veronica).\n\nDetails: [docs/architecture.md](docs/architecture.md) -- includes [supporting systems](docs/diagrams/supporting-systems.svg) and [evaluation flow](docs/diagrams/shield-pipeline-flow.svg) diagrams.\n\n---\n\n## Security\n\nProcess-boundary policy enforcement. 20-scenario red-team regression suite covering exfiltration, credential hunt, workflow poisoning, and persistence attacks. 4 rounds of independent security audit (130+ findings fixed).\n\nDetails: [docs/SECURITY_CONTAINMENT_PLAN.md](docs/SECURITY_CONTAINMENT_PLAN.md) | [docs/THREAT_MODEL.md](docs/THREAT_MODEL.md)\n\n---\n\n## Stats\n\n5766 tests, 94% coverage, zero required dependencies. Zero breaking changes from v2.1.0 through v3.7.3. Python 3.10+.\n\nEvaluation: [docs/EVALUATION.md](docs/EVALUATION.md) | [CHANGELOG.md](CHANGELOG.md)\n\n---\n\n## Install\n\n```bash\npip install veronica-core\n```\n\nOptional extras:\n\n```bash\npip install veronica-core[redis]   # DistributedCircuitBreaker, RedisBudgetBackend\npip install veronica-core[otel]    # OpenTelemetry export\npip install veronica-core[vault]   # VaultKeyProvider (HashiCorp Vault)\n```\n\nDevelopment:\n\n```bash\ngit clone https://github.com/amabito/veronica-core\ncd veronica-core\npip install -e \".[dev]\"\npytest\n```\n\n---\n\n## Roadmap\n\nv4.0 Federation (multi-process policy coordination) is the next milestone. No timeline commitment -- veronica-core is stable at v3.7.3.\n\nFull roadmap: [docs/ROADMAP.md](docs/ROADMAP.md)\n\n---\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famabito%2Fveronica-core","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Famabito%2Fveronica-core","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famabito%2Fveronica-core/lists"}