diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..f5f0ab3 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,15 @@ +## Summary + +- What changed: +- Why: + +## Related Issue + +- Refs # + +## Documentation Checklist + +- [ ] No real credentials, API keys, or secrets were added +- [ ] Updated links and Markdown anchors were checked +- [ ] API snippets were reviewed for endpoint/payload consistency +- [ ] Security-sensitive changes were reflected in `Security.md` if needed diff --git a/.github/workflows/docs-checks.yml b/.github/workflows/docs-checks.yml new file mode 100644 index 0000000..43ae1bb --- /dev/null +++ b/.github/workflows/docs-checks.yml @@ -0,0 +1,48 @@ +name: Docs Checks + +on: + pull_request: + paths: + - "**/*.md" + - ".github/workflows/docs-checks.yml" + push: + branches: + - main + paths: + - "**/*.md" + - ".github/workflows/docs-checks.yml" + +jobs: + link-check: + name: Link Check (blocking) + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + - name: Check markdown links + uses: lycheeverse/lychee-action@v2 + with: + args: >- + --no-progress + --verbose + --accept 200,401,429 + '**/*.md' + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + + markdown-lint: + name: Markdown Lint (non-blocking) + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + - name: Lint markdown + id: lint + continue-on-error: true + uses: DavidAnson/markdownlint-cli2-action@v18 + with: + globs: | + **/*.md + - name: Report non-blocking lint result + if: steps.lint.outcome == 'failure' + run: echo "Markdown lint found style issues (non-blocking)." diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..e92ce7c --- /dev/null +++ b/.gitignore @@ -0,0 +1,18 @@ +# macOS +.DS_Store + +# Editors +.idea/ +.vscode/ +*.swp + +# Python +__pycache__/ +*.pyc + +# Node +node_modules/ + +# Local env files +.env +.env.* diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..bac8b1c --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,46 @@ +# Repository Guidelines + +## Project Structure & Module Organization +This repository is documentation-first. + +- `README.md`: Primary project overview, links, and community entry points. +- `api/README.md`: API quickstart and request examples. +- `Security.md`: Vulnerability reporting and security policy. +- `antler_hackathon.md`: Event-specific reference material. +- Root metadata: `LICENSE`, `CODE_OF_CONDUCT.md`, `CNAME`. + +Keep new content close to its audience: API usage updates belong in `api/README.md`; organization or product messaging belongs in `README.md`. + +## Build, Test, and Development Commands +There is no in-repo build pipeline or automated test suite currently. + +- `rg -n "term" README.md api/README.md`: Find and update repeated wording quickly. +- `git status -sb`: Check branch state before and after edits. +- `git diff -- README.md api/README.md`: Review exactly what changed. +- `gh pr create --draft --fill`: Open a draft PR after pushing your branch. + +For docs changes, treat link validity, snippet accuracy, and formatting consistency as the release gate. + +## Coding Style & Naming Conventions +- Use clear Markdown headings (`##`, `###`) and short sections. +- Prefer concise, imperative prose and concrete examples. +- Use fenced code blocks for request snippets. +- Use lowercase, hyphenated branch names such as `42-api-doc-refresh`. +- Keep filenames descriptive and stable; avoid creating duplicate topic files. + +## Testing Guidelines +No formal coverage target is defined for this repository. + +- Manually verify API snippets before merging (request path, payload keys, auth header format). +- Confirm external links resolve and point to canonical docs. +- If you change example inputs/outputs, ensure narrative text matches code blocks. + +## Commit & Pull Request Guidelines +Recent history uses short, imperative subjects (for example, `Update README.md`, `Create CNAME`, `chore: ...`). Follow that pattern. + +- Commit format: `: `. +- Keep commits scoped to one topic (README, API docs, or policy update). +- PRs should include: purpose, changed files, linked issue (for example `Refs #42`), and any screenshots only when visual output changed. + +## Security & Configuration Tips +Never commit real credentials, tokens, or private endpoints. In examples, prefer placeholders (``, `${ACCESS_TOKEN}`) and reference secure reporting flow in `Security.md`. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..a632398 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,34 @@ +# Contributing + +Thanks for contributing to the Sublime repository. + +## Scope of This Repository + +This repository is documentation-first. Most contributions update: +- `README.md` +- `api/README.md` +- `antler_hackathon.md` +- `Security.md` + +## Branch and Commit Guidelines + +- Create a focused branch from `main`, for example: `42-docs-security-fix`. +- Keep commits small and scoped by topic. +- Use short, imperative commit messages: + - `Update API quickstart error handling` + - `chore: add docs CI` + +## Pull Request Checklist + +Before opening a PR: + +1. Confirm no real credentials, secrets, or tokens are present. +2. Validate links and anchors in edited Markdown files. +3. Ensure code snippets match the surrounding narrative. +4. Link the related issue in the PR body (for example: `Refs #42`). + +## Review Expectations + +- Prefer small PRs with a clear purpose. +- Include a brief summary of changed files and why. +- Add screenshots only when visual output meaningfully changes. diff --git a/README.md b/README.md index a9bd795..2b5e788 100644 --- a/README.md +++ b/README.md @@ -3,28 +3,6 @@ Behavior Change as a Service🌞 - - - [![Open Issues](https://img.shields.io/github/issues-raw/Subconscious-ai/sublime)](https://github.com/Subconscious-ai/sublime/issues) [![Release Notes](https://img.shields.io/badge/Release-Notes-blue)](https://docs.google.com/document/d/1BVZsVeQnk9AMC1zxN3pw_LPjOKrEtBVPXmmiqTDdzVs/edit#heading=h.cok4hkezrxg) [![Stars](https://img.shields.io/github/stars/Subconscious-ai/sublime)](https://star-history.com/#Subconscious-ai/sublime/) @@ -53,17 +31,21 @@ We poll the Representative Population to obtain answers for each respondent. Eac ### Reporting and Expansion Results are analyzed using state-of-the-art causal modeling techniques. The coefficients are used to estimate the preferences of subgroups in the population, create clusters, and report on which features of the product each persona prefers, and why. +## πŸ“š Documentation Map +- `api/README.md`: canonical quickstart for token setup and first API workflow. +- `antler_hackathon.md`: extended end-to-end walkthrough with deeper examples. +- `Security.md`: vulnerability disclosure policy for this repository. + ## πŸ’¬ Important Links -- [Getting Started!](https://github.com/Subconscious-ai/sublime/blob/API/api/README.md) -- [Demo, Get to Know Us!]() +- [Getting Started](api/README.md) - [Subconscious AI Wiki](https://docs.subconscious.ai/) - [API Playground](https://api.subconscious.ai/docs#/) -- [API Documentation]() +- [Security Policy](Security.md) ## Join Us! Please reach out, and join our community: - [Linkedin](https://www.linkedin.com/company/subconscious-ai/) -- [Twitter](https://www.linkedin.com/company/subconscious-ai/) +- [Twitter](https://twitter.com/subconscious_ai) - [Discord](https://discord.com/invite/3bgj4ZhABz) - [Email](press@subconscious.ai) @@ -73,11 +55,9 @@ Please reach out, and join our community: [](https://github.com/AidaE) [](https://github.com/aastroza) [](https://github.com/aviyashchin) - [](https://github.com/CodeJellee) [](https://github.com/Darcy667) [](https://github.com/JadeChan03) [](https://github.com/jessiezhang39) - [](https://github.com/MahdiJafari1) [](https://github.com/MahithaSann) [](https://github.com/mikefischer) [](https://github.com/rbolline) diff --git a/Security.md b/Security.md index 52b24af..b26813b 100644 --- a/Security.md +++ b/Security.md @@ -1,61 +1,33 @@ # Security Policy -## Reporting OSS Vulnerabilities +## Reporting Vulnerabilities -Subconscious is partnered with [huntr by Protect AI](https://huntr.com/) to provide -a bounty program for our open source projects. +If you discover a security issue in this repository or the examples it contains: -Please report security vulnerabilities associated with the Subconscious -open source projects by visiting the following link: +1. Submit a report via huntr: [https://huntr.com/bounties/disclose/](https://huntr.com/bounties/disclose/?target=https%3A%2F%2Fgithub.com%2FSubconscious-ai%2Fsublime&validSearch=true) +2. If huntr is unavailable or your report is time-sensitive, email: `security@subconscious.ai` -[https://huntr.com/bounties/disclose/](https://huntr.com/bounties/disclose/?target=https%3A%2F%2Fgithub.com%2FSubconscious-ai%2FSubconscious&validSearch=true) +Please include: +- A clear description of the issue and impact +- Reproduction steps or proof of concept +- Any affected files, links, or endpoints -Before reporting a vulnerability, please review: +Do not open public GitHub issues for unpatched security vulnerabilities. -1) In-Scope Targets and Out-of-Scope Targets below. -2) The [Subconscious-ai/Subconscious](https://python.Subconscious.com/docs/contributing/repo_structure) monorepo structure. -3) Subconscious [security guidelines](https://python.Subconscious.com/docs/security) to - understand what we consider to be a security vulnerability vs. developer - responsibility. +## Scope -### In-Scope Targets +This policy applies to content in this repository, including: +- Documentation and examples in `README.md`, `api/README.md`, and `antler_hackathon.md` +- Repository configuration and workflow files -The following packages and repositories are eligible for bug bounties: +Third-party services linked from this repository are out of scope unless the issue is caused by this repository's configuration or guidance. -- Subconscious-core -- Subconscious (see exceptions) -- Subconscious-community (see exceptions) -- langgraph -- langserve +## Secret Handling -### Out of Scope Targets +- Never commit real credentials, API keys, client secrets, or tokens. +- Use placeholders such as ``, `${SUBCONSCIOUS_TOKEN}`, and ``. +- If credentials are accidentally committed, rotate them immediately and submit a private security report. -All out of scope targets defined by huntr as well as: +## Responsible Disclosure -- **Subconscious-experimental**: This repository is for experimental code and is not - eligible for bug bounties, bug reports to it will be marked as interesting or waste of - time and published with no bounty attached. -- **tools**: Tools in either Subconscious or Subconscious-community are not eligible for bug - bounties. This includes the following directories - - Subconscious/tools - - Subconscious-community/tools - - Please review our [security guidelines](https://python.Subconscious.com/docs/security) - for more details, but generally tools interact with the real world. Developers are - expected to understand the security implications of their code and are responsible - for the security of their tools. -- Code documented with security notices. This will be decided done on a case by - case basis, but likely will not be eligible for a bounty as the code is already - documented with guidelines for developers that should be followed for making their - application secure. -- Any LangSmith related repositories or APIs see below. - -## Reporting LangSmith Vulnerabilities - -Please report security vulnerabilities associated with LangSmith by email to `security@Subconscious.dev`. - -- LangSmith site: https://smith.Subconscious.com -- SDK client: https://github.com/Subconscious-ai/langsmith-sdk - -### Other Security Concerns - -For any other security concerns, please contact us at `security@Subconscious.dev`. +We ask reporters to avoid public disclosure until the issue has been triaged and mitigated. We will acknowledge valid reports and coordinate remediation timelines. diff --git a/antler_hackathon.md b/antler_hackathon.md index 0f6048b..b3b2326 100644 --- a/antler_hackathon.md +++ b/antler_hackathon.md @@ -1,5 +1,7 @@ # Subconscious AI API Documentation +> Note: For the canonical quickstart, use `api/README.md`. This document is an extended reference with larger payload examples. + ## Welcome to Subconscious AI Subconscious AI redefines market research and product development with our innovative "Behaviour Change as a Service" model. Powered by advanced Large Language Models (LLMs), we enable businesses to conduct **Causal Market Research** with unmatched speed, quality, and ethical standards. Our platform delivers human-level reliability, guiding you through **Ideation**, **User Research**, and **Product Design**. Subconscious AI is your partner in understanding and influencing consumer behavior. @@ -115,7 +117,7 @@ response = httpx.post( Finally, we can now run our experiment! But first, we need to setup the data to run the experiment. -[//]: # (todo: the result of the previosu step should be used here to populate the attributes and levels) +[//]: # (TODO: use the output of the previous step to populate attributes and levels.) **Purpose:** Launches a conjoint analysis experiment to measure customer preferences and understand what drives behavior change. @@ -819,4 +821,4 @@ client.close() For additional support and detailed documentation, visit our resources or contact the Subconscious AI team. -**Happy researching! πŸš€** \ No newline at end of file +**Happy researching! πŸš€** diff --git a/api/README.md b/api/README.md index 8ff2e9e..c173cae 100644 --- a/api/README.md +++ b/api/README.md @@ -1,124 +1,137 @@ -# Getting Started! +# API Quickstart -Welcome to Subconscious AI, where we are redefining the landscape of market research and product development through our revolutionary "Behaviour Change as a Service" model. Utilizing the cutting-edge capabilities of Large Language Models (LLMs), we empower businesses to conduct Causal Market Research at an unprecedented pace, ensuring higher quality and ethical standards that surpass existing methodologies. With our commitment to human-level reliability, we stand at the forefront of guiding businesses through the critical steps of Ideation, User Research, and Product Design. Subconscious AI is not just a tool; it's a game-changer in understanding and influencing consumer behavior. +This is the canonical quickstart for running your first Subconscious AI experiment. ## Contents -- [Token Genration](https://github.com/Subconscious-ai/sublime/tree/API/api#step-1) -- [Prompt Generation](https://github.com/Subconscious-ai/sublime/tree/API/api#step-2) -- [Attributes & Levels](https://github.com/Subconscious-ai/sublime/tree/API/api#step-3) -- [Experiment & Results](https://github.com/Subconscious-ai/sublime/tree/API/api#step-4) +- [Step 1: Configure Access](#step-1-configure-access) +- [Step 2: Validate Prompt Causality](#step-2-validate-prompt-causality) +- [Step 3: Generate Attributes and Levels](#step-3-generate-attributes-and-levels) +- [Step 4: Run an Experiment](#step-4-run-an-experiment) +- [Step 5: Retrieve Results](#step-5-retrieve-results) -To simulate a causal market research, our system employs the following steps: -Design a Causal Prompt pertaining to the task -> Generate/Design attributes and their levels for the task -> Run the experiment -It is as simple as that! But before we start, remember to generate an API token for authorization purposes. So, +## API Versioning Notes -### Step 1 +Current public routes include both `/api/v1` and `/api/v2` endpoints. Use the endpoint path shown in each example and confirm details in the API Playground: [https://api.subconscious.ai/docs#/](https://api.subconscious.ai/docs#/). -``` - -conn = http.client.HTTPSConnection("auth.subconscious.ai") - -username = "" -password = "" -audience = "https://dev-5qhuxyzkmd8cku6i.us.auth0.com/api/v2/" -client_id = "MR5gS0QSe3boMNAtnR0t1t2ctNpzSHsd" -client_secret = "c1GGYa9U7gbX5dvDR8pRHvmmY067InwLi0HYZMNXzKg9zn99RvNf13ibsDzT2jKV" - -payload = f"grant_type=password&username={username}&password={password}&audience={audience}&scope=read:current_user&client_id={client_id}&client_secret={client_secret}" -headers = { 'content-type': "application/x-www-form-urlencoded" } - -conn.request("POST", "/oauth/token", payload, headers) -res = conn.getresponse() -data = json.loads(res.read().decode("utf-8")) - -``` - -Now, you can adjust your headers for all future calls to the API by adding the token we obtained above +## Step 1: Configure Access -``` -access_token=data['access_token'] -headers = {'Content-Type':'application/json',"Authorization": "Bearer %s" %access_token} - -``` - -The next step involves defining our causal prompt, which will serve as the foundation for setting up our task. To assist you in crafting this prompt, we offer a helpful 'check-causality' feature! - - -### Step 2 - -``` +Generate an access token at [https://app.subconscious.ai/settings](https://app.subconscious.ai/settings), then pass it as a bearer token. -prompt = "I would like to design a new electric car for the American markets" +```python +import httpx -response = requests.post("https://api.subconscious.ai/copilot/check-causality", headers=headers, params=params) -isCausal=json.loads(response.content) +BASE_URL = "https://api.subconscious.ai" +TOKEN = "${SUBCONSCIOUS_TOKEN}" # Set via environment variable or secret manager -if (not isCausal['is_causal']): - prompt = isCausal['suggestions'][0] +headers = { + "Authorization": f"Bearer {TOKEN}", + "Content-Type": "application/json", +} +client = httpx.Client(timeout=300.0) ``` -After selecting the prompt, we progress to constructing our attributes and their corresponding levels, which define the scale of each attribute. For instance, consider a car: "Price" could be an essential attribute, with a range from $10,000 to $100,000. You have the flexibility to access a more detailed set of levels through our API, or you can opt to define these levels yourself! - -### Step 3 - +## Step 2: Validate Prompt Causality + +Use `POST /api/v2/copilot/causality` to verify your research prompt. + +```python +why_prompt = ( + "I want to understand which laptop features most influence purchase decisions " + "for U.S. software engineers in 2026." +) + +try: + response = client.post( + f"{BASE_URL}/api/v2/copilot/causality", + headers=headers, + json={"why_prompt": why_prompt}, + ) + response.raise_for_status() + causality = response.json() +except httpx.HTTPStatusError as exc: + raise RuntimeError( + f"Causality check failed: {exc.response.status_code} {exc.response.text}" + ) from exc ``` -data={ - "idea": prompt, - "prompt_type": "product", - "num_levels": 3, - "max_length": 80, - "num_attrs": 3, - "model_type": "gpt4" -} - -response = requests.post("https://api.subconscious.ai/levels", headers=headers, json=data) -levels=json.loads(response.content) - - +## Step 3: Generate Attributes and Levels + +Use `POST /api/v1/product-attributes-levels` to generate candidate attributes. + +```python +try: + response = client.post( + f"{BASE_URL}/api/v1/product-attributes-levels", + headers=headers, + json={ + "why_prompt": why_prompt, + "attribute_count": 6, + "level_count": 4, + "country": "USA", + }, + ) + response.raise_for_status() + attributes = response.json().get("pre_cooked_attributes_and_levels_lookup", []) +except httpx.HTTPStatusError as exc: + raise RuntimeError( + f"Attribute generation failed: {exc.response.status_code} {exc.response.text}" + ) from exc ``` -Finally, we can now run our experiment! But first, we need to setup the data to run the experiment. - -### Step 4 - +## Step 4: Run an Experiment + +Use `POST /api/v1/experiments` with the generated attributes. + +```python +try: + response = client.post( + f"{BASE_URL}/api/v1/experiments", + headers=headers, + json={ + "why_prompt": why_prompt, + "country": "United States", + "year": "2026", + "pre_cooked_attributes_and_levels_lookup": attributes, + "number_of_respondents": 75, + "number_of_tasks_per_respondent": 10, + }, + ) + response.raise_for_status() + result = response.json() +except httpx.HTTPStatusError as exc: + raise RuntimeError( + f"Experiment creation failed: {exc.response.status_code} {exc.response.text}" + ) from exc ``` -exp_data={ - "number_of_attributes": 2, - "number_of_levels": 3, - "pre_cooked_attributes_and_levels_lookup": attributes, - "where_preamble": "United States", - "when_preamble": "2023", - "experimentor_why_question_type": "generic", - "experimentor_why_question_prompt": prompt, - "number_of_respondents": 75, - "number_of_tasks_per_respondent": 10, - "model_type": "default", - "levels_per_trait": 2, - "null_levels": True, - "max_length": 40, - "add_price_and_brand_attributes": False, - "hb_run_id": "", - "paper_data": [], - "is_private": False -} - -response = requests.post("https://api.subconscious.ai/experiments", headers=headers, json=exp_data) -experiment=json.loads(response.content) - +## Step 5: Retrieve Results + +Use `GET /api/v1/runs/artifact/{file_name}` after experiment processing completes. + +```python +wandb_run_name = result["wandb_run_name"] +file_name = f"Analytics_output_{wandb_run_name}" + +try: + response = client.get( + f"{BASE_URL}/api/v1/runs/artifact/{file_name}", + headers=headers, + ) + response.raise_for_status() + analytics = response.json() +except httpx.HTTPStatusError as exc: + raise RuntimeError( + f"Results retrieval failed: {exc.response.status_code} {exc.response.text}" + ) from exc ``` -The provided snippet gives a WandB (Weights & Biases) ID and run name, enabling you to visualize the experiment run and view the result parameters. These details can be easily accessed in your code by utilizing our runs endpoint. +## Troubleshooting -``` - -url = "https://api.subconscious.ai/runs/" + experiment['wandb_run_id'] -response = requests.post(url, headers=headers) -metrics = json.loads(response.content) +- `401 Unauthorized`: verify token validity and authorization header format. +- `422 Unprocessable Entity`: validate payload schema and required fields. +- Long-running requests: use client timeouts of at least 300 seconds for generation endpoints. -``` +## Extended Reference -That's it! You just ran your first experiment! This is also available in [Colab](https://colab.research.google.com/drive/19QQtXVb8qONgveSxYedbHfBrcZ5GS_Fn?usp=sharing). -You can further customize your experiment by consulting the Swagger UI documentation, accessible through the provided [link](https://api.subconscious.ai/docs#/). Should you have any additional questions or need further assistance, please feel free to contact us at ethicsboard@subconscious.ai. +For a longer, end-to-end walkthrough (including persona-rich payloads), use `antler_hackathon.md`.