### Debug Swift Build with Verbose Output

Source: https://github.com/domano/fundament/blob/master/docs/GettingStarted.md

This command builds the Swift project with verbose linker flags, useful for debugging shim loading failures or inspecting build configurations. It helps in diagnosing issues related to missing frameworks or framework paths.

```bash
swift build -Xswiftc -v
```

--------------------------------

### Build Example Binaries - Bash

Source: https://github.com/domano/fundament/blob/master/context/operations/build/toolchain.md

Explicitly compiles example binaries for the Domano Fund project. This includes 'simple', 'structured', and 'streaming' examples.

```bash
make examples
```

--------------------------------

### Go Example: Simple Prompt/Response and Logging

Source: https://github.com/domano/fundament/blob/master/PLAN.md

Demonstrates the basic usage of the Domano Fundament project by showing a simple prompt and response interaction, as well as logging the availability status of the language model.

```go
package main

import (
    "fmt"
    "log"
    "path/to/fundament"
)

func main() {
    if fund.IsAvailable() {
        fmt.Println("Model is available.")
    }
    
    session, err := fund.NewSession()
    if err != nil {
        log.Fatalf("Failed to create session: %v", err)
    }
    defer session.Destroy()

    response, err := session.Respond(context.Background(), "What is the capital of France?")
    if err != nil {
        log.Fatalf("Failed to get response: %v", err)
    }
    fmt.Printf("Response: %s\n", response)
}
```

--------------------------------

### Go Example: Streaming Incremental Chunks

Source: https://github.com/domano/fundament/blob/master/PLAN.md

Provides an example of consuming and printing incremental chunks received from a streaming response. This demonstrates how to handle the stream of data as it arrives, including identifying the final chunk.

```go
package main

import (
    "context"
    "fmt"
    "log"
    "path/to/fundament"
)

func main() {
    session, err := fund.NewSession()
    if err != nil {
        log.Fatalf("Failed to create session: %v", err)
    }
    defer session.Destroy()

    chunkChan, err := session.RespondStream(context.Background(), "Tell me a story")
    if err != nil {
        log.Fatalf("Failed to start stream: %v", err)
    }

    for chunk := range chunkChan {
        fmt.Printf("%s", chunk.Data)
        if chunk.IsFinal {
            fmt.Println("\nStream finished.")
            break
        }
    }
}
```

--------------------------------

### Go Example: Structured Generation with Schema

Source: https://github.com/domano/fundament/blob/master/PLAN.md

Illustrates how to perform structured generation by utilizing JSON schemas derived from Go struct annotations. The example shows passing these schemas to the Swift shim for generating data that conforms to the specified structure.

```go
package main

import (
    "encoding/json"
    "fmt"
    "log"
    "path/to/fundament"
)

type Location struct {
    City    string `json:"city"`
    Country string `json:"country"`
}

func main() {
    schema, err := json.Marshal(Location{})
    if err != nil {
        log.Fatalf("Failed to marshal schema: %v", err)
    }

    session, err := fund.NewSession()
    if err != nil {
        log.Fatalf("Failed to create session: %v", err)
    }
    defer session.Destroy()

    // Assuming a method like GenerateStructured exists
    var result Location
    err = session.GenerateStructured(context.Background(), "Generate a location", schema, &result)
    if err != nil {
        log.Fatalf("Failed to generate structured output: %v", err)
    }
    fmt.Printf("Generated Location: %+v\n", result)
}
```

--------------------------------

### Install Fundament Go Module

Source: https://github.com/domano/fundament/blob/master/README.md

This command installs the Fundament Go module, which provides the necessary libraries to interact with Apple's on-device SystemLanguageModel from Go. Ensure you have Go 1.25+ and CGO_ENABLED=1 set.

```bash
go get github.com/domano/fundament
```

--------------------------------

### Build and Test Workflow Commands (Bash)

Source: https://context7.com/domano/fundament/llms.txt

Provides bash commands for managing the build and test process of the project. This includes building Swift and Go components, running unit and integration tests, and building all examples.

```bash
# Build Swift shim (required after modifying Swift sources)
make swift

# Build Go components (CGO-free via purego)
make go

# Run unit tests (platform-independent)
make test

# Run integration tests (requires macOS 26 + Apple Intelligence)
make integration

# Build all examples
make examples

```

--------------------------------

### Structured Output with Fundament in Go

Source: https://github.com/domano/fundament/blob/master/README.md

Illustrates how to request structured data from the Fundament model by defining a JSON schema on the fly. The `RespondStructured` method allows you to get strongly typed data back, which is then printed as a JSON string.

```go
schemaDefinition := map[string]any{
	"name": "TravelPlan",
	"properties": []map[string]any{
		{
			"name": "destination",
			"schema": map[string]any{
				"type": "string",
			},
		},
		// ...
	},
}
schemaBytes, _ := json.Marshal(schemaDefinition)
schema, _ := fundament.SchemaFromRawJSON(schemaBytes)

res, err := session.RespondStructured(ctx, "Plan a 2-day trip to Kyoto in autumn", schema)
fmt.Println(string(res.JSON))
```

--------------------------------

### Go: Structured Response with JSON Schema

Source: https://context7.com/domano/fundament/llms.txt

This Go code snippet demonstrates how to generate structured responses from a language model using a predefined JSON schema. It requires the 'context', 'encoding/json', 'fmt', 'log', 'time', and 'github.com/domano/fundament' packages. The function defines a schema for a 'TravelPlan' and uses it to get a structured recommendation for a trip to Kyoto.

```go
package main

import (
    "context"
    "encoding/json"
    "fmt"
    "log"
    "time"
    "github.com/domano/fundament"
)

func main() {
    availability, err := fundament.CheckAvailability()
    if err != nil {
        log.Fatalf("check availability: %v", err)
    }
    if availability.State != fundament.AvailabilityReady {
        log.Fatalf("system language model unavailable: %s", availability)
    }

    session, err := fundament.NewSession(fundament.SessionOptions{
        Instructions: "You produce structured travel recommendations.",
    })
    if err != nil {
        log.Fatalf("new session: %v", err)
    }
    defer session.Close()

    // Define schema for structured output
    schemaDefinition := map[string]any{
        "name":        "TravelPlan",
        "description": "A short trip plan with destination, highlights, and packing list.",
        "properties": []map[string]any{
            {
                "name": "destination",
                "schema": map[string]any{
                    "type":        "string",
                    "description": "City and country for the trip.",
                },
            },
            {
                "name": "highlights",
                "schema": map[string]any{
                    "type":            "array",
                    "description":     "A list of must-see highlights.",
                    "minimumElements": 2,
                    "maximumElements": 4,
                    "items": map[string]any{
                        "type":        "string",
                        "description": "Concise highlight.",
                    },
                },
            },
            {
                "name": "packingList",
                "schema": map[string]any{
                    "type":        "array",
                    "description": "Packing list tailored to the itinerary.",
                    "items": map[string]any{
                        "type":        "string",
                        "description": "Single packing list item.",
                    },
                },
            },
        },
    }

    schemaBytes, err := json.Marshal(schemaDefinition)
    if err != nil {
        log.Fatalf("marshal schema: %v", err)
    }
    schema, err := fundament.SchemaFromRawJSON(schemaBytes)
    if err != nil {
        log.Fatalf("schema: %v", err)
    }

    ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
    defer cancel()

    res, err := session.RespondStructured(ctx, "Plan a 2-day trip to Kyoto in autumn", schema)
    if err != nil {
        log.Fatalf("respond structured: %v", err)
    }

    fmt.Println(string(res.JSON))
    // Output example:
    // {"destination":"Kyoto, Japan","highlights":["Fushimi Inari Shrine","Kinkaku-ji Temple","Arashiyama Bamboo Grove"],"packingList":["Comfortable walking shoes","Light jacket","Camera"]}
}

```

--------------------------------

### Check Fundament Model Availability in Go

Source: https://github.com/domano/fundament/blob/master/README.md

This Go code snippet shows how to check if the on-device model required by Fundament is available and ready for use. It's crucial to call this before starting a session to handle cases where the model might be downloading or the device is not eligible.

```go
availability, err := fundament.CheckAvailability()
// ... Handle availability and errors here
```

--------------------------------

### Unmarshal Structured Output to Go Types with fundament

Source: https://context7.com/domano/fundament/llms.txt

This snippet demonstrates how to generate structured output from a language model and automatically unmarshal it into a strongly-typed Go struct using the fundament library. It defines a Go struct for a TravelPlan and uses a JSON schema to guide the unmarshalling process. The function `session.RespondStructuredInto` is key here, taking the context, prompt, schema, and a pointer to the Go struct as arguments. Ensure the schema accurately reflects the Go struct's JSON tags for successful unmarshalling.

```go
package main

import (
    "context"
    "encoding/json"
    "fmt"
    "log"
    "time"
    "github.com/domano/fundament"
)

type TravelPlan struct {
    Destination string   `json:"destination"`
    Highlights  []string `json:"highlights"`
    PackingList []string `json:"packingList"`
}

func main() {
    availability, err := fundament.CheckAvailability()
    if err != nil {
        log.Fatalf("check availability: %v", err)
    }
    if availability.State != fundament.AvailabilityReady {
        log.Fatalf("system language model unavailable: %s", availability)
    }

    session, err := fundament.NewSession(fundament.SessionOptions{
        Instructions: "You produce structured travel recommendations.",
    })
    if err != nil {
        log.Fatalf("new session: %v", err)
    }
    defer session.Close()

    schemaDefinition := map[string]any{
        "name": "TravelPlan",
        "properties": []map[string]any{
            {"name": "destination", "schema": map[string]any{"type": "string"}},
            {
                "name": "highlights",
                "schema": map[string]any{
                    "type":            "array",
                    "minimumElements": 2,
                    "maximumElements": 4,
                    "items":           map[string]any{"type": "string"},
                },
            },
            {
                "name": "packingList",
                "schema": map[string]any{
                    "type":  "array",
                    "items": map[string]any{"type": "string"},
                },
            },
        },
    }

    schemaBytes, _ := json.Marshal(schemaDefinition)
    schema, err := fundament.SchemaFromRawJSON(schemaBytes)
    if err != nil {
        log.Fatalf("schema: %v", err)
    }

    ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
    defer cancel()

    var plan TravelPlan
    err = session.RespondStructuredInto(ctx, "Plan a 2-day trip to Tokyo", schema, &plan)
    if err != nil {
        log.Fatalf("respond structured into: %v", err)
    }

    fmt.Printf("Destination: %s\n", plan.Destination)
    fmt.Printf("Highlights: %v\n", plan.Highlights)
    fmt.Printf("Packing: %v\n", plan.PackingList)
    // Output example:
    // Destination: Tokyo, Japan
    // Highlights: [Senso-ji Temple Shibuya Crossing Tokyo Skytree]
    // Packing: [Comfortable shoes Travel adapter Umbrella]
}

```

--------------------------------

### Create and Use Fundament Session in Go

Source: https://github.com/domano/fundament/blob/master/README.md

Demonstrates the basic usage of the Fundament library by creating a new session with specific instructions, sending a prompt, and deferring the session's closure. It includes error handling for session creation and response generation.

```go
session, err := fundament.NewSession(fundament.SessionOptions{
    Instructions: "You are a concise assistant that answers in one sentence.",
})
if err != nil {
    log.Fatal(err)
}
defersession.Close()

ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
deferscancel()

resp, err := session.Respond(ctx, "Explain what a markov chain is.")
if err != nil {
    log.Fatal(err)
}

fmt.Println(resp.Text)
```

--------------------------------

### Session Management and Basic Response

Source: https://github.com/domano/fundament/blob/master/README.md

APIs for creating a session and handling basic prompt-response interactions.

```APIDOC
## fundament.NewSession

### Description
Creates a session bound to the default system language model.

### Method
`func NewSession(opts SessionOptions) *Session`

### Endpoint
N/A (Function call)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```go
session := fundament.NewSession(fundament.SessionOptions{})
```

### Response
#### Success Response (N/A)
Returns a pointer to a `Session` object.

#### Response Example
```go
// *Session object is returned
```

## (*Session).Respond

### Description
Handles a single prompt and returns a response from the language model.

### Method
`func (s *Session) Respond(ctx context.Context, prompt string, opts ...GenerationOption) (string, error)`

### Endpoint
N/A (Method call on Session object)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```go
response, err := session.Respond(ctx, "What is the weather today?")
```

### Response
#### Success Response (200)
- **response** (string) - The text response from the language model.
- **err** (error) - An error if the response could not be generated.

#### Response Example
```json
{
  "response": "The weather today is sunny."
}
```
```

--------------------------------

### Troubleshooting Fundament

Source: https://github.com/domano/fundament/blob/master/README.md

Common issues and solutions for using the Fundament API.

```APIDOC
## Troubleshooting Fundament

### Unavailable Model

- **Issue**: `fundament.CheckAvailability()` returns `AvailabilityUnavailable`.
- **Reason**: Device not eligible, Apple Intelligence disabled, or model not ready.
- **Solution**: Handle this condition before making prompts. Check the availability status and implement appropriate fallback or user messaging.

### Shim Loading Issues

- **Issue**: Errors related to the fundament shim loading.
- **Solution 1**: Remove the shim cache directory: `~/Library/Caches/fundament-shim` (or `$XDG_CACHE_HOME/fundament-shim`) and rerun.
- **Solution 2**: If the error persists, re-run `make swift` to ensure `internal/shimloader/prebuilt/libFundamentShim.dylib` and its manifest match the embedded hash.

### Structured Schema Errors

- **Issue**: Errors when using structured schemas with `RespondStructured` or `RespondStructuredInto`.
- **Supported Shapes**: Objects, arrays, enums, and primitive fields.
- **Unsupported Shapes**: References, numeric guides.
- **Solution**: Ensure your schema uses supported shapes. The shim will return descriptive errors for unsupported structures.
```

--------------------------------

### Schema Generation Helpers

Source: https://github.com/domano/fundament/blob/master/README.md

Helper functions for constructing generation schemas.

```APIDOC
## fundament.SchemaFromRawJSON

### Description
Helper function to build a generation schema from raw JSON data.

### Method
`func SchemaFromRawJSON(data []byte) interface{}`

### Endpoint
N/A (Function call)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```go
schemaJSON := []byte(`{\"type\": \"object\", \"properties\": {\"name\": {\"type\": \"string\"}}}`)
schema := fundament.SchemaFromRawJSON(schemaJSON)
```

### Response
#### Success Response (N/A)
Returns an object representing the schema.

#### Response Example
```go
// Schema object is returned
```

## fundament.SchemaFromValue

### Description
Helper function to build a generation schema from a Go value.

### Method
`func SchemaFromValue(value interface{}) interface{}`

### Endpoint
N/A (Function call)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```go
type Person struct {
    Name string `json:"name"`
}
schema := fundament.SchemaFromValue(Person{})
```

### Response
#### Success Response (N/A)
Returns an object representing the schema.

#### Response Example
```go
// Schema object is returned
```
```

--------------------------------

### Compile Swift Shim - Bash

Source: https://github.com/domano/fundament/blob/master/context/operations/build/toolchain.md

Compiles the Swift shim for the Domano Fund project. This command sets deployment targets, disables sandboxing, and produces a dynamic library. It also packages the shim for use by Go consumers.

```bash
make swift
```

--------------------------------

### Go Session Handle Wrapper with Finalizer

Source: https://github.com/domano/fundament/blob/master/PLAN.md

Implements a Go session handle wrapper using `uintptr` which calls `C.fundament_session_create` for construction. `runtime.SetFinalizer` is used to ensure automatic session destruction when the handle is no longer referenced.

```go
type sessionHandle uintptr

func newSession() sessionHandle {
    handle := C.fundament_session_create()
    return sessionHandle(handle)
}

func (h sessionHandle) destroy() {
    C.fundament_session_destroy(C.fundament_session_t(h))
}

func init() {
    runtime.SetFinalizer(sessionHandle(0), (*sessionHandle).destroy) // Simplified for example
}
```

--------------------------------

### Generation Options

Source: https://github.com/domano/fundament/blob/master/README.md

Functions to configure generation parameters.

```APIDOC
## Fundament Generation Options

### Description
Options that can be passed to session methods to control generation parameters like temperature, top-p, and max tokens.

### Method
- `fundament.WithTemperature(temperature float32)`
- `fundament.WithTopP(topP float32)`
- `fundament.WithMaxTokens(maxTokens int)`
- `fundament.WithStopSequences(stopSequences ...string)`

### Endpoint
N/A (Function calls, used as options)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```go
response, err := session.Respond(ctx, "Write a short story.",
    fundament.WithTemperature(0.7),
    fundament.WithMaxTokens(500))
```

### Response
#### Success Response (N/A)
These functions return options that are applied during generation.

#### Response Example
```go
// Options are applied internally, no direct response body
```
```

--------------------------------

### Swift Availability and Metadata Functions

Source: https://github.com/domano/fundament/blob/master/PLAN.md

Provides functions to check the availability status of the language model, query locale support, access guardrails information, and manage the download and compilation of adapters.

```swift
func fundament_is_available() -> Bool
func fundament_supports_locale(locale: UnsafePointer<CChar>) -> Bool
func fundament_get_guardrails() -> Guardrails
func fundament_download_adapter(id: UnsafePointer<CChar>) -> Bool
func fundament_compile_adapter(id: UnsafePointer<CChar>) -> Bool
```

--------------------------------

### Create Fundament Session and Generate Single-Turn Response in Go

Source: https://context7.com/domano/fundament/llms.txt

This Go code snippet illustrates how to create a language model session using the Fundament library and then generate a single-turn text response. It includes checking model availability, setting custom instructions for the assistant, and handling context with a timeout for the response generation.

```go
package main

import (
    "context"
    "fmt"
    "log"
    "time"
    "github.com/domano/fundament"
)

func main() {
    // Check availability first
    availability, err := fundament.CheckAvailability()
    if err != nil {
        log.Fatalf("check availability: %v", err)
    }
    if availability.State != fundament.AvailabilityReady {
        log.Fatalf("system language model unavailable: %s", availability)
    }

    // Create session with instructions
    session, err := fundament.NewSession(fundament.SessionOptions{
        Instructions: "You are a concise assistant that answers in one sentence.",
    })
    if err != nil {
        log.Fatalf("new session: %v", err)
    }
    defer session.Close()

    // Create context with timeout
    ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
    defer cancel()

    // Generate response
    response, err := session.Respond(ctx, "Explain what a markov chain is.")
    if err != nil {
        log.Fatalf("respond: %v", err)
    }

    fmt.Println("Assistant:", response.Text)
    // Output example: "Assistant: A Markov chain is a mathematical system that transitions between states where the probability of each state depends only on the previous state."
}
```

--------------------------------

### Streaming Responses with Fundament in Go

Source: https://github.com/domano/fundament/blob/master/README.md

Demonstrates how to receive streaming text completions from the Fundament model. The `RespondStream` method returns a channel that yields text chunks incrementally. This is useful for real-time applications where immediate feedback is desired.

```go
stream, err := session.RespondStream(
	ctx,
	"Write a limerick about coding Go bindings for Swift models.",
	fundament.WithTemperature(0.7),
)

for chunk := range stream {
	if chunk.Err != nil {
		log.Fatal(chunk.Err)
	}
	fmt.Print(chunk.Text, " ")
	if chunk.Final {
		fmt.Println("\n-- end --")
	}
}
```

--------------------------------

### Build Go Packages - Bash

Source: https://github.com/domano/fundament/blob/master/context/operations/build/toolchain.md

Builds all Go packages within the Domano Fund project. This command relies on the Swift shim artifact created in the previous step for linking. Ensure Go environment variables like GOCACHE and GOMODCACHE are set if operating in a sandbox.

```bash
make go
```

--------------------------------

### Run Unit Tests - Bash

Source: https://github.com/domano/fundament/blob/master/context/operations/build/toolchain.md

Executes unit tests for the Domano Fund project using Go's testing framework. This command verifies the correctness of individual Go code units.

```bash
make test
```

--------------------------------

### Web Chat Server Logic with Fundament in Go

Source: https://github.com/domano/fundament/blob/master/README.md

This Go snippet illustrates the server-side logic for a web chat application using Fundament. It handles incoming HTTP requests, appends user prompts, sends them to the Fundament session, and updates the conversation with the assistant's response.

```go
func (s *chatServer) handleChat(w http.ResponseWriter, r *http.Request) {
	// ...
	prompt := s.appendUserAndPrompt(strings.TrimSpace(r.FormValue("message")))

	ctx, cancel := context.WithTimeout(r.Context(), 45*time.Second)
	deferscancel()

	resp, err := s.session.Respond(ctx, prompt)
	if err != nil {
		s.appendSystemMessage(fmt.Sprintf("Response error: %v", err))
	} else {
		s.appendAssistantMessage(resp.Text)
	}
	// ...
}
```

--------------------------------

### Control Generation with Temperature, Top-P, and Max Tokens in Go

Source: https://context7.com/domano/fundament/llms.txt

This Go code snippet shows how to control the creativity and determinism of text generation using the `fundament.Respond` function. It demonstrates setting low and high temperatures for deterministic and creative outputs, respectively, along with `WithTopP` and `WithMaxTokens` to refine the generation process. Ensure the fundament library is imported and the system language model is available.

```go
package main

import (
    "context"
    "fmt"
    "log"
    "time"
    "github.com/domano/fundament"
)

func main() {
    availability, err := fundament.CheckAvailability()
    if err != nil {
        log.Fatalf("check availability: %v", err)
    }
    if availability.State != fundament.AvailabilityReady {
        log.Fatalf("system language model unavailable: %s", availability)
    }

    session, err := fundament.NewSession(fundament.SessionOptions{
        Instructions: "You are a creative writing assistant.",
    })
    if err != nil {
        log.Fatalf("new session: %v", err)
    }
    defer session.Close()

    ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
    defer cancel()

    // Low temperature for deterministic output
    response1, err := session.Respond(
        ctx,
        "Write a one-sentence product tagline for a smart coffee maker.",
        fundament.WithTemperature(0.2),
        fundament.WithMaxTokens(50),
    )
    if err != nil {
        log.Fatalf("respond: %v", err)
    }
    fmt.Println("Deterministic:", response1.Text)

    // High temperature for creative output
    response2, err := session.Respond(
        ctx,
        "Write a one-sentence product tagline for a smart coffee maker.",
        fundament.WithTemperature(0.9),
        fundament.WithTopP(0.95),
        fundament.WithMaxTokens(50),
    )
    if err != nil {
        log.Fatalf("respond: %v", err)
    }
    fmt.Println("Creative:", response2.Text)
}

```

--------------------------------

### Achieve Reproducible Generation with Seed in Go

Source: https://context7.com/domano/fundament/llms.txt

This Go code snippet demonstrates how to ensure reproducible generation results by using a deterministic seed with the `fundament.Respond` function. By providing a specific integer value to `fundament.WithSeed`, you can obtain the same output for the same prompt and generation settings on subsequent runs. This is useful for testing and debugging generative models. Dependencies include the fundament library and standard Go packages for context and time management.

```go
package main

import (
    "context"
    "fmt"
    "log"
    "time"
    "github.com/domano/fundament"
)

func main() {
    availability, err := fundament.CheckAvailability()
    if err != nil {
        log.Fatalf("check availability: %v", err)
    }
    if availability.State != fundament.AvailabilityReady {
        log.Fatalf("system language model unavailable: %s", availability)
    }

    session, err := fundament.NewSession(fundament.SessionOptions{
        Instructions: "You are a creative writing assistant.",
    })
    if err != nil {
        log.Fatalf("new session: %v", err)
    }
    defer session.Close()

    ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
    defer cancel()

    // Deterministic seeding for reproducible results
    response3, err := session.Respond(
        ctx,
        "Generate a random tech startup name.",
        fundament.WithSeed(12345),
        fundament.WithTemperature(0.7),
    )
    if err != nil {
        log.Fatalf("respond: %v", err)
    }
    fmt.Println("Seeded:", response3.Text)
}

```

--------------------------------

### Structured and Streamed Responses

Source: https://github.com/domano/fundament/blob/master/README.md

APIs for receiving responses in structured JSON format or as a stream of updates.

```APIDOC
## (*Session).RespondStructured

### Description
Returns a structured JSON response based on a provided schema.

### Method
`func (s *Session) RespondStructured(ctx context.Context, prompt string, schema interface{}, opts ...GenerationOption) (string, error)`

### Endpoint
N/A (Method call on Session object)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```go
var result map[string]interface{}
response, err := session.RespondStructured(ctx, "Describe a cat.", "{\"name\": \"string\", \"age\": \"number\"}")
```

### Response
#### Success Response (200)
- **response** (string) - A JSON string representing the structured response.
- **err** (error) - An error if the structured response could not be generated.

#### Response Example
```json
{
  "response": "{\"name\": \"Whiskers\", \"age\": 3}"
}
```

## (*Session).RespondStructuredInto

### Description
Unmarshals the structured JSON response directly into a Go value.

### Method
`func (s *Session) RespondStructuredInto(ctx context.Context, prompt string, schema interface{}, target interface{}, opts ...GenerationOption) error`

### Endpoint
N/A (Method call on Session object)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```go
type Cat struct {
    Name string `json:"name"`
    Age  int    `json:"age"`
}
var myCat Cat
err := session.RespondStructuredInto(ctx, "Describe a cat.", fundament.SchemaFromValue(Cat{}), &myCat)
```

### Response
#### Success Response (200)
- **err** (error) - An error if the structured response could not be generated or unmarshaled.

#### Response Example
```go
// No explicit response body, error is checked
```

## (*Session).RespondStream

### Description
Returns a channel of streaming updates for the response.

### Method
`func (s *Session) RespondStream(ctx context.Context, prompt string, opts ...GenerationOption) (<-chan StreamingUpdate, error)`

### Endpoint
N/A (Method call on Session object)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```go
stream, err := session.RespondStream(ctx, "Describe the process of photosynthesis.")
for update := range stream {
    fmt.Print(update.Delta)
}
```

### Response
#### Success Response (200)
- **StreamingUpdate channel** - A channel that yields `StreamingUpdate` objects.
- **err** (error) - An error if the stream could not be initiated.

#### Response Example
```go
// No explicit response body, streaming updates are received via channel
```
```

--------------------------------

### Go Build Tags for Platform-Specific Tests

Source: https://github.com/domano/fundament/blob/master/PLAN.md

Utilizes Go build tags to conditionally compile tests based on the operating system and CGO availability. This allows for macOS-specific tests (`darwin && cgo`) and fallback tests for non-macOS environments (`!darwin`).

```go
//go:build darwin && cgo
// This test runs only on macOS with CGO enabled.

//go:build !darwin
// This test runs on non-macOS systems, providing fallback errors.
```

--------------------------------

### Go Streaming to Channel Mapping

Source: https://github.com/domano/fundament/blob/master/PLAN.md

Maps the callback-based streaming API to Go channels. It utilizes `runtime/cgo.NewHandle` to pass channel references into C code, ensuring thread-safety and adherence to cgo callback best practices.

```go
type StreamChunk struct {
    Data string
    IsFinal bool
}

func (s *Session) RespondStream(ctx context.Context, prompt string) (<-chan StreamChunk, error) {
    // ... implementation using cgo.NewHandle and channels
    return nil, nil
}
```

--------------------------------

### Run Integration Tests - Bash

Source: https://github.com/domano/fundament/blob/master/context/operations/build/toolchain.md

Runs integration tests for the Domano Fund project on macOS 26 hardware with Apple Intelligence enabled. This command exercises the live Swift bridge against SystemLanguageModel and helps identify issues related to entitlements, availability, or ABI drift.

```bash
make integration
```

--------------------------------

### Stream Language Model Responses Incrementally with fundament

Source: https://context7.com/domano/fundament/llms.txt

This Go code snippet demonstrates how to receive a streaming response from a language model, allowing for incremental delivery of text chunks. This is useful for providing real-time user feedback. The `session.RespondStream` function is used, returning a channel that yields `Chunk` objects. Each chunk contains a piece of the response text, an error if one occurred, and a boolean indicating if it's the final chunk. The code iterates over this channel, printing each text chunk as it arrives.

```go
package main

import (
    "context"
    "fmt"
    "log"
    "time"
    "github.com/domano/fundament"
)

func main() {
    availability, err := fundament.CheckAvailability()
    if err != nil {
        log.Fatalf("check availability: %v", err)
    }
    if availability.State != fundament.AvailabilityReady {
        log.Fatalf("system language model unavailable: %s", availability)
    }

    session, err := fundament.NewSession(fundament.SessionOptions{
        Instructions: "You compose cheerful limericks.",
    })
    if err != nil {
        log.Fatalf("new session: %v", err)
    }
    defer session.Close()

    ctx, cancel := context.WithTimeout(context.Background(), 45*time.Second)
    defer cancel()

    stream, err := session.RespondStream(
        ctx,
        "Write a limerick about coding Go bindings for Swift models.",
        fundament.WithTemperature(0.7),
    )
    if err != nil {
        log.Fatalf("respond stream: %v", err)
    }

    fmt.Println("Streaming response:")
    for chunk := range stream {
        if chunk.Err != nil {
            log.Fatalf("stream error: %v", chunk.Err)
        }
        fmt.Printf("%s ", chunk.Text)
        if chunk.Final {
            fmt.Println("\n-- end --")
        }
    }
    // Output example:
    // Streaming response:
    // A coder named Ray wrote some bindings one day He mixed Swift with Go Now his models all flow And Apple Intelligence came out to play
    // -- end --
}

```

--------------------------------

### Swift Session Lifecycle Functions

Source: https://github.com/domano/fundament/blob/master/PLAN.md

Provides functions for creating and destroying language model sessions. These functions wrap the initialization of LanguageModelSession, manage caching of SystemLanguageModel.default, and handle adapter management. They accept optional instruction strings and adapter identifiers.

```swift
func fundament_session_create(instructions: UnsafePointer<CChar>? = nil, adapterId: UnsafePointer<CChar>? = nil) -> SessionHandle?
func fundament_session_destroy(handle: SessionHandle?)
```

--------------------------------

### Swift Synchronous Prompt/Response Wrapper

Source: https://github.com/domano/fundament/blob/master/PLAN.md

Implements synchronous wrappers for the respond(to:) method using Task and CheckedContinuation to block until completion. Results are returned as UTF-8 buffers allocated via malloc for clean ownership transfer, with companion free functions provided.

```swift
func respond_sync(sessionHandle: SessionHandle, prompt: UnsafePointer<CChar>) -> UnsafeMutablePointer<CChar>?
func free_buffer(buffer: UnsafeMutablePointer<CChar>?)
```

--------------------------------

### Go Web Chat Server with Conversation History

Source: https://context7.com/domano/fundament/llms.txt

Implements a Go HTTP server for a web chat application. It manages conversation history using a slice of messages and interacts with a session from the fundament library to generate responses. The server renders an HTML template for the chat interface and handles message submissions and conversation resets.

```go
package main

import (
    "context"
    "embed"
    "fmt"
    "html/template"
    "log"
    "net/http"
    "strings"
    "sync"
    "time"
    "github.com/domano/fundament"
)

//go:embed templates/*.gohtml
var templateFS embed.FS

var pageTemplate = template.Must(template.ParseFS(templateFS, "templates/index.gohtml"))

type message struct {
    Role    string
    Content string
}

type chatServer struct {
    session *fundament.Session
    mu      sync.Mutex
    history []message
}

func (s *chatServer) handleChat(w http.ResponseWriter, r *http.Request) {
    if r.Method == http.MethodPost {
        if err := r.ParseForm(); err != nil {
            http.Error(w, "could not read form", http.StatusBadRequest)
            return
        }

        userMessage := strings.TrimSpace(r.FormValue("message"))
        if userMessage == "" {
            http.Redirect(w, r, r.URL.Path, http.StatusSeeOther)
            return
        }

        prompt := s.appendUserAndPrompt(userMessage)

        ctx, cancel := context.WithTimeout(r.Context(), 45*time.Second)
        defer cancel()

        resp, err := s.session.Respond(ctx, prompt)
        if err != nil {
            log.Printf("respond: %v", err)
            s.appendSystemMessage(fmt.Sprintf("Response error: %v", err))
        } else {
            s.appendAssistantMessage(resp.Text)
        }

        http.Redirect(w, r, r.URL.Path, http.StatusSeeOther)
        return
    }

    if r.Method == http.MethodGet && r.URL.Query().Get("reset") == "1" {
        s.resetConversation()
        http.Redirect(w, r, r.URL.Path, http.StatusSeeOther)
        return
    }

    if err := pageTemplate.Execute(w, struct {
        History []message
    }{
        History: s.historySnapshot(),
    }); err != nil {
        log.Printf("template execute: %v", err)
    }
}

func (s *chatServer) appendUserAndPrompt(content string) string {
    s.mu.Lock()
    defer s.mu.Unlock()
    s.history = append(s.history, message{Role: "user", Content: content})
    return buildPrompt(s.history)
}

func (s *chatServer) appendAssistantMessage(content string) {
    s.mu.Lock()
    defer s.mu.Unlock()
    s.history = append(s.history, message{Role: "assistant", Content: content})
}

func (s *chatServer) appendSystemMessage(content string) {
    s.mu.Lock()
    defer s.mu.Unlock()
    s.history = append(s.history, message{Role: "system", Content: content})
}

func (s *chatServer) resetConversation() {
    s.mu.Lock()
    defer s.mu.Unlock()
    s.history = []message{{Role: "assistant", Content: "Hi there! Ask me about anything."}}
}

func (s *chatServer) historySnapshot() []message {
    s.mu.Lock()
    defer s.mu.Unlock()
    out := make([]message, len(s.history))
    copy(out, s.history)
    return out
}

func buildPrompt(history []message) string {
    var b strings.Builder
    b.WriteString("Continue the conversation between the user and the assistant.\n\n")
    for _, msg := range history {
        switch msg.Role {
        case "assistant":
            b.WriteString("Assistant: ")
        case "system":
            b.WriteString("System: ")
        default:
            b.WriteString("User: ")
        }
        b.WriteString(msg.Content)
        b.WriteByte('\n')
    }
    b.WriteString("Assistant:")
    return b.String()
}

func main() {
    availability, err := fundament.CheckAvailability()
    if err != nil {
        log.Fatalf("check availability: %v", err)
    }
    if availability.State != fundament.AvailabilityReady {
        log.Fatalf("system language model unavailable: %s", availability)
    }

    session, err := fundament.NewSession(fundament.SessionOptions{
        Instructions: "You are a friendly assistant answering questions on a website chat widget. Keep responses short and helpful.",
    })
    if err != nil {
        log.Fatalf("new session: %v", err)
    }
    defer session.Close()

    server := &chatServer{
        session: session,
        history: []message{{Role: "assistant", Content: "Hi there! Ask me about anything."}},
    }

    mux := http.NewServeMux()
    mux.HandleFunc("/", server.handleChat)

    addr := ":8080"
    log.Printf("web chat example listening on http://localhost%s", addr)

    if err := http.ListenAndServe(addr, mux); err != nil {
        log.Fatalf("listen and serve: %v", err)
    }
}

// Run with: go run ./examples/webchat
// Then visit: http://localhost:8080

```

--------------------------------

### Go Context-Aware Swift Operations

Source: https://github.com/domano/fundament/blob/master/PLAN.md

Provides Go methods that execute Swift operations on background threads, supporting cancellation via contexts. This involves introducing cooperative cancellation mechanisms, such as using cancel tokens stored in Swift.

```go
func (s *Session) GenerateWithContext(ctx context.Context, prompt string) (string, error) {
    // ... implementation involving context cancellation and Swift token passing
    return "", nil
}
```

--------------------------------

### Automation Script for Swift Artefact Verification

Source: https://github.com/domano/fundament/blob/master/PLAN.md

An automation script designed to verify that the Swift artefact is built as a universal binary, supporting both arm64 and x86_64 architectures. This ensures compatibility with hosts using Rosetta translation.

```shell
#!/bin/bash

SWIFT_ARTEFACT="./swift/build/fundament.framework/fundament"

if lipo -info "$SWIFT_ARTEFACT" | grep -q "(for architecture x86_64)" && lipo -info "$SWIFT_ARTEFACT" | grep -q "(for architecture arm64)"; then
    echo "Swift artefact is a universal binary."
else
    echo "Error: Swift artefact is not a universal binary."
    exit 1
fi

exit 0
```

--------------------------------

### Go String to C.CString Conversion

Source: https://github.com/domano/fundament/blob/master/PLAN.md

Demonstrates the conversion of Go strings to C strings (`*C.char`) using `C.CString`. It emphasizes the necessity of freeing the allocated C string memory using the companion Swift free function to prevent memory leaks.

```go
goString := "example prompt"
cString := C.CString(goString)
defer C.free(unsafe.Pointer(cString)) // Freeing C string memory
// ... pass cString to C function
```

--------------------------------

### Check Fundament Model Availability in Go

Source: https://context7.com/domano/fundament/llms.txt

This Go code snippet demonstrates how to check the availability status of the on-device language model provided by the Fundament library. It handles different availability states and reasons for unavailability, such as device ineligibility or the model not being ready.

```go
package main

import (
    "fmt"
    "log"
    "github.com/domano/fundament"
)

func main() {
    availability, err := fundament.CheckAvailability()
    if err != nil {
        log.Fatalf("check availability: %v", err)
    }

    switch availability.State {
    case fundament.AvailabilityReady:
        fmt.Println("Model is ready")
    case fundament.AvailabilityUnavailable:
        switch availability.Reason {
        case fundament.AvailabilityReasonDeviceNotEligible:
            fmt.Println("Device lacks Apple Intelligence hardware")
        case fundament.AvailabilityReasonAppleIntelligenceDisabled:
            fmt.Println("User has not enabled Apple Intelligence")
        case fundament.AvailabilityReasonModelNotReady:
            fmt.Println("Model is still downloading")
        default:
            fmt.Println("Unknown unavailability reason")
        }
    default:
        fmt.Println("Availability state unknown")
    }
}
```

--------------------------------

### Clear Caches - Bash

Source: https://github.com/domano/fundament/blob/master/context/operations/build/toolchain.md

Clears local caches for Swift build artifacts, Go build cache, and Go module cache. This is useful after experiments to avoid stale artifacts.

```bash
rm -rf .swift-module-cache .swift-build-cache .gocache .gomodcache
```

--------------------------------

### Swift Streaming Callback Registration

Source: https://github.com/domano/fundament/blob/master/PLAN.md

Exposes a mechanism to register callbacks for streaming responses. This bridges Swift's ResponseStream to repeated callback invocations on the main actor, using a C-style function pointer for the callback.

```c
typedef void (*fundament_stream_cb)(const char *chunk, void *userdata);
void fundament_register_stream_callback(SessionHandle handle, fundament_stream_cb callback, void *userdata);
```

--------------------------------

### Go cgo Directives for Swift Artefact Linking

Source: https://github.com/domano/fundament/blob/master/PLAN.md

Defines cgo directives in Go to include generated headers and link with the Swift artefact. This specifies the necessary linker flags and library paths to connect the Go code with the compiled Swift code.

```go
#cgo LDFLAGS: -F${SRCDIR}/../swift/build -lfundament
#include "path/to/generated/fundament.h"
```

--------------------------------

### Swift Error Handling to C Compatibility

Source: https://github.com/domano/fundament/blob/master/PLAN.md

Normalizes Swift errors into structured C-compatible error objects, typically consisting of a code and a message. This may involve bridging NSError to dictionaries or using simple tagged unions for representation.

```c
typedef struct {
    int code;
    const char *message;
} CError;
CError fundament_get_last_error();
```

--------------------------------

### Go Error Translation from Swift Structs

Source: https://github.com/domano/fundament/blob/master/PLAN.md

Translates Swift error structures into Go `error` types. This includes performing type assertions to differentiate between availability errors and generation errors for more specific error handling in Go.

```go
type SwiftError struct {
    Code int
    Message string
}

func (se SwiftError) Error() string { return se.Message }

func convertSwiftErrorToGo(swiftErr SwiftError) error {
    // ... type assertion logic for availability vs generation errors
    return swiftErr
}
```