sysmlv2copilot 0.2.0__tar.gz

sysmlv2copilot-0.2.0/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## 0.2.0
+
+- split the public package into a client-only SDK and CLI boundary
+- added PyPI-ready metadata, MIT licensing, and release workflow docs
+- added a repair workflow across the API, SDK, and CLI
+- added packaging, CI, and smoke-test improvements

sysmlv2copilot-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chance LaVoie
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sysmlv2copilot-0.2.0/MANIFEST.in

@@ -0,0 +1,17 @@
+include LICENSE
+include README.md
+recursive-include sysmlv2copilot *.py
+recursive-include examples *.py *.md *.txt
+include CHANGELOG.md
+prune app
+prune alembic
+prune context
+prune docker
+prune docs
+prune infra
+prune scripts
+prune sysmlv2copilot_admin
+prune tests
+exclude alembic.ini
+exclude Dockerfile
+exclude prompt.txt

sysmlv2copilot-0.2.0/PKG-INFO

@@ -0,0 +1,432 @@
+Metadata-Version: 2.4
+Name: sysmlv2copilot
+Version: 0.2.0
+Summary: Python client SDK and CLI for the SysML refinement API
+Author: Chance LaVoie
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/cmuchancel/sysmlv2copilot
+Project-URL: Repository, https://github.com/cmuchancel/sysmlv2copilot
+Project-URL: Issues, https://github.com/cmuchancel/sysmlv2copilot/issues
+Project-URL: Documentation, https://github.com/cmuchancel/sysmlv2copilot/tree/main/docs
+Keywords: sysml,sysmlv2,api-client,sdk,llm
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx<1,>=0.28
+Requires-Dist: pydantic<3,>=2.7
+Provides-Extra: server
+Requires-Dist: alembic<2,>=1.14; extra == "server"
+Requires-Dist: anthropic<1,>=0.84; extra == "server"
+Requires-Dist: fastapi<1,>=0.116; extra == "server"
+Requires-Dist: openai<2,>=1.0; extra == "server"
+Requires-Dist: psycopg[binary]<4,>=3.2; extra == "server"
+Requires-Dist: pydantic-settings<3,>=2.7; extra == "server"
+Requires-Dist: python-dotenv<2,>=1.0; extra == "server"
+Requires-Dist: sqlalchemy<3,>=2.0; extra == "server"
+Requires-Dist: uvicorn<1,>=0.35; extra == "server"
+Provides-Extra: admin
+Requires-Dist: pandas<3,>=2.2; extra == "admin"
+Requires-Dist: streamlit<2,>=1.45; extra == "admin"
+Provides-Extra: dev
+Requires-Dist: build<2,>=1.2; extra == "dev"
+Requires-Dist: pytest<9,>=8.3; extra == "dev"
+Requires-Dist: twine<7,>=5; extra == "dev"
+Dynamic: license-file
+
+# SysML Refinement API
+
+This repository contains two distinct products:
+- a public Python SDK and CLI, published as `sysmlv2copilot`
+- an internal server/admin implementation that stays hosted and black-box
+
+## Repo Split
+
+The repository is now organized into two explicit halves:
+- `api/`: index for the service/SDK/admin side
+- `finetune/`: local dataset generation, repair corpus, and fine-tuning assets
+
+To avoid breaking runtime imports in one large move, the API code still currently lives in the root-owned paths such as `app/`, `alembic/`, `sysmlv2copilot/`, `sysmlv2copilot_admin/`, and the main `scripts/` directory. The fine-tuning assets now live directly under `finetune/`.
+
+The hosted service accepts either natural-language requirements or SysML input, runs the compiler-in-the-loop workflow, returns SysML plus structured metadata, and stores each request with a single persisted artifact bundle.
+
+The service itself is intentionally narrow:
+- internal-only
+- one user, one API key
+- plain text in, SysML text out
+- FastAPI HTTP layer
+- Postgres-compatible metadata storage
+- filesystem artifact storage by default
+- admin operations through CLI scripts, not public admin routes
+
+## Public SDK
+
+The public package is client-only. It does not ship the backend, migrations, deployment code, or admin console.
+
+Install from PyPI:
+
+```bash
+python -m pip install sysmlv2copilot
+```
+
+Basic generation:
+
+```python
+from sysmlv2copilot import SysMLCopilot
+
+with SysMLCopilot(
+    api_key="sysml_live_...",
+    base_url="https://your-deployment.example.com",
+) as client:
+    response = client.responses.create(
+        input="Design a compact warehouse inspection drone that can hover for 15 minutes.",
+        provider="openai",
+    )
+    print(response.id)
+    print(response.output_text)
+```
+
+Basic repair:
+
+```python
+from sysmlv2copilot import SysMLCopilot
+
+broken_sysml = """package Example {
+  public import ScalarValues::*;
+  requirement def R { text = "Missing semicolon" }
+}
+"""
+
+with SysMLCopilot(
+    api_key="sysml_live_...",
+    base_url="https://your-deployment.example.com",
+) as client:
+    repaired = client.repairs.create(input=broken_sysml, provider="openai")
+    print(repaired.compiler_passed)
+    print(repaired.output_text)
+```
+
+CLI examples:
+
+```bash
+sysmlv2copilot --api-key sysml_live_... \
+  --base-url https://your-deployment.example.com \
+  responses create \
+  --input "Design a compact warehouse inspection drone that can hover for 15 minutes."
+
+sysmlv2copilot --api-key sysml_live_... \
+  --base-url https://your-deployment.example.com \
+  repairs create \
+  --input-file ./broken.sysml
+```
+
+SDK details:
+- [docs/PYTHON_SDK.md](/Users/chancelavoie/Desktop/sysmlv2copilot/docs/PYTHON_SDK.md)
+- [docs/PYPI_RELEASE.md](/Users/chancelavoie/Desktop/sysmlv2copilot/docs/PYPI_RELEASE.md)
+
+## What It Solves
+
+The upstream pipeline already knows how to:
+- build the iterative refinement prompt
+- call the OpenAI Responses API
+- write every iteration prompt and candidate SysML file
+- run `syside check`
+- capture compiler diagnostics
+- stop on success or refinement limits
+
+This service wraps that exact behavior in an authenticated API with request tracking and persistent artifacts so an internal team can use it immediately.
+
+The refinement loop now supports either upstream provider:
+- OpenAI via the Responses API
+- Anthropic via the Messages API
+
+The public API surface stays narrow and OpenAI-style. Provider choice is an internal runtime option exposed as an extra request field.
+
+## Repo Layout
+
+- `app/`: FastAPI app, auth, DB models, storage, and upstream wrapper
+- `app/upstream/refine_sysml.py`: vendored upstream refiner used as the behavior source of truth
+- `context/upstream/`: tight context package copied from the upstream repo
+- `scripts/`: admin CLI for user creation, API key reset, and usage reporting
+- `alembic/`: schema migrations
+- `sysmlv2copilot/`: public client SDK and CLI package
+- `sysmlv2copilot_admin/`: internal Streamlit admin console
+- `tests/`: API, CLI, and config coverage
+
+## Internal Repo Setup
+
+If you are working on the hosted backend from this repo, install the internal extras:
+
+1. Create a virtual environment and install dependencies:
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install --upgrade pip
+python -m pip install -e ".[server,admin,dev]"
+```
+
+2. Create `.env`:
+
+```bash
+cp .env.example .env
+```
+
+3. Fill in at least:
+- one or both of `OPENAI_API_KEY` / `ANTHROPIC_API_KEY`
+- one of `SYSIDE_VENV_PATH` or `SYSIDE_EXECUTABLE_PATH`
+- `API_KEY_HASH_PEPPER`
+- optionally a PostgreSQL `DATABASE_URL`
+
+SQLite works for local development. PostgreSQL or Supabase Postgres is preferred for shared environments.
+For PostgreSQL or Supabase, install/runtime support now includes `psycopg`.
+
+## Migrations
+
+Run the schema migration before starting the service:
+
+```bash
+alembic upgrade head
+```
+
+## Start The Service
+
+```bash
+uvicorn app.main:app --reload
+```
+
+The default address is `http://127.0.0.1:8000`.
+
+## Create A User And API Key
+
+Create a user and print the plaintext key once:
+
+```bash
+python scripts/create_user.py --email engineer@example.com --name "Internal Engineer"
+```
+
+Reset the single API key for an existing user:
+
+```bash
+python scripts/reset_api_key.py --email engineer@example.com
+```
+
+List usage:
+
+```bash
+python scripts/list_usage.py --email engineer@example.com --from-date 2026-03-01 --to-date 2026-03-31
+```
+
+## Call The API
+
+```bash
+curl -s http://127.0.0.1:8000/v1/responses \
+  -H "Authorization: Bearer sysml_live_..." \
+  -H "Content-Type: application/json" \
+  -d '{
+    "input": "Design a compact battery-powered inspection drone that fits in a 30 cm cube and flies for 20 minutes.",
+    "model": "refine-sysml-v1",
+    "provider": "openai",
+    "max_iters": 10,
+    "max_total_tokens": 40000,
+    "temperature": null
+  }'
+```
+
+Example successful response:
+
+```json
+{
+  "id": "resp_20260312_161200_abcd",
+  "object": "response",
+  "status": "completed",
+  "model": "refine-sysml-v1",
+  "output_text": "package RequirementsOnly { ... }",
+  "compiler_passed": true,
+  "iterations_completed": 4,
+  "started_at": "2026-03-12T16:12:00Z",
+  "finished_at": "2026-03-12T16:12:22Z",
+  "duration_ms": 22014,
+  "request_user_id": "usr_1234",
+  "metadata": {
+    "provider": "openai",
+    "upstream_model": "gpt-5-mini",
+    "run_id": "run_20260312_161200_abcd",
+    "artifact_paths": {
+      "request_artifact": "/abs/path/request_artifact.json"
+    }
+  },
+  "error": null
+}
+```
+
+Repair request example:
+
+```bash
+curl -s http://127.0.0.1:8000/v1/repairs \
+  -H "Authorization: Bearer sysml_live_..." \
+  -H "Content-Type: application/json" \
+  -d '{
+    "input": "package Example { requirement def R { text = \"Missing semicolon\" } }",
+    "model": "refine-sysml-v1",
+    "provider": "openai"
+  }'
+```
+
+Anthropic request example:
+
+```bash
+curl -s http://127.0.0.1:8000/v1/responses \
+  -H "Authorization: Bearer sysml_live_..." \
+  -H "Content-Type: application/json" \
+  -d '{
+    "input": "Design a compact battery-powered inspection drone that fits in a 30 cm cube and flies for 20 minutes.",
+    "model": "refine-sysml-v1",
+    "provider": "anthropic",
+    "upstream_model": "claude-sonnet-4-5-20250929"
+  }'
+```
+
+Check a stored request:
+
+```bash
+curl -s http://127.0.0.1:8000/v1/requests/resp_20260312_161200_abcd \
+  -H "Authorization: Bearer sysml_live_..."
+```
+
+Health check:
+
+```bash
+curl -s http://127.0.0.1:8000/healthz
+```
+
+## Repair Workflow
+
+The hosted API now supports a repair-oriented workflow:
+- accept raw SysML text
+- run SysIDE immediately
+- if the model already passes, return it unchanged with `iterations_completed = 0`
+- if it fails, feed the broken SysML plus real compiler diagnostics into the repair loop
+- persist the same request tracking and single-artifact bundle used by generation requests
+
+Repair metadata includes:
+- `metadata.operation = "repair"`
+- `metadata.initial_compiler_passed`
+- `metadata.diagnostics_summary`
+
+Design note:
+- [docs/ITERATION_STALL_POLICY.md](/Users/chancelavoie/Desktop/sysmlv2copilot/docs/ITERATION_STALL_POLICY.md)
+
+## Admin Frontend
+
+Run the Streamlit admin console:
+
+```bash
+streamlit run sysmlv2copilot_admin/app.py
+```
+
+It uses the real configured database and supports:
+- create users and issue API keys
+- rotate existing keys
+- inspect per-user usage totals
+- inspect overall usage and compiler performance
+- browse recent request activity
+- check live API health against a configured base URL
+
+More detail:
+- [docs/ADMIN_FRONTEND.md](/Users/chancelavoie/Desktop/sysmlv2copilot/docs/ADMIN_FRONTEND.md)
+- [docs/PYPI_RELEASE.md](/Users/chancelavoie/Desktop/sysmlv2copilot/docs/PYPI_RELEASE.md)
+
+## Artifact Storage
+
+Artifacts are stored under `ARTIFACT_ROOT`, defaulting to `./data/artifacts`. Each request gets a run directory with a single persisted artifact:
+- `request_artifact.json`
+
+That JSON bundle stores:
+- the original input text
+- the final SysML output
+- request statistics such as tokens, chars, duration, and iterations
+- provider/model metadata and any terminal error
+
+Each request registers exactly one row in the `artifacts` table. Temporary iteration files used during SysIDE checks are removed before persistence.
+
+## Tests
+
+Run the test suite with:
+
+```bash
+pytest
+```
+
+The tests mock the expensive upstream generation path and cover auth, request tracking, repair flow, artifacts, CLI operations, health reporting, packaging boundaries, and config validation.
+
+## Docker
+
+Build:
+
+```bash
+docker build \
+  --build-arg SYSIDE_PIP_SPEC='syside==<your-version>' \
+  --build-arg REQUIRE_SYSIDE=1 \
+  -t sysml-refinement-api .
+```
+
+Run:
+
+```bash
+docker run --rm -p 8000:8000 --env-file .env sysml-refinement-api
+```
+
+The container runs `alembic upgrade head` before starting `uvicorn`.
+
+## Azure And Supabase
+
+The repo is now prepared for:
+- Azure Container Apps for compute
+- Azure Container Registry for the private image
+- Azure Files for persistent artifacts
+- Supabase Postgres for metadata
+
+Relevant files:
+- [docs/AZURE_CONTAINER_APPS.md](/Users/chancelavoie/Desktop/sysmlv2copilot/docs/AZURE_CONTAINER_APPS.md)
+- [scripts/deploy_azure_container_app.sh](/Users/chancelavoie/Desktop/sysmlv2copilot/scripts/deploy_azure_container_app.sh)
+- [scripts/build_database_url.py](/Users/chancelavoie/Desktop/sysmlv2copilot/scripts/build_database_url.py)
+- [scripts/render_azure_containerapp_yaml.py](/Users/chancelavoie/Desktop/sysmlv2copilot/scripts/render_azure_containerapp_yaml.py)
+- [infra/supabase/create_service_role.sql](/Users/chancelavoie/Desktop/sysmlv2copilot/infra/supabase/create_service_role.sql)
+
+To build a Supabase-compatible SQLAlchemy URL:
+
+```bash
+python scripts/build_database_url.py \
+  --host db.<project-ref>.supabase.co \
+  --port 5432 \
+  --database postgres \
+  --user sysml_api_service \
+  --password 'replace-me'
+```
+
+To deploy to Azure Container Apps:
+
+```bash
+export BUILD_MODE=local-docker
+bash scripts/deploy_azure_container_app.sh
+```
+
+## Upstream Context
+
+The copied upstream context package lives in:
+- `context/upstream/refine_sysml.py`
+- `context/upstream/setup_pipeline_env.sh`
+- `context/upstream/pipeline_README.md`
+- `context/upstream/pipeline_HELP.md`
+- `context/upstream/env.example`
+- `context/examples/example_prompt.txt`
+- `context/examples/example_output.sysml`
+- `context/examples/example_run_log.json`
+
+That context is intentionally tight and keeps the original refinement flow visible without copying the whole older repository.