Metadata-Version: 2.5
Name: ershu-core
Version: 1.0.1.post20260812
Summary: Shared data, access control, querying, and run state for Ershu services.
Project-URL: Documentation, https://ershu.org
Project-URL: Repository, https://github.com/ershu-lab/ershu-core
Project-URL: Issues, https://github.com/ershu-lab/ershu-core/issues
Author: Ershu contributors
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: code-intelligence,developer-tools,ershu
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.14
Requires-Dist: aiosqlite<1.0.0,>=0.20.0
Requires-Dist: alembic<2.0.0,>=1.16.0
Requires-Dist: anthropic<1.0.0,>=0.100.0
Requires-Dist: asyncpg<1.0.0,>=0.30.0
Requires-Dist: cryptography>=44.0.0
Requires-Dist: greenlet<4.0.0,>=3.2.0
Requires-Dist: httpx<1.0.0,>=0.28.0
Requires-Dist: openai<3.0.0,>=2.36.0
Requires-Dist: pydantic-settings<3.0.0,>=2.8.0
Requires-Dist: pydantic<3.0.0,>=2.10.0
Requires-Dist: pymilvus<4.0.0,>=3.0.0
Requires-Dist: sqlalchemy[asyncio]<3.0.0,>=2.0.36
Description-Content-Type: text/markdown

# Ershu Core

[简体中文](README-CN.md)

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](https://github.com/ershu-lab/ershu).

## Where Core fits

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

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

| Area | What Core provides |
| --- | --- |
| Data and migrations | SQLAlchemy models, async sessions, Alembic revisions, and the `ershu-db` command |
| Projects and access | Projects, repositories, memberships, grants, user and project MCP key scopes, and visibility checks |
| Run state | Analysis runs, queue leases, events, blocks, conversations, cancellation, and retention |
| Documents and retrieval | Documents, sections, chunks, search selection, Milvus indexing, and reranking primitives |
| Project relationships | Shared queries for code indexes, knowledge graphs, change surfaces, and runtime flows |
| Repository access | Managed workspaces, trusted local path checks, Git URL restrictions, and read-only file access |
| Model channels | Shared records and selection rules for language, embedding, and reranking providers |
| Service contracts | Schemas, errors, identifiers, and runtime setting definitions shared across backend services |

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

| Path | Contents |
| --- | --- |
| `src/ershu/core/` | Configuration, logging, security checks, errors, and identifiers |
| `src/ershu/db/` | Data models, async database sessions, and the migration command entry point |
| `src/ershu/schemas/` | Data structures shared by backend services |
| `src/ershu/services/` | Shared project, access, run, retrieval, repository, and model channel behavior |
| `src/ershu/tools/readonly_repository/` | Path-constrained, read-only repository access |
| `alembic/` | Database migration history |
| `tests/` | Unit tests and optional checks against real services |

## Install

Ershu Core requires Python 3.14. The
[`ershu` installer package](https://github.com/ershu-lab/ershu) selects the Core
release pinned by that Ershu composition:

```bash
pip install ershu
```

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

```bash
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:

```bash
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`](.env.example) is a development
starting point:

```bash
cp .env.example .env
```

The main setting groups are:

| Group | Settings | Purpose |
| --- | --- | --- |
| Process | `APP_NAME`, `APP_VERSION`, `ENVIRONMENT`, `LOG_LEVEL` | Process identity and logging |
| PostgreSQL | `DATABASE_URL`, `DATABASE_POOL_SIZE`, `DATABASE_MAX_OVERFLOW`, `DATABASE_POOL_TIMEOUT_SECONDS` | Persistent application and run data |
| Milvus | `MILVUS_URI`, `MILVUS_TOKEN`, `MILVUS_DB_NAME` | Rebuildable vector indexes |
| Runs and search | `RUN_QUEUE_LEASE_TIMEOUT_SECONDS`, `ANALYSIS_RUN_RETENTION_COUNT`, `SEARCH_INDEX_BATCH_SIZE` | Shared queue and indexing defaults |
| Sessions | `SESSION_IDLE_TIMEOUT_MINUTES` | Shared session validation window |
| Repository access | `REPOSITORY_STORAGE_PATH`, `TRUSTED_LOCAL_PATHS`, `GIT_ALLOWED_HOSTS`, Git protocol switches | Cache location and repository trust boundaries |
| Secrets | `SECRET_KEY`, `ENCRYPTION_KEY`, `MCP_KEY_PEPPER` | Session signing, stored credential encryption, and MCP key verification |
| Repository credentials | `GITHUB_TOKEN`, `GITLAB_TOKEN` | Fallback access when a repository has no stored credential |

`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:

```bash
uv run ershu-db heads
```

Inspect the revision applied to the configured database:

```bash
uv run ershu-db current
```

Upgrade the database:

```bash
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:

```bash
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:

```bash
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:

```bash
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](LICENSE).
