team/dev/: vista-3.0.8.post251231 metadata and description

Add your description here

description_content_type	text/markdown
metadata_version	2.3
requires_dist	agno>=2.1.3 czsc>=0.9.68 tomlkit>=0.13.0 clickhouse-connect>=0.6.0 loguru>=0.7.0 pydantic>=2.6.0 tabulate>=0.9.0 cvxpy[complete]>=1.7.3 scs>=3.2.9 ecos>=2.0.14 osqp>=1.0.5 mosek>=11.0.29 openai>=2.8.0 fastapi>=0.121.2 uvicorn[standard]>=0.38.0 faiss-cpu>=1.13.0 joblib>=1.5.2 sqlalchemy>=2.0.44 psutil>=7.1.3 streamlit>=1.36.0 google-genai>=1.56.0
requires_python	>=3.11

Because this project isn't in the mirror_whitelist, no releases from root/pypi are included.

File	Tox results	History
vista-3.0.8.post251231-py3-none-any.whl Size 112 KB Type Python Wheel Python 3		Uploaded to team/dev by team 2025-12-31 07:33:53

vista

前瞻视野/长期推演；侧重趋势预测；因子挖掘流程

面向量价因子的系统化挖掘、计算、评估与截面建模工程。项目聚焦趋势预测与长期推演，提供从标准化数据 → 因子构建 → 性能评价 → 策略建模的端到端流程，兼顾工程可用性与研究可扩展性。

项目目标与特点

覆盖因子挖掘的全链路：数据标准、算子库、并行计算引擎、批量评估、数据库化管理、截面策略建模与智能体辅助生成
高性能计算：并行、分批、内存监控与故障回退，提供完整性能统计与告警
工程规范：统一枚举/Schema、可插拔算子、严密的输入校验、防未来信息审计

uv add vista --default-index https://pypi.zbczsc.com/team/dev --trusted-host pypi.zbczsc.com

pip install vista -i https://pypi.zbczsc.com/team/dev

目录结构

vista/engines.py 因子计算引擎（时序引擎、截面引擎占位）
vista/operates.py 算子库（TA-Lib与自定义算子、横截面算子草案）
vista/factor_db/ 因子库服务（ClickHouse管理、模型Schema与CRUD）
vista/models/ 截面策略建模（排序法、直接暴露、组合优化、最大化因子暴露）
scripts/ 批量因子分析与Notebook示例（含配置 scripts/config/）
examples/zengbin/ 因子矿工与使用示例（LLM生成、FAISS检索、流程配置）
examples/zyf/agno/ 智能体生态示例（工具/存储/知识、公告解析、因子工厂与分析报告）
tests/ 引擎与功能单元测试
docs/ 设计与规范说明（K线标准、数据库与标签体系、架构说明、流程图）
.github/workflows/ CI配置（如发布流水线）
.vscode/ 编辑器工程设置
根目录：README.md、pyproject.toml、uv.lock、.python-version、.gitignore

标准数据与因子列规范

标准K线必备列：dt, symbol, open, close, high, low, vol, amount
因子列命名以 F# 前缀，例如：F#YourFactor#DEFAULT

核心模块说明

因子计算引擎

时序引擎 TimeSeriesEngine：并行计算与分批处理，自动内存阈值监控，失败回退至单线程，输出性能统计与告警
截面引擎 CrossSectionEngine：输入校验与接口占位，建议后续实现按日横截面向量化计算

使用示例：

import pandas as pd
from vista.engines import quick_compute

# df 为标准K线，含 dt / symbol 与价格量字段
results = quick_compute(
    klines=df,
    factor_code="""
import inspect
import numpy as np
import pandas as pd

def demo_factor(df, **kwargs):
    factor_col = f"F#{inspect.currentframe().f_code.co_name}#DEFAULT"
    df[factor_col] = (df['close'] - df['open']).rolling(10).mean()
    return df
""",
    factor_name="demo_factor",
    n_jobs=4,
    chunk_size=100
)

算子库（operates）

TA-Lib算子：趋势/动量/波动/成交量等常见指标的伪代码与说明，便于快速拼装因子
自定义算子：rolling统计、rank、风险/收益度量、信噪比与导数、平滑器等
横截面算子草案：winsorize、rank、normalize、regression 等，为截面处理与组合构建提供基元

因子数据库（ClickHouse）

管理器 FactorDBManager：单例连接、自动建库建表、批量写入与查询、物理删除
Schema 模型：FactorDescribe、FactorEvaluate 以及联合视图模型
服务接口：新增/查询/统计因子与评估记录、联表汇总最新评估、统一枚举与类型规范

环境变量：CLICKHOUSE_DSN（示例 clickhouse://user:password@localhost:9000/factor_db）。

写入因子示例：

from vista.factor_db.manager import get_factor_db_manager
from vista.factor_db.models import FactorDescribeCreate
from vista.factor_db.services import add_factor

mgr = get_factor_db_manager()
fd = FactorDescribeCreate(
    factor_name="demo_factor",
    factor_code="...python code...",
    factor_type="TimeSeriesTechnical",
    factor_tags=[],
    compute_engine="TimeSeriesEngine",
    description="示例因子"
)
add_factor(mgr, fd)

截面策略建模（models）

基类 BaseStrategyModel：数据校验、去极值与标准化、通用运行框架与权重输出
排序法 CSSorting：按因子排序构建多空组合，支持等权与按名次加权
直接暴露法 DirectExposure：因子标准化→映射权重，支持风险中性与权重约束
组合优化法 MaxExpectedReturns：二次规划最大化预期收益，支持换手/基准约束与启发式回退
最大化因子暴露 MaxFactorExposure：以目标因子暴露为核心，风险预算与多空权重约束可配，支持启发式备选

使用示例：

import pandas as pd
from vista.models import CSSorting, DirectExposure, MaxExpectedReturns, MaxFactorExposure

df = pd.read_csv('your_data.csv')

model = CSSorting(df, factor='F#YOUR_FACTOR', top_pct=0.2, bottom_pct=0.2)
weights = model.run()[['dt','symbol','weight']]

model = DirectExposure(df, factor='F#YOUR_FACTOR', normalize_method='zscore')
weights = model.run()[['dt','symbol','weight']]

model = MaxExpectedReturns(df, factor='F#YOUR_FACTOR', risk_aversion=1.0,
                           solver_config={'solver':'ECOS'})
weights = model.run()[['dt','symbol','weight']]

model = MaxFactorExposure(df, factor='F#YOUR_FACTOR', target_exposure=0.3,
                          solver_config={'solver':'ECOS'})
weights = model.run()[['dt','symbol','weight']]

批量因子分析（scripts）

多进程并行、截面IC与收益评估、增量写入、TOML配置驱动
运行方式：

python scripts/batch_factor_analyze.py scripts/config/batch_factor_config.toml

配置要点：factors_file（因子定义表），klines_files（一个或多个标准K线文件），output_file（CSV/PKL/Feather）。

智能体因子挖掘（examples）

examples/zengbin/：LLM因子矿工（含防未来信息检测、因子代码验证与保存）、FAISS向量检索示例
examples/zyf/agno/：多智能体示例（工具/知识/存储、公告解析、因子工厂/分析/汇总报告）

运行示例：

# 因子矿工（zengbin）
python examples/zengbin/factor_miner.py

# 因子工厂（zyf/agno）
python examples/zyf/agno/factor_factory/build_factor_agent.py

端到端工作流

数据准备：按标准K线格式加载/转换，保证 dt、symbol 与价格量字段完整
因子构造：选择算子组合或智能体自动生成；在引擎中并行计算因子列
性能评估：计算截面IC、收益与稳定性指标，分时段统计 IC/ICIR/年化收益/波动/夏普等
策略建模：选择排序法/直接暴露/组合优化/最大化因子暴露等策略，产出权重表用于回测或执行
因子库管理：描述/标签/输入/评估入库并可检索最新评估结果，支持批量写入与联表查询

开发环境与依赖

# 在项目根目录创建 pyproject.toml
uv init

# 指定 Python 版本
uv python install 3.11
uv python pin 3.11

# 安装所有依赖
uv sync
# uv sync --allow-insecure-host github.com

# 更新依赖
uv update

# 添加生产依赖
uv add pandas numpy matplotlib

# 添加开发依赖
uv add --dev pytest black isort mypy

# 检查依赖
uv tree

# 激活虚拟环境
uv venv
source .venv/bin/activate  # Linux/Mac
.venv\Scripts\activate     # Windows

# 在虚拟环境中运行命令
uv run python script.py
uv run pytest

测试与质量保障

单元测试位于 tests/，覆盖引擎运行与超时、基础功能
基类与引擎包含严格的数据/输入校验与预解析，运行时捕获告警并给出性能统计

路线图 / 下一步完善

完成横截面引擎实现：按日全市场向量化计算、并行化与统一性能统计
扩展防未来信息审计：静态分析覆盖 rank/rolling、shift/diff/pct_change 负参数、错位索引/赋值
标签与元数据平台：完善标签体系与因子-输入-评估关系视图与过滤
评估与回测一体化：权重直通净值曲线与指标，对比不同建模法输出，滚动稳定性分析
性能与可扩展性：引入分布式计算与缓存，优化内存峰值与故障回退策略
CLI与配置统一：统一计算/评估/查询入口，导出CSV/Parquet/Feather，因子库迁移与备份
文档与示例：补充端到端Demo、参数选择指南与算子适配最佳实践

devpi