Skip to main content
Change of provenance

The repository or configuration that created this release differ from a previous release. View details.

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.

English · 中文 · 文档

Python Local First License

AICF = Agent Infrastructure Cybernetics Framework · Apache-2.0


📦 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 (see below).

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

🧩 What you get

You need… Module
A turn loop that only depends on IChatClient + ToolRegistry harness.agent.loop
A tool protocol with ownership tracking, diff snapshots, MCP bridge harness.tools
Context assembly under a token budget, with compaction harness.context_assembly
Memory stores (in-memory / vector) behind a port protocol harness.memory
Sessions that survive a restart (sqlite + atomic transcripts) harness.transcript, infra.store
Sub-agent collaboration by mailbox, with depth and concurrency limits harness.agent.collab
Model routing across llama.cpp / LM Studio / OpenAI / Anthropic, with failover infra.orchestrator
VRAM-aware scheduling for local models (and ASR/TTS/decision models) infra.resources
Budgets, retries, token accounting, policy infra.policy
A structured event stream you can build traces on harness.agent.events

🧩 Just want to write an agent? Five symbols.

Most people only need these five. Everything else in harness exists for people building a platform on top of it.

from harness import Agent, 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

Everything else — harness.agent.*, harness.tools.standard, infra.* — is there for the people who need it, not for the people who just want an agent.

🚀 Sixty seconds

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, …) — see docs/sdk_guide.md.


🗺️ 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.


🧪 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
Learn the module map and dependency rules docs/architecture.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
How the old monorepo maps onto the new repositories docs/split_migration.md

📄 License

Apache-2.0

Metadata

Release files for aicf-core 0.6.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Change of provenance

The repository or configuration that created these release files differ from that of a previous release.

We recommend inspecting the repository and configuration before proceeding. View details.

Source distribution (sdist)

Source distribution for aicf-core 0.6.2
File Size Uploaded Provenance Actions
aicf_core-0.6.2.tar.gz 555.3 kB With provenance Details for aicf_core-0.6.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for aicf-core 0.6.2
File Interpreter ABI Platform Actions
aicf_core-0.6.2-py3-none-any.whl Python 3 none any Details for aicf_core-0.6.2-py3-none-any.whl

Total release size: 1.1 MB

Release files / aicf_core-0.6.2.tar.gz

Change of provenance

This file belongs to a release with changed provenance: the repository or configuration that created the release files differ from that of a previous release.

We recommend inspecting the repository and configuration before proceeding. View details.

Download URL aicf_core-0.6.2.tar.gz
Size 555.3 kB
Tags Source
SHA-256 checksum
How to use checksums
563ba261ba6cc38c62215cecd3c7de5411590786f60d74c9dc7e173ebac1a71b
BLAKE2b-256 checksum
How to use checksums
68ed9d1168bc7e4f09c62391ea53aba5246ffde6e6bb4f76f56e90f6a90ad350
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 18, 2026.

Transparency log

Release files / aicf_core-0.6.2-py3-none-any.whl

Change of provenance

This file belongs to a release with changed provenance: the repository or configuration that created the release files differ from that of a previous release.

We recommend inspecting the repository and configuration before proceeding. View details.

Download URL aicf_core-0.6.2-py3-none-any.whl
Size 540.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
a68e99cf418709eb834e5e4d543a07f75c02830d5ca6f76d5a63b1b4c00be24a
BLAKE2b-256 checksum
How to use checksums
f6e5354f78fec15e470842f7707ce3b41fdffff7482387d669b3eef0891efd9b
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 18, 2026.

Transparency log

Security for aicf-core 0.6.2

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.

Change of provenance

The repository and configuration that created this release differ from a previous release.

While this could reflect a routine change by the project maintainers, it may also indicate that the release files have been compromised.

Select from 2 files

Attestation for aicf_core-0.6.2.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 18, 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