Metadata-Version: 2.4
Name: neuron-engine
Version: 3.0.4
Summary: 类脑神经元全域智能体引擎 SDK — 基于五层神经圈层架构的通用AI Agent框架 (V2.8稳态增强版)
Author-email: liangjie_deng <liangjie_deng@163.com>
Maintainer-email: 合肥极美景行商贸有限公司「若曦」项目组 <liangjie_deng@163.com>
License-Expression: MIT
Keywords: neuron,brain-inspired,ai-agent,cognitive-architecture,stdp,lif-model,mcp-server
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Framework :: AsyncIO
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: api
Provides-Extra: postgres
Requires-Dist: psycopg2-binary>=2.9.9; extra == "postgres"
Provides-Extra: dev
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
Provides-Extra: all
Requires-Dist: neuron-engine[api,dev,postgres]; extra == "all"
Dynamic: license-file

# Neuron Engine SDK v3.0

> 类脑神经元全域智能体引擎 — 基于五层神经圈层架构的通用AI Agent框架

## 架构概览

```
┌─────────────────────────────────────────────────────┐
│                  决策层 (Decision)                    │
│         决策融合 · 多巴胺奖励 · RPE预测误差           │
├─────────────────────────────────────────────────────┤
│                  调度层 (Schedule)                    │
│       规则互斥 · 优先级 · 限流 · 全局调控            │
├─────────────────────────────────────────────────────┤
│                  能力层 (Skill)                       │
│       技能管理 · STDP学习 · 突触可塑性                │
├─────────────────────────────────────────────────────┤
│                  认知层 (Cognition)                   │
│       语义解析 · 情景记忆 · 程序记忆 · 知识库        │
├─────────────────────────────────────────────────────┤
│                  感知层 (Perception)                  │
│       信号采集 · 三分类协议 · 噪声过滤               │
└─────────────────────────────────────────────────────┘
```

## 核心特性

- **LIF膜电位模型** — 离散近似 `V(t+1) = λ·V(t) + (1-λ)·I_syn(t)`
- **三分类信号协议** — 兴奋 / 抑制 / 调控（调控走旁路不触发点火）
- **STDP脉冲时序可塑性** — Bi&Poo 1998 生物参数 (A+=0.08, A-=0.04)
- **四级层级记忆** — temp → short_term → long_term → permanent
- **全局调控系统** — 四维状态(觉醒/注意/学习/稳定) + 大五人格 + VAD情绪
- **三态熔断机制** — 关闭 → 打开 → 半开，60秒冷却
- **10步闭环工作流** — Bootstrap → 感知 → 认知 → 能力 → 调控 → 调度 → 执行 → 决策 → 奖励 → 演化
- **零外部依赖** — 纯Python标准库实现，可选PostgreSQL后端

## 快速开始

### 安装

```bash
cd neuron-engine
pip install -e ".[dev]"
```

### 基础使用

```python
from neuron_engine.workflow import NeuronEngine
from neuron_engine.core.signal import Signal

# 创建引擎
engine = NeuronEngine()

# 注册神经元 + 技能
def my_skill(neuron, **kwargs):
    task_input = kwargs.get("task_input", "")
    return {"output": f"Processed: {task_input}"}

nid = engine.register_neuron(
    neuron_type="skill",
    domain_tag="demo",
    executor=my_skill,
    description="示例技能"
)

# 执行任务 (10步闭环)
result = engine.execute_task("Hello Neuron Engine")
print(result)
```

### 信号系统

```python
from neuron_engine.core.signal import Signal, SignalType, ModulationType

# 兴奋信号
exc = Signal.create_excitation(source_id="N-01", intensity=0.8, priority=5)

# 抑制信号
inh = Signal.create_inhibition(source_id="N-02", intensity=0.6)

# 调控信号（多巴胺/NE/ACh/5-HT/组胺）
mod = Signal.create_modulation(
    source_id="G1",
    modulation_type=ModulationType.DOPAMINE,
    intensity=0.7
)
```

### STDP学习

```python
from neuron_engine.learning import STDPLearner, RPEEvaluator
from neuron_engine.core.synapse import Synapse

learner = STDPLearner()
synapse = Synapse(source_id="N-01", target_id="N-02", weight=0.5)

# pre-before-post: 权重增强
learner.update_single(synapse, delta_t=-100, learning_rate=1.0)
print(f"Weight: {synapse.weight:.4f}")  # > 0.5

# RPE奖励评估
evaluator = RPEEvaluator()
quality = evaluator.evaluate_quality({
    "completeness": 0.9,
    "success_rate": 0.8,
    "latency_ms": 200,
    "user_feedback": 0.7,
})
rpe = evaluator.calc_rpe(quality, expected_value=0.5)
print(f"Quality: {quality:.3f}, RPE: {rpe:+.3f}")
```

### 记忆系统

```python
from neuron_engine.memory import MemoryManager

mgr = MemoryManager()

# 存储记忆
atom = mgr.store("重要知识点", domain_tag="AI", keywords=["深度学习"])
atom.access()  # 记录访问
atom.access()

# 搜索记忆
results = mgr.search(domain_tag="AI", keyword="深度学习")

# 记忆巩固
mgr.consolidate(atom.atom_id)
```

### 全局调控

```python
from neuron_engine.governance import GovernanceSystem

gov = GovernanceSystem()

# 调节四维状态
gov.global_state.update(arousal=0.8, learning_mode=0.7)
gov.infer_mode()  # 自动推断运行模式

# 三维协同向量
synergy = gov.calc_synergy_vector()
print(synergy)
```

### 数据库持久化

```python
from neuron_engine.db import NeuronDB, NeuronRow, SynapseRow, MemoryAtomRow

# SQLite (默认)
db = NeuronDB("neurons.db")

# PostgreSQL (生产)
# db = NeuronDB("postgresql://user:pass@host/db")

# 创建神经元
db.insert_neuron(NeuronRow(
    neuron_id="N-001",
    neuron_type="skill",
    domain_tag="NLP",
    description="文本分析"
))

# 创建突触
db.insert_synapse(SynapseRow(
    source_id="N-001", target_id="N-002",
    weight=0.7, signal_type="excitation"
))

# 查看统计
print(db.get_stats())
```

### REST API

```python
from neuron_engine.workflow import NeuronEngine
from neuron_engine.db import NeuronDB
from neuron_engine.api import NeuronAPIServer

engine = NeuronEngine(db=NeuronDB("neurons.db"))
server = NeuronAPIServer(engine, engine.db, host="0.0.0.0", port=8100)
server.start()  # 阻塞启动
# server.start(blocking=False)  # 后台启动
```

**API端点：**

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/health` | 健康检查 |
| GET | `/neurons` | 列出神经元 |
| POST | `/neurons` | 创建神经元 |
| GET | `/neurons/{id}` | 获取神经元 |
| POST | `/neurons/{id}/activate` | 激活神经元 |
| GET | `/synapses` | 列出突触 |
| POST | `/synapses` | 创建突触 |
| PUT | `/synapses/{src}/{tgt}/weight` | 更新权重 |
| GET | `/memories` | 搜索记忆 |
| POST | `/memories` | 创建记忆 |
| POST | `/memories/{id}/promote` | 晋升记忆 |
| POST | `/tasks/execute` | 执行任务 |
| GET | `/governance/state` | 调控状态 |
| GET | `/governance/personality` | 人格特征 |
| GET | `/governance/emotion` | 情绪状态 |
| GET | `/config` | 获取配置 |
| PUT | `/config` | 更新配置 |
| GET | `/stats` | 引擎统计 |
| GET | `/openapi.json` | OpenAPI规范 |

### MCP Server (Claude/OpenAI 集成)

#### 编程式调用

```python
from neuron_engine.workflow import NeuronEngine
from neuron_engine.db import NeuronDB
from neuron_engine.mcp_server import NeuronMCPServer
import json

engine = NeuronEngine(db=NeuronDB(":memory:"))
server = NeuronMCPServer(engine)

# 列出工具
resp = server.handle_request({
    "jsonrpc": "2.0", "id": 1,
    "method": "tools/list", "params": {}
})
for tool in resp["result"]["tools"]:
    print(f"  {tool['name']}: {tool['description']}")

# 执行任务
resp = server.handle_request({
    "jsonrpc": "2.0", "id": 2,
    "method": "tools/call",
    "params": {
        "name": "neuron_execute_task",
        "arguments": {"task_input": "分析文本情感", "priority": "5"}
    }
})
result = json.loads(resp["result"]["content"][0]["text"])
print(f"Status: {result['status']}")
```

#### 自定义工具

```python
server.register_tool_simple(
    name="my_tool",
    description="自定义工具",
    params={"query": "查询内容"},
    handler=lambda p: {"result": process(p["query"])},
)
```

#### Claude Desktop 集成

将以下配置添加到 Claude Desktop 配置文件:

```json
{
  "mcpServers": {
    "neuron-engine": {
      "command": "python",
      "args": ["-m", "neuron_engine.mcp_server"],
      "cwd": "/path/to/neuron-engine"
    }
  }
}
```


## 运行测试

```bash
cd neuron-engine
python -m pytest tests/ -v
```

## 项目结构

```
neuron-engine/
├── neuron_engine/
│   ├── __init__.py          # 包入口 V3.0.0
│   ├── protocols.py         # Protocol接口定义 (ISignal/ISynapse/INeuron)
│   ├── mcp_server.py        # MCP Server (JSON-RPC 2.0 + stdio)
│   ├── logging.py           # 分层日志系统 (层级Logger + JSON格式化)
│   ├── core/                # 核心模型
│   │   ├── signal.py        # 三分类信号协议
│   │   ├── neuron.py        # LIF膜电位 + 三态熔断
│   │   └── synapse.py       # 突触 + STDP权重锁定
│   ├── config/              # 配置管理 (13+9项, 4分组)
│   ├── learning/            # STDP学习 + RPE奖励评估
│   ├── memory/              # 原子记忆 + 四级晋升 + 链式检索
│   ├── governance/          # 全局调控 + 人格 + 情绪 + 三维协同
│   ├── workflow/            # 10步闭环工作流引擎
│   ├── db/                  # 14张核心表持久化 (SQLite/PG)
│   ├── api/                 # REST API (零依赖)
│   ├── signal/              # 信号总线 + 生命周期 + 噪声过滤
│   ├── evolution/           # 自动演化引擎
│   ├── monitor/             # 指标采集 + 异常检测 + 自愈 + Dashboard
│   ├── utils/               # 工具函数
│   └── exceptions/          # 23章错误码体系 (21个异常类)
├── tests/                   # 165个单元测试 (12文件, 0.42s)
│   ├── test_core.py         # Signal/Neuron/Synapse (21)
│   ├── test_learning.py     # STDP/RPE (19)
│   ├── test_memory.py       # MemoryAtom/MemoryManager (28)
│   ├── test_governance.py   # GovernanceSystem (22)
│   ├── test_workflow.py     # NeuronEngine (5)
│   ├── test_db.py           # NeuronDB (11)
│   ├── test_protocols.py    # Protocol接口 (7)
│   ├── test_logging.py      # 日志系统 (18)
│   ├── test_mcp_server.py   # MCP Server (12)
│   ├── test_signal.py       # 信号总线/生命周期/噪声 (16)
│   ├── test_evolution.py    # 自动演化 (5)
│   └── test_monitor.py      # 监控/异常检测 (6)
├── examples/
│   ├── basic_usage.py       # 基础使用6例
│   └── mcp_server_usage.py  # MCP Server使用3例
├── docker/
│   ├── Dockerfile           # 容器化部署
│   └── docker-compose.yml   # 编排配置
├── pyproject.toml           # 打包配置 (零依赖, 可选PG)
└── README.md
```

## 白皮书映射

| SDK模块 | 白皮书章节 | 核心内容 |
|---------|-----------|---------|
| `core/signal.py` | 第6章 | 三分类信号协议、工厂方法 |
| `core/neuron.py` | 第5/7章 | LIF膜电位、三态熔断、点火放电 |
| `core/synapse.py` | 第6/7章 | 突触权重锁定[0.1,0.9]、STDP更新 |
| `learning/` | 第7章 | Bi&Poo 1998 STDP参数、RPE奖励 |
| `memory/` | 第9章 | 原子记忆节点、四级晋升规则 |
| `governance/` | 第8章 | 四维全局状态、大五人格、VAD情绪 |
| `workflow/` | 第11/12章 | 10步闭环工作流 |
| `db/` | 第13章 | 14张核心表DDL |
| `config/` | 第10章 | 13+9项配置、4分组、热加载 |
| `exceptions/` | 第23章 | 5级错误分级、21个异常类 |

## License

MIT

## 📝 更新日志

### v3.0.2 (2026-05-08)
- ✅ 【发布信息】更新维护者信息为：合肥极美景行商贸有限公司「若曦」项目组
- ✅ 【发布信息】同步更新开发者邮箱与项目归属信息
- ✅ 【发布信息】修复 PyPI 发布配置，确保版本号与描述一致性
- ✅ 【文档】完善项目简介与开发者背景说明

### v3.0.1 (2026-05-07)
- ✨ 新增 MCP 协议集成接口（10个工具/4分组/协议握手/客户端配置）
- ✨ 新增命令行工具（6子命令/使用示例/退出码规范）
- ✨ 新增 HTTP REST 接口（29端点/7分组/监控端点/Router架构）
- ✨ 完善部署与分发支持（PyPI发布/安装方式/双DB/多协议/部署清单）
- ✨ 新增协议抽象与扩展接口（5接口/4后端/4枚举/扩展示例）
- ✨ 补充 V3.0 版本演进更新（里程碑10项/章节索引/全景图）
- ✨ 完成 PyPI 发布：`neuron-engine` 3.0.1，纯Python零外部依赖

### v3.0.0 (2026-05-06)
- 🚀 发布「若曦・类脑神经元全域智能体架构」核心引擎 `neuron-engine`
- 🧠 实现基于五层神经圈层架构的通用AI Agent核心框架
- ⚡ 支持脉冲神经网络（SNN）、STDP突触可塑性、LIF神经元模型
- 📦 开源发布，支持 `pip install neuron-engine` 一键安装
