Metadata-Version: 2.4
Name: jijzeptai
Version: 0.1.0
Summary: Python client SDK for the JijZept AI Solver HTTP API.
Keywords: jijzeptai,jijmodeling,ommx,optimization,solver,jijzeptsolver
Author: JIJ Inc.
Author-email: JIJ Inc. <info@j-ij.com>
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Typing :: Typed
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Dist: jijmodeling>=2.5,<3
Requires-Dist: ommx>=2.6.1,<3
Requires-Dist: requests>=2.32,<3
Requires-Python: >=3.11, <3.15
Description-Content-Type: text/markdown

# jijzeptai

`jijzeptai` is the Python SDK for submitting optimization jobs through JijZept
AI. It supports CPython 3.11, 3.12, 3.13, and 3.14.

## Install

With uv:

```bash
uv add jijzeptai
```

With pip:

```bash
python -m pip install jijzeptai
```

JijModeling and OMMX are included as required dependencies.

## Create and configure an API token

In JijZept AI, open the account menu and choose API Tokens. Create a token for
the current Organization. The value appears only once, so copy it into your
environment with the production JijZept AI URL and do not put it in source
code:

```bash
export JIJZEPTAI_BASE_URL="https://ai.jijzept.com"
export JIJZEPTAI_API_TOKEN="jzsa_..."
```

`DeveloperClient` reads these variables by default. You can also pass
`base_url="https://ai.jijzept.com"` and `api_token` as constructor arguments
when that fits your program better.

## Minimal model workflow

This flow deploys a reusable JijModeling model, submits input data, waits for
optimization, and downloads the solution. Deploying a model requires an Admin
or Developer Organization Role. If your role is User, ask an Admin or Developer
to deploy the model and share its name and tag, then call
`submit_job_by_deployed_model` with those values (skip `deploy_model`).

```python
import jijmodeling as jm

from jijzeptai import DeveloperClient


# Define a reusable knapsack model.
@jm.Problem.define("knapsack", sense=jm.ProblemSense.MAXIMIZE)
def knapsack(problem: jm.DecoratedProblem):
    values = problem.Float(ndim=1)
    item_count = values.len_at(0)
    weights = problem.Float(shape=(item_count,))
    capacity = problem.Float()
    selected = problem.BinaryVar(
        "selected",
        shape=(item_count,),
        description="item selected",
    )
    problem += jm.sum(values * selected)
    problem += problem.Constraint(
        "capacity",
        jm.sum(weights * selected) <= capacity,
    )


# Create the SDK client for JijZept AI.
client = DeveloperClient()
# Publish the model so the Organization can run it with new input later.
model = client.deploy_model("knapsack", "demo", knapsack)
# Start an optimization job with concrete input values.
job = client.submit_job_by_deployed_model(
    model.name,
    model.tag,
    {
        "values": [10.0, 20.0, 15.0, 30.0],
        "weights": [2.0, 3.0, 5.0, 7.0],
        "capacity": 10.0,
    },
)
# Wait until the job succeeds, then download the solution.
finished = client.wait_for_success(job.job_id)
solution = client.download_solution(finished.job_id)
print(solution.extract_decision_variables("selected"))  # selected items
print(solution.objective)  # best objective value
print(solution.feasible)  # True when all constraints hold
```

## Organization roles

- Admin and Developer: deploy, update, archive, and unarchive models; submit a
  JijModeling problem or an OMMX problem file without deploying a model first;
  run deployed models.
- User: inspect and run deployed models.

Deployed models belong to the Organization. Jobs, results, and cancellation
stay private to the user who submitted the job.

## Errors

Catch `JijZeptAIError` for failures raised by this package. Invalid arguments
raise `TypeError` or `ValueError`.

```python
from jijzeptai import JijZeptAIError, TransportError

try:
    finished = client.wait_for_success(job.job_id)
except TransportError as error:
    print(f"Network request failed: {error}")
except JijZeptAIError as error:
    print(f"JijZept AI operation failed: {error}")
```

## License

- [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0)

Apache-2.0 covers the published `jijzeptai` package. It does not license the
JijZept AI hosted service, API tokens, user models or data, service terms, or
JIJ Inc. trademarks and the JijZept AI product name.
