9.0 KiB

Raw Blame History

title

status

created

owner

review_by

Qwen Code Context for 炼妖壶 (Lianyaohu) Project

Project Overview

炼妖壶 (Lianyaohu) - 稷下学宫AI辩论系统 is a Python-based multi-AI-agent debate platform rooted in traditional Chinese philosophy. The system allows AI agents, represented by the Eight Immortals of Chinese folklore, to engage in debates on investment topics, leveraging data from multiple financial APIs.

Key technologies and components:

Python: Primary language for the core application.
Streamlit: Web framework for the user interface.
Google Vertex AI: Integration with Google's AI platform, including Memory Bank for persistent agent memory.
Google ADK (Agent Development Kit): Framework for building and managing AI agents, replacing the older OpenAI Swarm approach.
RapidAPI: Data engine powered by 17 API subscriptions for financial data.
Doppler: Centralized configuration and secrets management.
Cloudflare AutoRAG/Vectorize (New): Integrated as a memory backend (RAG).

The project has two main modes:

Traditional Mode: Data-driven debates using RapidAPI.
Swarm Mode: AI-agent debates using the OpenAI Swarm framework (can use OpenRouter or Ollama). Note: Migration to Google ADK is underway.

It also features an analysis module based on the Confucian "天下体系" (All-under-Heaven system) to model capital ecosystems.

Project Structure

liurenchaxin/
├── app/                    # Application entry points
│   ├── streamlit_app.py   # Main Streamlit application
│   └── tabs/              # Functional UI modules
│       └── tianxia_tab.py # All-under-Heaven system analysis
├── src/                   # Core business logic
│   └── jixia/            # Jixia Academy system
│       ├── engines/      # Core engines (e.g., perpetual_engine.py)
│       ├── agents/       # AI agents with memory enhancements
│       ├── memory/       # Vertex AI Memory Bank and Cloudflare AutoRAG integration
│       └── debates/      # Debate logic (including Swarm and ADK)
├── config/               # Configuration management
│   └── doppler_config.py # Interface for Doppler secrets
├── scripts/              # Utility scripts
├── tests/                # Test suite
├── .kiro/               # Kiro AI assistant configuration
│   └── steering/        # AI guiding rules
├── requirements.txt     # Python dependencies
└── package.json         # Node.js dependencies (for Cloudflare Worker tests)

Building and Running

Environment Setup

Create and activate a Python virtual environment:

python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate.bat or .venv\Scripts\Activate.ps1

Install Python dependencies:
```
pip install -r requirements.txt
```
Configure secrets using Doppler (or environment variables directly, though not recommended). Required keys include RAPIDAPI_KEY and either OPENROUTER_API_KEY_1 or GOOGLE_API_KEY.

Running the Application

Start the main Streamlit web interface:

streamlit run app/streamlit_app.py
# Optionally specify a port:
# streamlit run app/streamlit_app.py --server.port 8501

Installing Optional Components

To use the Swarm debate features:

pip install git+https://github.com/openai/swarm.git
# Or potentially:
# python scripts/install_swarm.py

To use Google ADK (for newer features):

pip install google-adk
# Or for the latest development version:
# pip install git+https://github.com/google/adk-python.git@main

Testing

Several test and validation scripts exist:

# Validate configuration
python config/doppler_config.py

# Test API connections (specific script names may vary)
# python scripts/test_*.py

# Test Vertex AI Memory Bank
python tests/test_vertex_memory_bank.py

# Test Google ADK functionality
python src/jixia/debates/adk_debate_test.py
python src/jixia/debates/adk_simple_debate.py
python src/jixia/debates/adk_real_debate.py
python src/jixia/debates/adk_memory_debate.py

# Run other specific tests
python tests/test_*.py

(Note: The scripts/test_openrouter_api.py file mentioned in README.md was not found in the directory listing.)

Development Conventions

Language: Python 3.x
Coding Style: PEP 8
Type Hinting: Extensive use of type annotations (typing module) and dataclass for data structures.
Configuration: Centralized configuration management via config/doppler_config.py, strictly avoiding hardcoded secrets.
Security: Zero hardcoded keys, environment isolation, automated security scanning.
Testing: Unit tests for core functions, integration tests for API calls, and validation tests for configuration are required.

Key Files for Quick Reference

README.md: Main project documentation.
app/streamlit_app.py: Entry point for the web application.
src/jixia/engines/perpetual_engine.py: Core data engine for providing information to agents.
src/jixia/memory/vertex_memory_bank.py: Integration with Google Vertex AI Memory Bank.
src/jixia/memory/factory.py: Factory for creating memory backends (Vertex or Cloudflare).
src/jixia/agents/memory_enhanced_agent.py: Implementation of agents with persistent memory, using Google ADK.
src/jixia/debates/adk_*.py: Implementations of debate systems using Google ADK.
config/doppler_config.py: Central place for accessing configuration and secrets.
requirements.txt: Python dependencies.
QUICK_START_GUIDE.md: Instructions for quick setup and basic usage examples.
MIGRATION_STATUS.md: Detailed report on the migration from OpenRouter/Swarm to Google ADK.
RELEASE_v2.0.0.md: Release notes for the v2.0.0 release, detailing the new debate system and memory features.

Vertex AI Configuration

The project can be configured to use Google Vertex AI. The configuration is managed primarily through environment variables, though Doppler can also be used.

Required Environment Variables for Vertex AI

GOOGLE_GENAI_USE_VERTEXAI: Set to TRUE to enable Vertex AI.
GOOGLE_CLOUD_PROJECT_ID: Your Google Cloud Project ID.
GOOGLE_API_KEY: Your Google API Key (used for authentication when not using Vertex AI service account).
GOOGLE_CLOUD_LOCATION: (Optional) The location for Vertex AI resources (defaults to us-central1).
VERTEX_MEMORY_BANK_ENABLED: (Optional) Set to TRUE to enable Vertex AI Memory Bank (defaults to TRUE).

Authentication for Vertex AI

Authentication for Vertex AI can be handled in two ways:

Service Account Key: Set the GOOGLE_SERVICE_ACCOUNT_KEY environment variable with the path to your service account key file.
Application Default Credentials (ADC): Run gcloud auth application-default login to generate the ADC file at ~/.config/gcloud/application_default_credentials.json.

The system will first check for a service account key. If not found, it will fall back to using Application Default Credentials.

Configuration Validation

The test_vertex_ai_setup.py script can be used to validate your Vertex AI configuration:

python test_vertex_ai_setup.py

This script checks for the presence of required environment variables and the ADC file, and verifies that the configuration is correct for using Vertex AI with the application.

Qwen's Role and Workflow

Qwen is integrated as a core collaborator in the 炼妖壶 (Lianyaohu) project, working alongside Gemini and other tools. The primary role of Qwen Code is to:

Maintain and Understand Context: Keep a clear and up-to-date understanding of the project's structure, goals, and current state, as reflected in this QWEN.md file.
Perform Software Engineering Tasks: Execute tasks such as code reading, writing, refactoring, debugging, and testing. This includes implementing new features like the "Celestial Map" (celestial_map.py), the "Market FSM" (market_fsm.py), and the "Monster Stock Scanner" (monster_stock_scanner.py).
Code Generation and Review: Generate new code modules based on abstract concepts (e.g., turning "差序格局" into a NetworkX graph model) and review existing code for adherence to project conventions and architectural principles.
System Integration: Understand how different parts of the system (e.g., mythology engine, cycle models, dragon agents) interact and ensure new components integrate smoothly.
Follow Project Conventions: Strictly adhere to the project's development conventions, including language (Python 3.x), coding style (PEP 8), type hinting, configuration management (Doppler), and security practices (no hardcoded keys).
Tool Usage: Utilize available tools like read_file, write_file, replace, search_file_content, glob, run_shell_command, and web_fetch to perform actions and gather information autonomously.

9.0 KiB Raw Blame History