This release is a pre-release and may not be stable for production use.
aicf-core
The engine, not the app. A scenario-agnostic agent core: turn loop, tool protocol, context assembly, memory, sessions, multi-agent collaboration — and nothing else.
AICF = Agent Infrastructure Cybernetics Framework · Apache-2.0
One promise
Run one long task safely, idempotently, and measurably.
Most agent frameworks assume the process lives. This one assumes it will not.
| The claim | How you can check it | |
|---|---|---|
| Safe | Every tool call goes through a policy gate, an approval step when the tool has side effects, and a sandbox. Anything undecided is denied. | aicf tool exec proc.run --args '{"command":"rm -rf /"}' → refused |
| Idempotent | A crashed run can be resumed without repeating side effects. effectful calls are never auto-replayed. |
pytest tests/fault/ — real kill -9 in a subprocess |
| Measurable | Every run produces a trace; every change is scored against a dataset and stopped by a four-gate report. | aicf eval → aicf gate |
Ninety seconds
pip install aicf-core
# 1. What does each tool actually do? Effect level, sandbox tier, required scopes.
aicf tool list
# 2. Try to run a shell. It has side effects — so it waits for a human.
aicf tool exec proc.run --args '{"command":"rm -rf /"}' --policy strict
# Error: 工具 proc.run 被策略拒绝(approval):CLI 未开启 --yes
# 3. Run one turn. It leaves a trace.
aicf run "summarize this repo" --trace trace.jsonl
# 4. Score it against a dataset (shipped with the package).
aicf eval --dataset basic --traces trace.jsonl --out run.json
# 5. Stop the release if anything regressed, got too expensive, or broke a rule.
aicf gate --run run.json --out gate.json
No API key required for any of the above — it runs offline against a stub model.
Install
pip install aicf-core
That is the whole library — the agent kernel and the model/tool/runtime layer.
It has no application code and no UI: the web console lives in its own repository
(aicf-ui).
Optional extras, installed only when you need them:
pip install "aicf-core[personality]" # personality dynamics (PEV3)
pip install "aicf-core[decisions]" # System-1 decision head
pip install "aicf-core[learning]" # trajectory → dataset → judge → promotion loop
pip install "aicf-core[finetune]" # local SFT (pulls torch)
pip install "aicf-core[mcp]" # external MCP tool servers
pip install "aicf-core[all]" # everything
Just want to write an agent? Five symbols.
from harness import create_agent, tool # the three you write with
from harness.tools import ToolRegistry # when you manage tools yourself
from infra.models.base import IChatClient # the model interface
| Symbol | What it is |
|---|---|
tool |
turns a typed function into a tool (schema generated from the signature) |
Agent |
an agent bound to a client — chat() / run() / chat_stream() |
create_agent |
one-liner factory: model + key + tools |
ToolRegistry |
the tool table (only if you register them yourself) |
IChatClient |
the model interface — implement it to plug in your own backend |
from harness import create_agent, tool
@tool
def add(a: int, b: int) -> int:
"""Add two numbers."""
return a + b
agent = create_agent(
model="deepseek-chat",
base_url="https://api.deepseek.com/v1",
api_key="sk-...", # or just export OPENAI_API_KEY
tools=[add],
)
result = agent.run("what is 17 + 25?")
print(result) # the result is string-like
Any OpenAI-compatible endpoint works. For a local model, point base_url at your
llama-server / LM Studio, or hand create_agent a client
(infra.orchestrator.LlamaCppChat, LMStudioChat, OpenAICompatClient, …).
The repo in 30 seconds
Two layers, dependencies pointing downward only:
harness/ Agent core turn loop · tools · context · memory · pipeline · sessions · SDK
│ knows nothing about any product
▼
infra/ Infra model routing · resource pool · storage · gateway · auth · policy
apps/ → gone. The web console now lives in its own repository:
| Repository | What it is |
|---|---|
aicf-ui |
Web console — models, chat, resources, System-1 decisions |
It depends on aicf-core and nothing else.
Status
aicf-core is at 1.0.0rc0. The definition of done for rc0 is three
executable claims, and all three hold (each one is pinned to a test):
- an agent that is
kill -9'd once still resumes and produces the right answer; - every tool call was either approved or refused — with an audit trail;
- the run can be scored by a ≥30-case dataset and produce a four-gate report.
Those guarantees hold on the default paths. An agent built with
create_agent comes with a guard, proc.run executes inside a workspace
sandbox, and both the SDK and the CLI write the tool intents into the journal
— so after a crash the runtime can tell which side effects may already have
happened.
Next is rc1: the control plane (agent artifacts and their lifecycle), the workflow and planner kernels, and agent identity with delegation. The plan, the acceptance criteria and the status of each workstream live in docs/roadmap_1.0.0-rc0.md.
Development
git clone https://github.com/ccjjfdyqlhy/aicf-core.git && cd aicf-core
pip install -e ".[mcp,anthropic,socks]"
pip install pytest pytest-asyncio
python -m pytest -q tests/
Documentation
| I want to… | Read this |
|---|---|
| Know what 1.0.0-rc0 is doing and how it is verified | docs/roadmap_1.0.0-rc0.md |
| Learn the module map and dependency rules | docs/architecture.md |
| Understand the security model (deny-by-default, approval, sandbox, audit) | docs/security.md |
| Understand the managed runtime (journal, checkpoint, idempotency, recovery) | docs/runtime.md |
| Understand the evaluation loop (dataset, gates, run versions, regression) | docs/evaluation.md |
| Use the core as a library | docs/sdk_guide.md |
| Go deeper into the agent loop / tools / context | docs/harness.md |
| Go deeper into model routing / resources / storage | docs/infra.md |
| Know which traps not to step into before changing code | docs/maintenance.md |
| Configuration keys / environment variables | docs/configuration.md |
| Known tech debt and its fix priority | docs/technical-debt.md |
License
Apache-2.0
Metadata
Release files for aicf-core 1.0.0rc0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| aicf_core-1.0.0rc0.tar.gz | 764.5 kB | With provenance | Details for aicf_core-1.0.0rc0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| aicf_core-1.0.0rc0-py3-none-any.whl | Python 3 | none | any | Details for aicf_core-1.0.0rc0-py3-none-any.whl |
Total release size: 1.5 MB
Release files / aicf_core-1.0.0rc0.tar.gz
| Download URL | aicf_core-1.0.0rc0.tar.gz |
|---|---|
| Size | 764.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
24dda1301ebe7a49c7442d817e6218d228837f14fc87d25613b7fca0f0432b55
|
|
BLAKE2b-256 checksum How to use checksums |
6623f973db729f18b182e6be46c72a43833ad129ab8699269898027a8370d5b3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.
Transparency logRelease files / aicf_core-1.0.0rc0-py3-none-any.whl
| Download URL | aicf_core-1.0.0rc0-py3-none-any.whl |
|---|---|
| Size | 737.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
fbecc82ab01fc341308059f70ed9aa8ee40027554acedf5f241ccebc5fdb25eb
|
|
BLAKE2b-256 checksum How to use checksums |
51513cdaab94ea763d7a7d1ae020360dbff0c7737f5b2b261ffa14c0cfe90a76
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.
Transparency logSecurity for aicf-core 1.0.0rc0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for aicf_core-1.0.0rc0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.