Ershu Core

简体中文

Ershu Core is the shared Python package used by the Ershu API, MCP server, and worker. It owns the data models, access rules, query primitives, run state, repository workspace safeguards, and database migrations that those services use in common.

This repository is for contributors working on shared backend behavior. It is not a standalone Ershu deployment: Core does not listen on a port, expose HTTP or MCP endpoints, or run repository analysis jobs. For a complete installation, start with the Ershu deployment repository.

Where Core fits

Frontend -> API ----+
                    |
AI client -> MCP ---+-> Core -> PostgreSQL / Milvus
                    |
             Worker-+

API, MCP, and Worker depend on Core. They do not depend on one another.

Core does not contain FastAPI routes, browser authentication flows, MCP response formatting, worker analysis orchestration, LSP execution, or frontend code. Keep behavior used by only one service in that service's repository.

Repository layout

Install

Ershu Core requires Python 3.14. The ershu installer package selects the Core release pinned by that Ershu composition:

pip install ershu

Projects that depend on Core as a library can pin the component directly:

uv add "ershu-core==1.0.1.post20260812"

The API, MCP server, and Worker each declare the oldest Core release they support. Their version numbers do not need to match Core. The ershu[api], ershu[mcp], ershu[worker], and ershu[all] choices install a set of component versions tested together.

After installation, confirm that the migration files are available:

uv run ershu-db heads

heads reads the packaged migration history without connecting to a database.

Configuration

Core reads environment variables and a .env file in the current working directory. The repository's .env.example is a development starting point:

cp .env.example .env

The main setting groups are:

validate_auth_secrets() rejects the configuration if a shared secret is shorter than 32 characters, retains a known placeholder value, or duplicates another secret. Generate three independent values before running a production service.

Core accepts managed repository caches, Git checkouts, and paths explicitly allowed by the caller. Use TRUSTED_LOCAL_PATHS for other local directories. validate_common_runtime_settings() rejects ALLOW_DEV_OPEN_LOCAL_REPOSITORY_PATHS=true when ENVIRONMENT is prod or production.

Service-specific settings stay outside Core. Redis, browser tokens, cookies, CORS, and login settings belong to the API. Analysis concurrency, LSP images, and worker policies belong to Worker. MCP transport and DNS rebinding settings belong to the MCP server.

Database migrations

All Ershu backend services use the migration history shipped with Core. Back up the target database before an upgrade and run migrations with the Core version selected for that deployment.

Inspect the available migration head:

uv run ershu-db heads

Inspect the revision applied to the configured database:

uv run ershu-db current

Upgrade the database:

uv run ershu-db upgrade head

ershu-db current and ershu-db upgrade head use DATABASE_URL and connect to the database. A successful heads command only confirms that the installed package contains its migration files.

When changing a model:

1. Update the model under src/ershu/db/.
2. Add a revision under alembic/versions/.
3. Test both upgrade and downgrade behavior. Do not rewrite a published revision.
4. Build the package and check ershu-db heads from the installed wheel.

Development

Clone the repository and install its locked development environment with UV:

git clone https://github.com/ershu-lab/ershu-core.git
cd ershu-core
uv sync --locked

Core can be installed, tested, and built without the API, MCP, Worker, or deployment repositories.

Run the checks used for regular changes:

uv run pytest -m "not integration"
uv run ruff check src tests
uv run ruff format --check src tests
uv build --no-sources

The default test command uses SQLite where a database is needed. The integration tests connect to real PostgreSQL and Milvus instances only when their test variables are set:

export ERSHU_TEST_POSTGRES_URL='postgresql+asyncpg://user:password@host:5432/ershu_test'
export ERSHU_TEST_MILVUS_URI='http://127.0.0.1:19530'
export ERSHU_TEST_MILVUS_TOKEN=''
export ERSHU_TEST_MILVUS_DB_NAME='default'
uv run pytest -m integration

Set only the services you intend to test. Keep real addresses and credentials in your local environment or secret store, not in the repository.

License

Ershu Core is licensed under the Apache License 2.0.