AIRegulation/nexus-claude-api
7
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Enhance user configuration management and logging

Browse Source 
- Introduced user configuration command to set API key.
- Updated README and documentation for user config and logging paths.
- Refactored logging to support user-specific log files.
- Added tests for user configuration and logging behavior.
This commit is contained in:
Guangfei.Zhao
2026-06-27 10:21:00 +08:00
parent 0e98ce57d4
commit 4685a0165d
10 changed files with 434 additions and 25 deletions
Download Patch File Download Diff File Expand all files Collapse all files

187
docs/PACKAGING_DISTRIBUTION.md Normal file
View File

@@ -0,0 +1,187 @@
# Python Internal Distribution Guide
This document describes how to distribute `nexus-claude-api` internally without publishing to PyPI.
## Recommended Options
Use one of these two approaches:
- **Wheel distribution**: build a `.whl` file and send it to colleagues. This is best for stable internal releases.
- **Private Git installation**: let colleagues install directly from the company Git repository. This is best for teammates who can access the source code or need frequent updates.
Both options require:
- Python `>=3.11`
- Access to PyPI or the company Python package mirror for runtime dependencies
- A personal AI Nexus API key
Do not share `nexus-claude-api.local.json`, `.env`, logs, or any personal API key.
## Option 1: Build and Share a Wheel
A wheel is the standard Python install package format. It is not an `.exe`; colleagues install it with `pip`, then run the installed `nexus-claude-api` command.
### Publisher Steps
1. Confirm the package version in `pyproject.toml`:
```toml
[project]
name = "nexus-claude-api"
version = "0.1.0"
```
Update the version for every released package. Avoid sending different builds with the same version.
2. Run the supported checks:
```powershell
uv sync --extra dev
uv run pytest
uv run nexus-claude-api start --dry-run
```
3. Build the package:
```powershell
uv build
```
This creates files under `dist/`, usually:
```text
dist/nexus_claude_api-0.1.0-py3-none-any.whl
dist/nexus_claude_api-0.1.0.tar.gz
```
4. Test the wheel in a clean environment:
```powershell
py -3.11 -m venv C:\Temp\nexus-claude-api-test
C:\Temp\nexus-claude-api-test\Scripts\python.exe -m pip install .\dist\nexus_claude_api-0.1.0-py3-none-any.whl
C:\Temp\nexus-claude-api-test\Scripts\nexus-claude-api.exe start --dry-run
```
5. Send only the `.whl` file to colleagues through an approved internal channel.
### Colleague Installation
Install the wheel:
```powershell
py -3.11 -m pip install .\nexus_claude_api-0.1.0-py3-none-any.whl
```
Configure the personal Nexus key:
```powershell
nexus-claude-api config set --api-key "your-nexus-api-key"
```
Start the local proxy and print the Claude Code helper:
```powershell
nexus-claude-api start --port 4141 --claude-code
```
If PowerShell cannot find the installed script, use the module form:
```powershell
py -3.11 -m nexus_claude_api start --port 4141 --claude-code
```
### Upgrade
Send a new wheel with a new version, then ask colleagues to run:
```powershell
py -3.11 -m pip install --upgrade .\nexus_claude_api-0.1.1-py3-none-any.whl
```
## Option 2: Install from Private Git
Private Git installation avoids manual wheel sharing. It still uses the Python package metadata from `pyproject.toml`, so the installed command is the same.
### Publisher Steps
1. Push the code to the company Git repository.
2. Update the version in `pyproject.toml` for each released version.
3. Tag stable versions:
```powershell
git tag v0.1.0
git push origin v0.1.0
```
For the next release:
```powershell
git tag v0.1.1
git push origin v0.1.1
```
4. Share an install command that points to a tag:
```powershell
py -3.11 -m pip install "git+https://company-git.example.com/group/nexus-claude-api.git@v0.1.0"
```
Prefer tags or exact commit SHAs. Avoid asking normal users to install from `main`, because repeated installs can produce different code over time.
### Colleague Installation
Install from the company Git repository:
```powershell
py -3.11 -m pip install "git+https://company-git.example.com/group/nexus-claude-api.git@v0.1.0"
```
Configure the personal Nexus key:
```powershell
nexus-claude-api config set --api-key "your-nexus-api-key"
```
Start the local proxy:
```powershell
nexus-claude-api start --port 4141 --claude-code
```
### Upgrade
Upgrade to a newer tag:
```powershell
py -3.11 -m pip install --upgrade "git+https://company-git.example.com/group/nexus-claude-api.git@v0.1.1"
```
### Development Clone
For colleagues who will modify or test the source code:
```powershell
git clone https://company-git.example.com/group/nexus-claude-api.git
cd nexus-claude-api
uv sync --extra dev
uv run nexus-claude-api start --dry-run
```
## Choosing Between the Two
- Use **wheel distribution** for normal internal users who only need a stable tool.
- Use **private Git installation** for colleagues who understand the repository, need fast updates, or help develop the project.
- Keep version numbers and Git tags aligned. For example, `pyproject.toml` version `0.1.0` should correspond to tag `v0.1.0`.
## Release Checklist
Before sharing a release:
- Run `uv run pytest`.
- Run `uv run nexus-claude-api start --dry-run`.
- Test wheel installation in a clean Python environment.
- If using Git installation, test install from the exact tag.
- Confirm no personal credentials are included.
- Confirm `nexus-claude-api.local.json`, `.env`, logs, caches, and `dist/` artifacts are not committed accidentally.

14
docs/PRD.md
View File

@@ -53,7 +53,8 @@ The proxy defaults to Opus because this deployment is intended for users whose N
## User Stories
- As a developer, I can store my Nexus key in ignored local config or set `NEXUS_API_KEY`, then run `nexus-claude-api start --claude-code` to get a Claude Code launch command.
- As a developer, I can store my Nexus key in user config with `nexus-claude-api config set --api-key <key>` or set `NEXUS_API_KEY`, then run `nexus-claude-api start --claude-code` to get a Claude Code launch command.
- As a contributor working from the repository, I can pass `--dev` to use current-directory development config and logs.
- As a Claude Code user, I can run coding workflows through local `http://127.0.0.1:4141`.
- As a Claude Code user, I can receive streaming model output.
- As a Claude Code user, I can use tool calls and tool results.
@@ -63,7 +64,12 @@ The proxy defaults to Opus because this deployment is intended for users whose N
## Acceptance Criteria
- `uv run nexus-claude-api start --port 4141 --claude-code` starts a local server.
- `nexus-claude-api config set --api-key <key>` writes user config to `~/.config/nexus-claude-api/config.json`.
- The server binds to `127.0.0.1` by default.
- Default startup reads credentials from user config before environment variables.
- `--dev` startup reads current-directory `nexus-claude-api.local.json` instead of user config.
- Default logs are written to `~/.config/nexus-claude-api/logs/nexus-claude-api.log`.
- `--dev` logs are written to current-directory `logs/nexus-claude-api.log`.
- Missing Nexus credentials fail fast with a clear error.
- `GET /health` returns healthy status.
- `GET /v1/models` returns the supported Claude models.
@@ -76,8 +82,10 @@ The proxy defaults to Opus because this deployment is intended for users whose N
## Security Requirements
- Do not persist API keys automatically.
- If the user chooses hardcoded local configuration, keep it in ignored `nexus-claude-api.local.json`.
- Do not persist API keys automatically during startup.
- Persist API keys only when the user explicitly runs `nexus-claude-api config set --api-key <key>` or manually writes a config file.
- Store normal user configuration in `~/.config/nexus-claude-api/config.json`.
- Use ignored current-directory `nexus-claude-api.local.json` only for explicit `--dev` repository-local development mode.
- Do not print or log API keys.
- Redact authorization headers in debug logs.
- Bind locally by default.

42
docs/REQUIREMENTS_DESIGN.md
View File

@@ -54,16 +54,41 @@ Primary command:
uv run nexus-claude-api start --port 4141 --claude-code
```
User configuration command:
```powershell
nexus-claude-api config set --api-key <key>
```
Options:
- `--host`: default `127.0.0.1`
- `--port`, `-p`: default `4141`
- `--endpoint-url`: default `https://genai-nexus.api.corpinter.net`
- `--api-key`: optional; fallback to ignored local config, `NEXUS_API_KEY`, then `AWS_BEARER_TOKEN_BEDROCK`
- `--api-key`: optional; overrides config files and environment variables
- `--model`: default `claude-opus-4.6`
- `--small-model`: default `claude-opus-4.6`
- `--claude-code`: print Claude Code launch command
- `--verbose`, `-v`: debug logging without secrets
- `--dev`: use current-directory development config and logs
- `--dry-run`: validate config and print helper output without starting the server
Credential lookup order:
1. `--api-key`
2. Current-mode config file
3. `NEXUS_API_KEY`
4. `AWS_BEARER_TOKEN_BEDROCK`
Config file paths:
- Default mode: `~/.config/nexus-claude-api/config.json`
- Development mode with `--dev`: current-directory `nexus-claude-api.local.json`
Log file paths:
- Default mode: `~/.config/nexus-claude-api/logs/nexus-claude-api.log`
- Development mode with `--dev`: current-directory `logs/nexus-claude-api.log`
When `--claude-code` is used, print a PowerShell command that sets:
@@ -89,7 +114,7 @@ Expose:
`ANTHROPIC_AUTH_TOKEN` is printed as `dummy` because Claude Code expects an Anthropic auth token variable to exist. This local proxy does not validate that inbound token by default. It is not the Nexus key.
Inbound authentication headers are accepted for compatibility but not validated by default because the service is local. Outbound Nexus authentication uses `--api-key`, ignored local `nexus-claude-api.local.json`, `NEXUS_API_KEY`, or `AWS_BEARER_TOKEN_BEDROCK`.
Inbound authentication headers are accepted for compatibility but not validated by default because the service is local. Outbound Nexus authentication uses `--api-key`, the current-mode config file, `NEXUS_API_KEY`, or `AWS_BEARER_TOKEN_BEDROCK`.
## Model Mapping
@@ -182,7 +207,7 @@ Return Anthropic-compatible errors:
Status mapping:
- invalid request: `400`
- missing local Nexus credential: startup failure
- missing Nexus credential: startup failure
- Nexus auth failure: `401` or `403`
- Nexus throttling: `429`
- Nexus network/timeout: `502` or `504`
@@ -215,3 +240,14 @@ CLI tests:
- `nexus-claude-api --help`
- Claude Code command generation.
- Missing API key validation.
- User config writing with `nexus-claude-api config set --api-key <key>`.
- Default-mode user config lookup from `~/.config/nexus-claude-api/config.json`.
- Default mode ignores current-directory `nexus-claude-api.local.json`.
- Development mode uses current-directory `nexus-claude-api.local.json`.
- `--api-key` overrides config files and config files override environment variables.
Logging tests:
- Default-mode log path resolves to `~/.config/nexus-claude-api/logs/nexus-claude-api.log`.
- Development-mode log path resolves to current-directory `logs/nexus-claude-api.log`.
- Verbose logging enables debug details without logging secrets.