OpenCE is a pluggable meta-framework for building closed-loop Context Engineering (CE) systems. It evolves the original community ACE reproduction into a toolkit that can sense → reason → evaluate → evolve its own strategies.
Classical RAG stacks are open loops: they fetch context once and immediately respond. OpenCE adds two missing pillars:
- Evaluation – automatically score every LLM response using domain-specific evaluators (ACE Reflector, RAGAS, etc.).
- Evolution – feed those evaluation signals into long-term memory/strategy modules (ACE Curator, adaptive RAG policies, …).
This creates a self-improving flywheel where every new interaction strengthens future contexts.
OpenCE standardizes five interfaces so that any CE system can be composed as Lego bricks:
| Pillar | Interface | Responsibility |
|---|---|---|
| Acquisition | IAcquirer | Perception layer (databases, web, LangChain retrievers). |
| Processing | IProcessor | Cleans, deduplicates, compresses, or reranks acquired knowledge. |
| Construction | IConstructor | Builds the final prompt/context bundle (few-shot selection, dynamic instructions). |
| Evaluation | IEvaluator | Scores LLM responses; outputs rich feedback signals. |
| Evolution | IEvolver | Consumes evaluation signals to update long-term strategies (playbooks, memories, knobs). |
Each pillar is defined in src/opence/interfaces/ (the soul), implemented natively in src/opence/components/ (the batteries), and can be connected to external ecosystems through src/opence/adapters/ (the glue).
src/
└── opence/
├── interfaces/ # Five pillar ABCs + canonical data models
├── components/ # Batteries-included implementations
│ ├── acquirers/ # Native file readers, etc.
│ ├── processors/ # Compressors, rerankers …
│ ├── constructors/ # Few-shot selectors
│ ├── evaluators/ # ACE reflector integrator
│ └── evolvers/ # ACE curator + playbook evolver
├── models/ # Client abstractions + providers (API, transformers, RWKV)
├── methods/ # Composite closed-loop recipes (ACE closed loop, ...)
├── adapters/ # LangChain/LlamaIndex adapters (thin wrappers)
├── core/ # LLM clients + ClosedLoopOrchestrator
└── ace/ # Original ACE reproduction (generator/reflector/curator/playbook)
Scripts in scripts/ show end-to-end examples, while tests/ cover the orchestrator, ACE wrappers, and the legacy adapters.
This repo is managed with uv. Typical workflow:
# Install deps
uv sync
# Run the test suite
uv run pytest
# Format/lint (optional if you add ruff/black)
uv run ruff checkAll code lives under src/, so editable installs (uv pip install -e .) just work if you prefer a global environment.
fromopence.coreimportClosedLoopOrchestrator, DummyLLMClientfromopence.componentsimport (
FileSystemAcquirer,
FewShotConstructor,
SimpleTruncationProcessor,
KeywordBoostReranker,
ACEReflectorEvaluator,
ACECuratorEvolver,
)
fromopence.methods.aceimportPlaybook, Reflector, Curatorfromopence.interfacesimportLLMRequestplaybook=Playbook()
reflector_llm=DummyLLMClient()
curator_llm=DummyLLMClient()
# Queue deterministic ACE role outputs (see tests for full mocks)# ...orchestrator=ClosedLoopOrchestrator(
llm=DummyLLMClient(),
acquirer=FileSystemAcquirer("docs"),
processors=[KeywordBoostReranker(["safety", "fire"]), SimpleTruncationProcessor()],
constructor=FewShotConstructor(),
evaluator=ACEReflectorEvaluator(Reflector(reflector_llm), playbook),
evolver=ACECuratorEvolver(Curator(curator_llm), playbook),
)
result=orchestrator.run(LLMRequest(question="How to investigate industrial fires?"))
print(result.evaluation.feedback)
print(playbook.as_prompt())Swap out any pillar with your own implementation (or a third-party adapter) to experiment with different CE strategies.
Many CE techniques require coordinated component bundles. The opence.methods package provides plug-and-play recipes, beginning with ACEClosedLoopMethod, which wires the ACE reflector/curator (evaluation + evolution) with any acquirer/processor/constructor you supply. Methods return fully configured ClosedLoopOrchestrator instances plus metadata, so higher-level runners or CLIs can let users pick --method ace.closed_loop and instantly inherit sensible defaults.
fromopenceimportDummyLLMClientfromopence.methodsimportACEClosedLoopMethodmethod=ACEClosedLoopMethod(
generator_llm=DummyLLMClient(),
reflector_llm=DummyLLMClient(),
curator_llm=DummyLLMClient(),
)
orchestrator=method.build().orchestratorMethodRegistry enables registering custom methods so downstream tooling can discover everything available in the toolkit.
opence.models now exposes a provider layer that unifies API-based models (OpenAIModelProvider), local transformers (TransformersModelProvider), RWKV weights (RWKVModelProvider), and deterministic test doubles (DummyModelProvider). Each provider yields an LLMClient; the ClosedLoopOrchestrator automatically accepts either a raw LLMClient or a provider instance, keeping execution uniform regardless of backend.
The original ACE reproduction now lives under opence.methods.ace. You still get:
OfflineAdapterandOnlineAdapterorchestration loops.Playbook,Generator,Reflector,Curator, and semantic deduplication utilities.- Example scripts (
scripts/run_local_adapter.py,scripts/run_questions.py) updated to importopence.methods.ace.
You can continue running the classic ACE training scripts:
uv run python scripts/run_local_adapter.py --model-path /path/to/modelThe new ACEReflectorEvaluator + ACECuratorEvolver bridge these components into the generic five-pillar orchestrator, so future CE techniques can co-exist with ACE’s evolution dynamics.
- v0.1 – Deliver the closed-loop skeleton (this refactor), document interfaces, publish ACE wrappers ✅
- v0.3 – Add more batteries (compression, dynamic few-shot, scoring adapters,
opence.contribregistry). - v0.5 – Provide benchmark packs + configuration-driven pipelines; ship LangChain/LlamaIndex adapters.
- v1.0 – Promote OpenCE to a community standard with deep OSS ecosystem integrations.
Contributions are welcome across research, engineering, evaluations, and docs. Join us in defining the future of Context Engineering!