---
title: "Qwen Code Context for 炼妖壶 (Lianyaohu) Project"
status: summer
created: 2025-08-17
owner: Qwen
review_by: "2026-02-17"
tags: ["context", "qwen", "core"]
---

# 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:
1.  **Traditional Mode**: Data-driven debates using RapidAPI.
2.  **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

1.  Create and activate a Python virtual environment:
    ```bash
    python -m venv .venv
    source .venv/bin/activate  # On Windows: .venv\Scripts\activate.bat or .venv\Scripts\Activate.ps1
    ```
2.  Install Python dependencies:
    ```bash
    pip install -r requirements.txt
    ```
3.  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:
```bash
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:
```bash
pip install git+https://github.com/openai/swarm.git
# Or potentially:
# python scripts/install_swarm.py
```

To use Google ADK (for newer features):
```bash
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:
```bash
# 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:
1.  **Service Account Key**: Set the `GOOGLE_SERVICE_ACCOUNT_KEY` environment variable with the path to your service account key file.
2.  **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:
```bash
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.