Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,13 @@

All notable changes to this project will be documented in this file.

## [1.1.0] - 2026-07-20

### Added

- Accessors for client state: `sessionPin()`/`setSessionPin()` and `newSession()` for reading, changing or regenerating the session pin after construction; `history()`/`setHistory()` for persisting and restoring conversations; and `writeHistory()`/`setWriteHistory()` for toggling history recording.
- `historyUsage()` totalling token usage across the calls that built the stored history.

## [1.0.0] - 2026-07-20

First stable release.
Expand All @@ -25,5 +32,6 @@ Initial release: a PHP port of [sthai-py](https://github.com/sitehostnz/sthai-py
- `models()`, `healthy()`, session pinning (explicit or auto-generated) and `SthAI\Image` data-URI helpers
- Offline test suite replaying fixtures captured from the live API, shared with sthai-py

[1.1.0]: https://github.com/sitehostnz/sthai-php/compare/v1.0.0...v1.1.0
[1.0.0]: https://github.com/sitehostnz/sthai-php/compare/v0.1.0...v1.0.0
[0.1.0]: https://github.com/sitehostnz/sthai-php/releases/tag/v0.1.0
8 changes: 8 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -56,6 +56,10 @@ $client->clearHistory();
$client->chat('Be brief: why is the sky blue?', systemPrompt: 'You are terse.');
```

The stored history can be read with `history()` and restored with `setHistory()`, so a conversation can be persisted and picked up later. `setWriteHistory(false)` stops `chat()` recording new turns (the stored history is kept and still sent); `writeHistory()` reads the current setting.

`historyUsage()` totals token usage across the calls that built the stored history. Each call resends the conversation so far, so input tokens count what the server processed (as billed), not unique tokens. `clearHistory()` and `setHistory()` reset the tally along with the turns it covered.

Thinking models can reason before answering; the reasoning rides along on the response:

```php
Expand Down Expand Up @@ -160,6 +164,10 @@ Pinning requests to a server session keeps routing consistent and helps caching.

```php
$client = new Client(autoSession: true);
echo $client->sessionPin(); // the pin in use, e.g. to persist it

$client->setSessionPin('my-pin'); // pin to a known session (null unpins)
$pin = $client->newSession(); // switch to a freshly generated pin
```

### Models and health
Expand Down
115 changes: 114 additions & 1 deletion src/Client.php
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,7 @@
use SthAI\Response\InferenceResponse;
use SthAI\Response\ModelCard;
use SthAI\Response\RerankResponse;
use SthAI\Response\Usage;
use SthAI\Transport\CurlTransport;
use SthAI\Transport\HttpResponse;
use SthAI\Transport\TransportInterface;
Expand Down Expand Up @@ -50,6 +51,9 @@ final class Client
/** @var array<int, array<string, mixed>> */
private array $chatHistory = [];

/** @var Usage[] usage of each call recorded into the stored history */
private array $historyUsage = [];

private ?InferenceResponse $lastResponse = null;

private TransportInterface $transport;
Expand Down Expand Up @@ -82,18 +86,126 @@ public function __construct(
$this->secure = $secure;
$this->sessionPin = $sessionPin;
if ($this->sessionPin === null && $autoSession) {
$this->sessionPin = bin2hex(random_bytes(24));
$this->sessionPin = self::generateSessionPin();
}
$this->writeHistory = $writeHistory;
$this->transport = $transport ?? new CurlTransport();
}

/**
* The session pin sent with requests, if any - whether passed in,
* generated by autoSession, or set after construction.
*/
public function sessionPin(): ?string
{
return $this->sessionPin;
}

/**
* Pin subsequent requests to a server session, or pass null to stop
* sending a pin.
*/
public function setSessionPin(?string $sessionPin): void
{
$this->sessionPin = $sessionPin;
}

/**
* Start a fresh session: generate a new random pin (as autoSession
* does), pin subsequent requests to it, and return it.
*/
public function newSession(): string
{
$this->sessionPin = self::generateSessionPin();

return $this->sessionPin;
}

/**
* A random session pin, as generated for autoSession.
*/
private static function generateSessionPin(): string
{
return bin2hex(random_bytes(24));
}

/**
* Discard the stored chat history.
*/
public function clearHistory(): void
{
$this->chatHistory = [];
$this->historyUsage = [];
}

/**
* The stored chat history: role/content message arrays, oldest first.
*
* @return array<int, array<string, mixed>>
*/
public function history(): array
{
return $this->chatHistory;
}

/**
* Replace the stored chat history, e.g. to restore a conversation
* persisted from history(). Each turn must be an array with 'role'
* and 'content' keys.
*
* @param array<int, mixed> $history
*/
public function setHistory(array $history): void
{
$turns = [];
foreach ($history as $turn) {
if (!is_array($turn) || !isset($turn['role']) || !array_key_exists('content', $turn)) {
throw new InvalidArgumentException(
"each history turn must be an array with 'role' and 'content' keys"
);
}
$turns[] = $turn;
}
$this->chatHistory = $turns;
// Restored turns carry no usage information, so the tally restarts
$this->historyUsage = [];
}

/**
* Total token usage across the calls that built the stored history.
*
* Each call resends the conversation so far, so input tokens count
* what the server processed (as billed), not unique tokens.
* clearHistory() and setHistory() reset the tally along with the
* turns it covered.
*/
public function historyUsage(): Usage
{
$total = new Usage();
foreach ($this->historyUsage as $usage) {
$total->inputTokens += $usage->inputTokens;
$total->outputTokens += $usage->outputTokens;
$total->cachedTokens += $usage->cachedTokens;
}

return $total;
}

/**
* Whether chat() records conversation turns.
*/
public function writeHistory(): bool
{
return $this->writeHistory;
}

/**
* Control whether chat() records conversation turns. Turning it off
* keeps the stored history; chat() still sends it.
*/
public function setWriteHistory(bool $writeHistory): void
{
$this->writeHistory = $writeHistory;
}

/**
Expand Down Expand Up @@ -171,6 +283,7 @@ public function chat(
'role' => 'assistant',
'content' => $decoded->choices[0]->message->content,
];
$this->historyUsage[] = $decoded->usage();
}

return $decoded;
Expand Down
85 changes: 85 additions & 0 deletions tests/ChatTest.php
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@
namespace SthAI\Tests;

use SthAI\Exception\HttpException;
use SthAI\Exception\InvalidArgumentException;
use SthAI\Response\InferenceResponse;
use SthAI\Tests\Support\ClientTestCase;

Expand Down Expand Up @@ -179,6 +180,90 @@ public function testClearHistory(): void
$this->assertSame(['user'], array_column($body['messages'], 'role'));
}

public function testHistoryGetterReturnsStoredTurns(): void
{
$fixture = $this->transport->register('chat_simple');
$client = $this->client();
$this->assertSame([], $client->history());

$client->chat('first');
$this->assertSame([
['role' => 'user', 'content' => 'first'],
['role' => 'assistant', 'content' => $fixture['response']['choices'][0]['message']['content']],
], $client->history());
}

public function testSetHistoryRestoresConversation(): void
{
$this->transport->register('chat_simple');
$client = $this->client();
$client->setHistory([
['role' => 'user', 'content' => 'earlier question'],
['role' => 'assistant', 'content' => 'earlier answer'],
]);

$client->chat('follow-up');
$body = $this->transport->lastCall()->body;
$this->assertNotNull($body);
$this->assertSame(['user', 'assistant', 'user'], array_column($body['messages'], 'role'));
$this->assertSame('earlier question', $body['messages'][0]['content']);
$this->assertSame('follow-up', $body['messages'][2]['content']);
}

public function testSetHistoryRejectsMalformedTurns(): void
{
$this->expectException(InvalidArgumentException::class);
$this->expectExceptionMessage('history turn');
$this->client()->setHistory([['role' => 'user']]);
}

public function testWriteHistoryAccessors(): void
{
$this->transport->register('chat_simple');
$client = $this->client();
$this->assertTrue($client->writeHistory());

$client->setWriteHistory(false);
$this->assertFalse($client->writeHistory());
$client->chat('first');
$this->assertSame([], $client->history());
}

public function testHistoryUsageAccumulates(): void
{
$fixture = $this->transport->register('chat_simple');
$client = $this->client();
$this->assertSame(0, $client->historyUsage()->inputTokens);

$client->chat('first');
$client->chat('second');
$usage = $fixture['response']['usage'];
$total = $client->historyUsage();
$this->assertSame($usage['prompt_tokens'] * 2, $total->inputTokens);
$this->assertSame($usage['completion_tokens'] * 2, $total->outputTokens);
}

public function testHistoryUsageExcludesUnrecordedCalls(): void
{
$this->transport->register('chat_simple');
$client = $this->client();
$client->chat('standalone', 'Qwen/Qwen3.6-27B', null, null, false, null, [], [], false);
$this->assertSame(0, $client->historyUsage()->inputTokens);
}

public function testHistoryUsageResetsWithHistory(): void
{
$this->transport->register('chat_simple');
$client = $this->client();
$client->chat('first');
$client->clearHistory();
$this->assertSame(0, $client->historyUsage()->inputTokens);

$client->chat('again');
$client->setHistory([['role' => 'user', 'content' => 'restored']]);
$this->assertSame(0, $client->historyUsage()->inputTokens);
}

public function testFailedCallDoesNotWriteHistory(): void
{
$this->transport->register('error_bad_model');
Expand Down
38 changes: 38 additions & 0 deletions tests/ClientCoreTest.php
Original file line number Diff line number Diff line change
Expand Up @@ -83,6 +83,44 @@ public function testAutoSessionGeneratesPin(): void
$this->assertTrue(ctype_xdigit($pin));
}

public function testSessionPinAccessors(): void
{
$this->transport->register('health');
$client = $this->client();
$this->assertNull($client->sessionPin());

$client->setSessionPin('my-pin');
$this->assertSame('my-pin', $client->sessionPin());
$client->healthy();
$this->assertSame('my-pin', $this->transport->lastCall()->headers[Client::SESSION_PIN_HEADER]);

$client->setSessionPin(null);
$this->assertNull($client->sessionPin());
$client->healthy();
$this->assertArrayNotHasKey(Client::SESSION_PIN_HEADER, $this->transport->lastCall()->headers);
}

public function testAutoSessionPinIsReadable(): void
{
$pin = $this->client(['autoSession' => true])->sessionPin();
$this->assertNotNull($pin);
$this->assertSame(48, strlen($pin));
$this->assertTrue(ctype_xdigit($pin));
}

public function testNewSessionGeneratesAndSendsPin(): void
{
$client = $this->client(['sessionPin' => 'old-pin']);
$pin = $client->newSession();
$this->assertSame(48, strlen($pin));
$this->assertTrue(ctype_xdigit($pin));
$this->assertSame($pin, $client->sessionPin());

$this->transport->register('health');
$client->healthy();
$this->assertSame($pin, $this->transport->lastCall()->headers[Client::SESSION_PIN_HEADER]);
}

public function testHealthyTrueOn200(): void
{
$this->transport->register('health');
Expand Down