Skip to main content
Pre-release

This release is a pre-release and may not be stable for production use.

aicf-core — the agent engine behind your local agent

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

Python Local First License CI


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):

  1. an agent that is kill -9'd once still resumes and produces the right answer;
  2. every tool call was either approved or refused — with an audit trail;
  3. 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)

Source distribution for aicf-core 1.0.0rc0
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)

Table of built distributions (wheels) for aicf-core 1.0.0rc0
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page