Metadata-Version: 2.4
Name: aicf-core
Version: 0.6.2
Summary: AICF - Agent Infrastructure Cybernetics Framework: a scenario-agnostic agent engine (turn loop, tools, sqlite sessions, sub-agent collaboration)
Author-email: Jeffery Darkstar <ccjjfdyqlhy@outlook.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/ccjjfdyqlhy/aicf-core
Project-URL: Repository, https://github.com/ccjjfdyqlhy/aicf-core
Project-URL: Issues, https://github.com/ccjjfdyqlhy/aicf-core/issues
Keywords: agent,llm,tools,sessions,subagents,framework,agent-harness
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: openai>=1.0.0
Requires-Dist: requests>=2.28.0
Requires-Dist: PyYAML>=6.0
Requires-Dist: python-dotenv>=1.0.0
Provides-Extra: personality
Requires-Dist: PyYAML>=6.0; extra == "personality"
Provides-Extra: decisions
Provides-Extra: learning
Provides-Extra: finetune
Requires-Dist: torch>=2.0; extra == "finetune"
Provides-Extra: mcp
Requires-Dist: mcp>=1.2.0; extra == "mcp"
Provides-Extra: anthropic
Requires-Dist: anthropic>=1.0.0; extra == "anthropic"
Provides-Extra: socks
Requires-Dist: httpx[socks]>=0.24; extra == "socks"
Provides-Extra: full
Requires-Dist: flask>=3.0.0; extra == "full"
Requires-Dist: fastapi>=0.100; extra == "full"
Requires-Dist: uvicorn>=0.20; extra == "full"
Requires-Dist: numpy>=1.24.0; extra == "full"
Requires-Dist: cryptography>=40.0.0; extra == "full"
Requires-Dist: rich>=13.0.0; extra == "full"
Requires-Dist: psutil>=5.9; extra == "full"
Requires-Dist: opencv-python>=4.8; extra == "full"
Requires-Dist: mcp>=1.2.0; extra == "full"
Requires-Dist: anthropic>=1.0.0; extra == "full"
Provides-Extra: all
Requires-Dist: flask>=3.0.0; extra == "all"
Requires-Dist: fastapi>=0.100; extra == "all"
Requires-Dist: uvicorn>=0.20; extra == "all"
Requires-Dist: numpy>=1.24.0; extra == "all"
Requires-Dist: cryptography>=40.0.0; extra == "all"
Requires-Dist: rich>=13.0.0; extra == "all"
Requires-Dist: psutil>=5.9; extra == "all"
Requires-Dist: opencv-python>=4.8; extra == "all"
Requires-Dist: mcp>=1.2.0; extra == "all"
Requires-Dist: anthropic>=1.0.0; extra == "all"
Requires-Dist: torch>=2.0; extra == "all"
Dynamic: license-file

<div align="center">
<img src="docs/header.svg" width="1200" alt="aicf-core — the agent engine behind your local agent">
</div>

# 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](README.md) · [中文](README_zh.md) · [文档](docs/README.md)

![Python](https://img.shields.io/badge/Python-3.10%2B-3776AB?style=for-the-badge&logo=python&logoColor=white)
![Local First](https://img.shields.io/badge/local--first-100%25-8A2BE2?style=for-the-badge)
![License](https://img.shields.io/badge/license-Apache--2.0-blue?style=for-the-badge)

**AICF** = Agent Infrastructure Cybernetics Framework · Apache-2.0

---

## 📦 Install

```bash
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:

```bash
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.

```python
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

```python
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](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`](https://github.com/ccjjfdyqlhy/aicf-ui) | Web console — models, chat, resources, System-1 decisions |

It depends on `aicf-core` and nothing else.

---

## 🧪 Development

```bash
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](docs/architecture.md) |
| Use the core as a library | [docs/sdk_guide.md](docs/sdk_guide.md) |
| Go deeper into the agent loop / tools / context | [docs/harness.md](docs/harness.md) |
| Go deeper into model routing / resources / storage | [docs/infra.md](docs/infra.md) |
| Know which traps not to step into before changing code | [docs/maintenance.md](docs/maintenance.md) |
| Configuration keys / environment variables | [docs/configuration.md](docs/configuration.md) |
| Known tech debt and its fix priority | [docs/technical-debt.md](docs/technical-debt.md) |
| How the old monorepo maps onto the new repositories | [docs/split_migration.md](docs/split_migration.md) |

---

## 📄 License

Apache-2.0
